# aidul23/mas-prompt-analytics architecture

> Architecture diagram of the GitHub repository aidul23/mas-prompt-analytics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aidul23/mas-prompt-analytics
- Repository: https://github.com/aidul23/mas-prompt-analytics

## Overview

The product is an interactive chatbot-trace analytics application: users import trace exports, explore predefined dashboard metrics, or ask questions answered by a multi-agent SLM workflow (with a single-model baseline and comparison mode). The map preserves data ingestion, analytics, chat, model management, saved conversations, and evaluation as distinct capabilities. Edges reflect documented wiring and indexed imports; unsampled implementation details are represented at supported directory paths, and evaluation internals are not inferred.

Main entry points: [`backend/app/mas/orchestrator.py`](https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/mas/orchestrator.py) (Multi-agent orchestrator), [`frontend/src/App.tsx`](https://github.com/aidul23/mas-prompt-analytics/blob/main/frontend/src/App.tsx) (App and routes), [`backend/app/api/main.py`](https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/api/main.py) (FastAPI app), [`backend/app/api/routes_chat.py`](https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/api/routes_chat.py) (Chat routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web interface"]
  node_webapp["App and routes<br/>[App.tsx]"]
  node_dashboard_ui["Dashboard UI<br/>[Dashboard.tsx]"]
  node_chat_ui["Chat UI<br/>[Chat.tsx]"]
  node_sources_ui["Data sources UI<br/>[DataSources.tsx]"]
  node_models_ui["Models UI<br/>[Models.tsx]"]
  node_frontend_api["API client<br/>[api.ts]"]
end

subgraph group_api["API services"]
  node_backend_api["FastAPI app<br/>[main.py]"]
  node_chat_routes["Chat routes<br/>[routes_chat.py]"]
  node_dashboard_routes["Dashboard routes"]
  node_data_routes["Data routes<br/>[routes_data.py]"]
  node_model_routes["Model routes<br/>[routes_models.py]"]
end

subgraph group_data["Trace data"]
  node_ingest["Import and sync<br/>[sources.py]"]
  node_build_data["Feature pipeline<br/>[pipeline.py]"]
  node_data_context["Analytics context<br/>[context.py]"]
  node_analytics_store[("Analytics database<br/>[store.py]")]
  node_dashboard_metrics["Dashboard metrics<br/>[dashboard.py]"]
end

subgraph group_chat["Question answering"]
  node_mas["Multi-agent orchestrator<br/>[orchestrator.py]"]
  node_query_agent["Query understanding"]
  node_agent_stages["Other agent stages"]
  node_baseline["Single-model baseline<br/>[single_model.py]"]
  node_chat_state[("Saved chats<br/>[chats.py]")]
  node_trace_state["Conversation traces<br/>[traces.py]"]
end

subgraph group_models["Models and evaluation"]
  node_ollama_client["Ollama client<br/>[llm.py]"]
  node_model_profiles["Model profiles<br/>[config.py]"]
  node_model_downloads["Model downloads<br/>[model_pulls.py]"]
  node_evaluation["Evaluation harness<br/>[run_eval.py]"]
end

node_user(("User"))
node_ollama["Ollama service"]

node_user -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_dashboard_ui
node_webapp -->|"routes to"| node_chat_ui
node_webapp -->|"routes to"| node_sources_ui
node_webapp -->|"routes to"| node_models_ui
node_dashboard_ui -->|"requests data"| node_frontend_api
node_chat_ui -->|"sends questions"| node_frontend_api
node_sources_ui -->|"manages sources"| node_frontend_api
node_models_ui -.->|"manages models"| node_frontend_api
node_frontend_api -->|"HTTP requests"| node_backend_api
node_backend_api -->|"registers"| node_chat_routes
node_backend_api -->|"registers"| node_dashboard_routes
node_backend_api -->|"registers"| node_data_routes
node_backend_api -->|"registers"| node_model_routes
node_chat_routes -->|"dispatches MAS"| node_mas
node_chat_routes -->|"dispatches baseline"| node_baseline
node_chat_routes -->|"loads and saves"| node_chat_state
node_chat_routes -->|"seeds and clears"| node_trace_state
node_data_routes -->|"manages sources"| node_ingest
node_ingest -->|"runs rebuilds"| node_build_data
node_build_data -->|"writes tables"| node_analytics_store
node_build_data -.->|"loads files"| node_ingest
node_dashboard_routes -->|"serves metrics"| node_dashboard_metrics
node_dashboard_metrics -->|"queries"| node_analytics_store
node_mas -->|"runs stages"| node_agent_stages
node_mas -->|"repairs query"| node_query_agent
node_query_agent -->|"grounds questions"| node_data_context
node_data_context -->|"reads values"| node_analytics_store
node_mas -->|"records turns"| node_trace_state
node_mas -->|"selects profile"| node_model_profiles
node_model_routes -->|"queries models"| node_ollama_client
node_model_routes -->|"manages downloads"| node_model_downloads
node_ollama_client -->|"calls API"| node_ollama
node_baseline -->|"requests completions"| node_ollama_client
node_evaluation -->|"evaluates answers"| node_mas
node_evaluation -->|"evaluates baseline"| node_baseline

click node_webapp "https://github.com/aidul23/mas-prompt-analytics/blob/main/frontend/src/App.tsx"
click node_dashboard_ui "https://github.com/aidul23/mas-prompt-analytics/blob/main/frontend/src/pages/Dashboard.tsx"
click node_chat_ui "https://github.com/aidul23/mas-prompt-analytics/blob/main/frontend/src/pages/Chat.tsx"
click node_sources_ui "https://github.com/aidul23/mas-prompt-analytics/blob/main/frontend/src/pages/DataSources.tsx"
click node_models_ui "https://github.com/aidul23/mas-prompt-analytics/blob/main/frontend/src/pages/Models.tsx"
click node_frontend_api "https://github.com/aidul23/mas-prompt-analytics/blob/main/frontend/src/api.ts"
click node_backend_api "https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/api/main.py"
click node_chat_routes "https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/api/routes_chat.py"
click node_dashboard_routes "https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/api/routes_dashboard.py"
click node_data_routes "https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/api/routes_data.py"
click node_model_routes "https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/api/routes_models.py"
click node_ingest "https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/data/sources.py"
click node_build_data "https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/data/pipeline.py"
click node_data_context "https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/data/context.py"
click node_analytics_store "https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/data/store.py"
click node_dashboard_metrics "https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/metrics/dashboard.py"
click node_mas "https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/mas/orchestrator.py"
click node_query_agent "https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/mas/agents/query_understanding.py"
click node_agent_stages "https://github.com/aidul23/mas-prompt-analytics/tree/main/backend/app/mas/agents"
click node_baseline "https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/baseline/single_model.py"
click node_chat_state "https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/chats.py"
click node_trace_state "https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/traces.py"
click node_ollama_client "https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/llm.py"
click node_model_profiles "https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/config.py"
click node_model_downloads "https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/model_pulls.py"
click node_evaluation "https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/eval/run_eval.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webapp,node_dashboard_ui,node_chat_ui,node_sources_ui,node_models_ui,node_frontend_api,node_user toneBlue
class node_backend_api,node_chat_routes,node_dashboard_routes,node_data_routes,node_model_routes toneAmber
class node_ingest,node_build_data,node_data_context,node_analytics_store,node_dashboard_metrics toneMint
class node_mas,node_query_agent,node_agent_stages,node_baseline,node_chat_state,node_trace_state toneRose
class node_ollama_client,node_model_profiles,node_model_downloads,node_evaluation,node_ollama toneIndigo
```

## Components

### Web interface

- [App and routes](https://github.com/aidul23/mas-prompt-analytics/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Dashboard UI](https://github.com/aidul23/mas-prompt-analytics/blob/main/frontend/src/pages/Dashboard.tsx): `frontend/src/pages/Dashboard.tsx`
- [Chat UI](https://github.com/aidul23/mas-prompt-analytics/blob/main/frontend/src/pages/Chat.tsx): `frontend/src/pages/Chat.tsx`
- [Data sources UI](https://github.com/aidul23/mas-prompt-analytics/blob/main/frontend/src/pages/DataSources.tsx): `frontend/src/pages/DataSources.tsx`
- [Models UI](https://github.com/aidul23/mas-prompt-analytics/blob/main/frontend/src/pages/Models.tsx): `frontend/src/pages/Models.tsx`
- [API client](https://github.com/aidul23/mas-prompt-analytics/blob/main/frontend/src/api.ts): `frontend/src/api.ts`

### API services

- [FastAPI app](https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/api/main.py): `backend/app/api/main.py`
- [Chat routes](https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/api/routes_chat.py): `backend/app/api/routes_chat.py`
- [Dashboard routes](https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/api/routes_dashboard.py): `backend/app/api/routes_dashboard.py`
- [Data routes](https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/api/routes_data.py): `backend/app/api/routes_data.py`
- [Model routes](https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/api/routes_models.py): `backend/app/api/routes_models.py`

### Trace data

- [Import and sync](https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/data/sources.py): `backend/app/data/sources.py`
- [Feature pipeline](https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/data/pipeline.py): `backend/app/data/pipeline.py`
- [Analytics context](https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/data/context.py): `backend/app/data/context.py`
- [Analytics database](https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/data/store.py): `backend/app/data/store.py`
- [Dashboard metrics](https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/metrics/dashboard.py): `backend/app/metrics/dashboard.py`

### Question answering

- [Multi-agent orchestrator](https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/mas/orchestrator.py): `backend/app/mas/orchestrator.py`
- [Query understanding](https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/mas/agents/query_understanding.py): `backend/app/mas/agents/query_understanding.py`
- [Other agent stages](https://github.com/aidul23/mas-prompt-analytics/tree/main/backend/app/mas/agents): `backend/app/mas/agents`
- [Single-model baseline](https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/baseline/single_model.py): `backend/app/baseline/single_model.py`
- [Saved chats](https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/chats.py): `backend/app/chats.py`
- [Conversation traces](https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/traces.py): `backend/app/traces.py`

### Models and evaluation

- [Ollama client](https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/llm.py): `backend/app/llm.py`
- [Model profiles](https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/config.py): `backend/app/config.py`
- [Model downloads](https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/app/model_pulls.py): `backend/app/model_pulls.py`
- [Evaluation harness](https://github.com/aidul23/mas-prompt-analytics/blob/main/backend/eval/run_eval.py): `backend/eval/run_eval.py`

### Other components

- **User**
- **Ollama service**

## Connections

- User → App and routes: uses (evidence: `frontend/src/App.tsx`)
- App and routes → Dashboard UI: routes to (evidence: `frontend/src/App.tsx`)
- App and routes → Chat UI: routes to (evidence: `frontend/src/App.tsx`)
- App and routes → Data sources UI: routes to (evidence: `frontend/src/App.tsx`)
- App and routes → Models UI: routes to (evidence: `frontend/src/App.tsx`)
- Dashboard UI → API client: requests data (evidence: `frontend/src/pages/Dashboard.tsx`)
- Chat UI → API client: sends questions (evidence: `frontend/src/pages/Chat.tsx`)
- Data sources UI → API client: manages sources (evidence: `frontend/src/pages/DataSources.tsx`)
- Models UI → API client: manages models
- API client → FastAPI app: HTTP requests (evidence: `README.md`)
- FastAPI app → Chat routes: registers (evidence: `backend/app/api/main.py`)
- FastAPI app → Dashboard routes: registers (evidence: `backend/app/api/main.py`)
- FastAPI app → Data routes: registers (evidence: `backend/app/api/main.py`)
- FastAPI app → Model routes: registers (evidence: `backend/app/api/main.py`)
- Chat routes → Multi-agent orchestrator: dispatches MAS (evidence: `backend/app/api/routes_chat.py`)
- Chat routes → Single-model baseline: dispatches baseline (evidence: `backend/app/api/routes_chat.py`)
- Chat routes → Saved chats: loads and saves (evidence: `backend/app/api/routes_chat.py`)
- Chat routes → Conversation traces: seeds and clears (evidence: `backend/app/api/routes_chat.py`)
- Data routes → Import and sync: manages sources (evidence: `backend/app/api/routes_data.py`)
- Import and sync → Feature pipeline: runs rebuilds (evidence: `backend/app/data/sources.py`)
- Feature pipeline → Analytics database: writes tables (evidence: `backend/app/data/pipeline.py`)
- Feature pipeline → Import and sync: loads files (evidence: `backend/app/data/sources.py`)
- Dashboard routes → Dashboard metrics: serves metrics (evidence: `backend/app/api/routes_dashboard.py`)
- Dashboard metrics → Analytics database: queries (evidence: `backend/app/metrics/dashboard.py`)
- Multi-agent orchestrator → Other agent stages: runs stages (evidence: `backend/app/mas/orchestrator.py`)
- Multi-agent orchestrator → Query understanding: repairs query (evidence: `backend/app/mas/orchestrator.py`)
- Query understanding → Analytics context: grounds questions (evidence: `backend/app/mas/agents/query_understanding.py`)
- Analytics context → Analytics database: reads values (evidence: `backend/app/data/context.py`)
- Multi-agent orchestrator → Conversation traces: records turns (evidence: `backend/app/mas/orchestrator.py`)
- Multi-agent orchestrator → Model profiles: selects profile (evidence: `backend/app/mas/orchestrator.py`)
- Model routes → Ollama client: queries models (evidence: `backend/app/api/routes_models.py`)
- Model routes → Model downloads: manages downloads (evidence: `backend/app/api/routes_models.py`)
- Ollama client → Ollama service: calls API (evidence: `backend/app/llm.py`)
- Single-model baseline → Ollama client: requests completions (evidence: `backend/app/baseline/single_model.py`)
- Evaluation harness → Multi-agent orchestrator: evaluates answers (evidence: `backend/eval/run_eval.py`)
- Evaluation harness → Single-model baseline: evaluates baseline (evidence: `backend/eval/run_eval.py`)
