# vaish1101/enterprise-analytics-copilot architecture

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

- Interactive diagram: https://gitdiagram.com/vaish1101/enterprise-analytics-copilot
- Repository: https://github.com/vaish1101/enterprise-analytics-copilot

## Overview

Enterprise Analytics Copilot serves governed KPI investigations: a user asks a question, the web client submits it to the API, and a bounded backend workflow plans the request, performs deterministic analysis and/or evidence retrieval, synthesizes claims, verifies them, and presents a supported answer or a boundary. The graph also shows the interface’s result-view layer and major documented capabilities. Backend wiring is better evidenced than the frontend transport details; optional or unverified links are marked dashed.

Main entry points: [`src/orchestration/graph.py`](https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/orchestration/graph.py) (Workflow orchestrator), [`src/retrieval/retrieve.py`](https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/retrieval/retrieve.py) (Evidence retrieval), [`frontend/src/App.tsx`](https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/frontend/src/App.tsx) (Experience app), [`src/api/service.py`](https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/api/service.py) (Graph service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Product interface"]
  node_app["Experience app<br/>[App.tsx]"]
  node_landing["Question interface<br/>[Landing.tsx]"]
  node_resultview["Result view model<br/>[viewModel.ts]"]
  node_workspace["Analysis workspace<br/>[Workspace.tsx]"]
  node_scene["Workflow illustration<br/>[PrecisionEngine.ts]"]
end

subgraph group_api["API boundary"]
  node_apiapp["HTTP application<br/>[app.py]"]
  node_routes["API routes"]
  node_service["Graph service<br/>[service.py]"]
end

subgraph group_workflow["Analysis workflow"]
  node_planner["Question planner<br/>[planner.py]"]
  node_graph["Workflow orchestrator<br/>[graph.py]"]
  node_synthesis["Structured synthesis<br/>[openai_provider.py]"]
  node_verification["Independent verifier<br/>[verifier.py]"]
  node_bounded["Bounded agent runtime<br/>[runtime.py]"]
end

subgraph group_evidence["Evidence and analytics"]
  node_analytics["Governed analytics<br/>[executor.py]"]
  node_calculations["Deterministic calculations<br/>[calculations.py]"]
  node_retrieval["Evidence retrieval<br/>[retrieve.py]"]
  node_retrievalquery["Governed query<br/>[query.py]"]
  node_embedding["Dense embeddings<br/>[embeddings.py]"]
  node_vectorstore[("Vector store<br/>[vector_store.py]")]
end

subgraph group_contracts["Contracts and state"]
  node_catalog["Metric contracts<br/>[models.py]"]
  node_planmodels["Plan contracts<br/>[models.py]"]
  node_retrievalmodels["Evidence contracts<br/>[models.py]"]
  node_checkpoint[("Workflow checkpoints")]
end

node_user(("Business user"))
node_browser(("Browser"))

node_user -->|"asks"| node_landing
node_landing -->|"submits question"| node_app
node_app -->|"builds result"| node_resultview
node_app -->|"renders"| node_workspace
node_app -.->|"shows workflow"| node_scene
node_app -.->|"sends request"| node_apiapp
node_browser -.->|"calls HTTP API"| node_apiapp
node_apiapp -->|"registers"| node_routes
node_routes -->|"delegates query"| node_service
node_service -->|"invokes workflow"| node_graph
node_graph -->|"plans question"| node_planner
node_planner -->|"uses contracts"| node_catalog
node_graph -->|"executes analytics"| node_analytics
node_analytics -->|"calculates metrics"| node_calculations
node_graph -->|"retrieves evidence"| node_retrieval
node_retrieval -->|"builds query"| node_retrievalquery
node_retrieval -->|"embeds query"| node_embedding
node_retrieval -->|"searches vectors"| node_vectorstore
node_retrieval -->|"returns evidence"| node_retrievalmodels
node_graph -->|"requests draft"| node_synthesis
node_graph -->|"checks claims"| node_verification
node_graph -->|"saves workflow state"| node_checkpoint
node_bounded -->|"uses workflow"| node_graph
node_graph -->|"uses plan contract"| node_planmodels
node_service -->|"configures retrieval"| node_retrieval
node_service -->|"maps evidence"| node_retrievalmodels

click node_app "https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/frontend/src/App.tsx"
click node_landing "https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/frontend/src/landing/Landing.tsx"
click node_resultview "https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/frontend/src/lib/viewModel.ts"
click node_workspace "https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/frontend/src/workspace/Workspace.tsx"
click node_scene "https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/frontend/src/scene/PrecisionEngine.ts"
click node_apiapp "https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/api/app.py"
click node_routes "https://github.com/vaish1101/enterprise-analytics-copilot/tree/main/src/api/routes"
click node_service "https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/api/service.py"
click node_planner "https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/planning/planner.py"
click node_graph "https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/orchestration/graph.py"
click node_synthesis "https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/llm/openai_provider.py"
click node_verification "https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/orchestration/verifier.py"
click node_bounded "https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/bounded_agents/runtime.py"
click node_analytics "https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/analytics/executor.py"
click node_calculations "https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/analytics/calculations.py"
click node_retrieval "https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/retrieval/retrieve.py"
click node_retrievalquery "https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/retrieval/query.py"
click node_embedding "https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/retrieval/embeddings.py"
click node_vectorstore "https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/retrieval/vector_store.py"
click node_catalog "https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/schemas/models.py"
click node_planmodels "https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/planning/models.py"
click node_retrievalmodels "https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/retrieval/models.py"
click node_checkpoint "https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/persistence/checkpoint_store.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_app,node_landing,node_resultview,node_workspace,node_scene,node_user,node_browser toneBlue
class node_apiapp,node_routes,node_service toneAmber
class node_planner,node_graph,node_synthesis,node_verification,node_bounded toneMint
class node_analytics,node_calculations,node_retrieval,node_retrievalquery,node_embedding,node_vectorstore toneRose
class node_catalog,node_planmodels,node_retrievalmodels,node_checkpoint toneIndigo
```

## Components

### Product interface

- [Experience app](https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Question interface](https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/frontend/src/landing/Landing.tsx): `frontend/src/landing/Landing.tsx`
- [Result view model](https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/frontend/src/lib/viewModel.ts): `frontend/src/lib/viewModel.ts`
- [Analysis workspace](https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/frontend/src/workspace/Workspace.tsx): `frontend/src/workspace/Workspace.tsx`
- [Workflow illustration](https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/frontend/src/scene/PrecisionEngine.ts): `frontend/src/scene/PrecisionEngine.ts`

### API boundary

- [HTTP application](https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/api/app.py): `src/api/app.py`
- [API routes](https://github.com/vaish1101/enterprise-analytics-copilot/tree/main/src/api/routes): `src/api/routes`
- [Graph service](https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/api/service.py): `src/api/service.py`

### Analysis workflow

- [Question planner](https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/planning/planner.py): `src/planning/planner.py`
- [Workflow orchestrator](https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/orchestration/graph.py): `src/orchestration/graph.py`
- [Structured synthesis](https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/llm/openai_provider.py): `src/llm/openai_provider.py`
- [Independent verifier](https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/orchestration/verifier.py): `src/orchestration/verifier.py`
- [Bounded agent runtime](https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/bounded_agents/runtime.py): `src/bounded_agents/runtime.py`

### Evidence and analytics

- [Governed analytics](https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/analytics/executor.py): `src/analytics/executor.py`
- [Deterministic calculations](https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/analytics/calculations.py): `src/analytics/calculations.py`
- [Evidence retrieval](https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/retrieval/retrieve.py): `src/retrieval/retrieve.py`
- [Governed query](https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/retrieval/query.py): `src/retrieval/query.py`
- [Dense embeddings](https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/retrieval/embeddings.py): `src/retrieval/embeddings.py`
- [Vector store](https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/retrieval/vector_store.py): `src/retrieval/vector_store.py`

### Contracts and state

- [Metric contracts](https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/schemas/models.py): `src/schemas/models.py`
- [Plan contracts](https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/planning/models.py): `src/planning/models.py`
- [Evidence contracts](https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/retrieval/models.py): `src/retrieval/models.py`
- [Workflow checkpoints](https://github.com/vaish1101/enterprise-analytics-copilot/blob/main/src/persistence/checkpoint_store.py): `src/persistence/checkpoint_store.py`

### Other components

- **Business user**
- **Browser**

## Connections

- Business user → Question interface: asks (evidence: `README.md`)
- Question interface → Experience app: submits question (evidence: `frontend/src/App.tsx`)
- Experience app → Result view model: builds result (evidence: `frontend/src/App.tsx`)
- Experience app → Analysis workspace: renders (evidence: `frontend/src/App.tsx`)
- Experience app → Workflow illustration: shows workflow (evidence: `frontend/src/App.tsx`)
- Experience app → HTTP application: sends request
- Browser → HTTP application: calls HTTP API
- HTTP application → API routes: registers (evidence: `src/api/app.py`)
- API routes → Graph service: delegates query (evidence: `src/api/routes/query.py`)
- Graph service → Workflow orchestrator: invokes workflow (evidence: `src/api/service.py`)
- Workflow orchestrator → Question planner: plans question (evidence: `src/orchestration/graph.py`)
- Question planner → Metric contracts: uses contracts (evidence: `src/planning/planner.py`)
- Workflow orchestrator → Governed analytics: executes analytics
- Governed analytics → Deterministic calculations: calculates metrics (evidence: `src/analytics/executor.py`)
- Workflow orchestrator → Evidence retrieval: retrieves evidence (evidence: `src/orchestration/graph.py`)
- Evidence retrieval → Governed query: builds query (evidence: `src/retrieval/retrieve.py`)
- Evidence retrieval → Dense embeddings: embeds query (evidence: `src/retrieval/retrieve.py`)
- Evidence retrieval → Vector store: searches vectors (evidence: `src/retrieval/retrieve.py`)
- Evidence retrieval → Evidence contracts: returns evidence (evidence: `src/retrieval/retrieve.py`)
- Workflow orchestrator → Structured synthesis: requests draft (evidence: `src/orchestration/graph.py`)
- Workflow orchestrator → Independent verifier: checks claims (evidence: `src/orchestration/graph.py`)
- Workflow orchestrator → Workflow checkpoints: saves workflow state (evidence: `src/orchestration/graph.py`)
- Bounded agent runtime → Workflow orchestrator: uses workflow (evidence: `src/bounded_agents/runtime.py`)
- Workflow orchestrator → Plan contracts: uses plan contract (evidence: `src/orchestration/graph.py`)
- Graph service → Evidence retrieval: configures retrieval (evidence: `src/api/service.py`)
- Graph service → Evidence contracts: maps evidence (evidence: `src/api/service.py`)
