docs/architecture.md

# Architecture

RAG QA Command Center is a self-contained Streamlit application for reviewing offline RAG evaluation logs. It is intentionally deterministic: packaged CSV artifacts are loaded locally, validated at startup, transformed into review views, and exported without external services.

## Runtime flow

```text
app.py
  -> src.dashboard.CommandCenterApp
       -> src.data.DataRepository.load()
       -> src.data.validate_bundle()
       -> src.analytics.*
       -> src.charts.*
       -> src.views.*
       -> Streamlit UI / downloads
```

## Main layers

| Layer | Files | Responsibility |
|---|---|---|
| Entry point | `app.py` | Thin launcher only. |
| Controller | `src/dashboard.py` | Page orchestration, filters, context construction, and shared rendering helpers. |
| View mixins | `src/views/` | One focused module per tab/page. |
| Data access | `src/data.py` | CSV discovery, loading, standardization, schema and integrity validation. |
| Analytics | `src/analytics.py` | Metrics, risk slices, retrieval outcomes, config scoring, policy curves, trace queues. |
| Charts | `src/charts.py` | Plotly figure factories. |
| UI primitives | `src/ui.py` | Reusable Streamlit/HTML components with controlled markup. |
| State models | `src/app_state.py`, `src/models.py` | Typed app context and runtime settings. |
| Tests | `tests/` | Data contracts, numeric analytics regressions, Streamlit smoke coverage, project hygiene, and release checks. |

## Design choices

- **Separation of concerns:** data loading, analytics, charts, and UI pages are separated.
- **Thin entrypoint:** `app.py` only starts the application.
- **View composition:** the main controller inherits focused view mixins instead of growing a monolithic UI file.
- **Fail-fast data contract:** packaged tables are validated before the UI renders, including key presence, references, strict numeric conversion, metric ranges, relevance flags, and rank sanity checks.
- **Offline-first review:** the app reviews fixed evaluation artifacts and does not call live LLMs.

## What this is not

This project is not a live RAG serving platform. It does not include online ingestion, vector indexing, authentication, scheduled jobs, alerting, or production incident automation.