# rahulramachandran-labs/reconmind architecture

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

- Interactive diagram: https://gitdiagram.com/rahulramachandran-labs/reconmind
- Repository: https://github.com/rahulramachandran-labs/reconmind

## Overview

ReconMind is an incident copilot for diagnosing data-pipeline anomalies. A user initiates a scan or asks a question in the web app; the API runs a multi-agent investigation that gathers read-only warehouse evidence, checks domain-specific failure modes, retrieves runbooks and past incidents, and produces findings and a report. Serious or uncertain cases pause for human review. The app also exposes volume dashboards, incident history, verification, and run traces. Edges reflect README statements and the supplied source excerpts/index; unsampled implementation details are not assumed.

Main entry points: [`app/main.py`](https://github.com/rahulramachandran-labs/reconmind/blob/main/app/main.py) (FastAPI App), [`app/agents/service.py`](https://github.com/rahulramachandran-labs/reconmind/blob/main/app/agents/service.py) (Investigation Service), [`app/agents/graph.py`](https://github.com/rahulramachandran-labs/reconmind/blob/main/app/agents/graph.py) (Agent Graph), [`app/api/knowledge.py`](https://github.com/rahulramachandran-labs/reconmind/blob/main/app/api/knowledge.py) (Knowledge API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experience"]
  node_web["ReconMind Web<br/>[page.tsx]"]
  node_incident_views["Incident Views<br/>[page.tsx]"]
  node_review_view["Review Queue<br/>[page.tsx]"]
  node_verify_view["Anomaly Verification<br/>[page.tsx]"]
  node_trace_views["Trace Views<br/>[page.tsx]"]
end

subgraph group_api["API and Runs"]
  node_api_app["FastAPI App<br/>[main.py]"]
  node_agent_api["Agent API<br/>[agents.py]"]
  node_knowledge_api["Knowledge API<br/>[knowledge.py]"]
  node_dashboard_api["Dashboard API<br/>[dashboard.py]"]
  node_investigation_service["Investigation Service<br/>[service.py]"]
end

subgraph group_investigation["Investigation"]
  node_agent_graph["Agent Graph<br/>[graph.py]"]
  node_planner_specialists["Planner and Specialists<br/>[specialists.py]"]
  node_domain_adapter["Retail Recon Adapter<br/>[adapter.py]"]
  node_domain_checks["Recon Checks<br/>[checks.py]"]
  node_human_review["Human Sign-off<br/>[review.py]"]
end

subgraph group_evidence["Evidence and Retrieval"]
  node_toolbox["MCP Tool Access<br/>[mcp_toolbox.py]"]
  node_warehouse_mcp["Warehouse Metadata MCP<br/>[server.py]"]
  node_orchestration_mcp["Orchestration Metadata MCP<br/>[server.py]"]
  node_retrieval["Hybrid Retrieval<br/>[service.py]"]
  node_rag_answer["RAG Answering<br/>[answer.py]"]
end

subgraph group_platform["State and Observability"]
  node_llm["LLM Provider Chain<br/>[providers.py]"]
  node_run_store[("Run and Incident Store")]
  node_sessions[("Chat Sessions<br/>[sessions.py]")]
  node_postgres[("PostgreSQL<br/>[models.py]")]
  node_tracing["Run Tracing<br/>[tracer.py]"]
end

node_user(("Analyst / Reviewer"))

node_user -->|"uses"| node_web
node_web -.->|"requests"| node_api_app
node_user -->|"browses incidents"| node_incident_views
node_user -->|"reviews findings"| node_review_view
node_user -->|"verifies anomalies"| node_verify_view
node_user -->|"inspects runs"| node_trace_views
node_api_app -->|"mounts router"| node_agent_api
node_api_app -->|"mounts router"| node_knowledge_api
node_api_app -->|"mounts router"| node_dashboard_api
node_agent_api -->|"invokes"| node_investigation_service
node_knowledge_api -->|"searches"| node_retrieval
node_knowledge_api -->|"answers with"| node_rag_answer
node_investigation_service -->|"runs"| node_agent_graph
node_agent_graph -->|"dispatches"| node_planner_specialists
node_planner_specialists -->|"uses domain contract"| node_domain_adapter
node_domain_adapter -.->|"performs checks"| node_domain_checks
node_investigation_service -->|"pauses for review"| node_human_review
node_agent_graph -->|"gathers evidence"| node_toolbox
node_toolbox -->|"calls tools"| node_warehouse_mcp
node_toolbox -->|"calls tools"| node_orchestration_mcp
node_agent_graph -->|"retrieves context"| node_retrieval
node_rag_answer -->|"searches"| node_retrieval
node_rag_answer -->|"generates answer"| node_llm
node_planner_specialists -->|"analyzes findings"| node_llm
node_api_app -->|"initializes"| node_llm
node_investigation_service -.->|"persists run data"| node_run_store
node_api_app -->|"selects session store"| node_sessions
node_sessions -->|"stores sessions"| node_postgres
node_investigation_service -->|"records run steps"| node_tracing
node_tracing -->|"writes steps"| node_postgres

click node_web "https://github.com/rahulramachandran-labs/reconmind/blob/main/frontend/src/app/page.tsx"
click node_incident_views "https://github.com/rahulramachandran-labs/reconmind/blob/main/frontend/src/app/incidents/page.tsx"
click node_review_view "https://github.com/rahulramachandran-labs/reconmind/blob/main/frontend/src/app/review/page.tsx"
click node_verify_view "https://github.com/rahulramachandran-labs/reconmind/blob/main/frontend/src/app/verify/page.tsx"
click node_trace_views "https://github.com/rahulramachandran-labs/reconmind/blob/main/frontend/src/app/traces/page.tsx"
click node_api_app "https://github.com/rahulramachandran-labs/reconmind/blob/main/app/main.py"
click node_agent_api "https://github.com/rahulramachandran-labs/reconmind/blob/main/app/api/agents.py"
click node_knowledge_api "https://github.com/rahulramachandran-labs/reconmind/blob/main/app/api/knowledge.py"
click node_dashboard_api "https://github.com/rahulramachandran-labs/reconmind/blob/main/app/api/dashboard.py"
click node_investigation_service "https://github.com/rahulramachandran-labs/reconmind/blob/main/app/agents/service.py"
click node_agent_graph "https://github.com/rahulramachandran-labs/reconmind/blob/main/app/agents/graph.py"
click node_planner_specialists "https://github.com/rahulramachandran-labs/reconmind/blob/main/app/agents/specialists.py"
click node_domain_adapter "https://github.com/rahulramachandran-labs/reconmind/blob/main/app/domain/retail_recon/adapter.py"
click node_domain_checks "https://github.com/rahulramachandran-labs/reconmind/blob/main/app/domain/retail_recon/checks.py"
click node_human_review "https://github.com/rahulramachandran-labs/reconmind/blob/main/app/agents/review.py"
click node_toolbox "https://github.com/rahulramachandran-labs/reconmind/blob/main/app/tools/mcp_toolbox.py"
click node_warehouse_mcp "https://github.com/rahulramachandran-labs/reconmind/blob/main/mcp_servers/warehouse_metadata/server.py"
click node_orchestration_mcp "https://github.com/rahulramachandran-labs/reconmind/blob/main/mcp_servers/orchestration_metadata/server.py"
click node_retrieval "https://github.com/rahulramachandran-labs/reconmind/blob/main/app/retrieval/service.py"
click node_rag_answer "https://github.com/rahulramachandran-labs/reconmind/blob/main/app/rag/answer.py"
click node_llm "https://github.com/rahulramachandran-labs/reconmind/blob/main/app/llm/providers.py"
click node_run_store "https://github.com/rahulramachandran-labs/reconmind/tree/main/app/agents/store"
click node_sessions "https://github.com/rahulramachandran-labs/reconmind/blob/main/app/memory/sessions.py"
click node_postgres "https://github.com/rahulramachandran-labs/reconmind/blob/main/app/db/models.py"
click node_tracing "https://github.com/rahulramachandran-labs/reconmind/blob/main/app/observability/tracer.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_web,node_incident_views,node_review_view,node_verify_view,node_trace_views,node_user toneBlue
class node_api_app,node_agent_api,node_knowledge_api,node_dashboard_api,node_investigation_service toneAmber
class node_agent_graph,node_planner_specialists,node_domain_adapter,node_domain_checks,node_human_review toneMint
class node_toolbox,node_warehouse_mcp,node_orchestration_mcp,node_retrieval,node_rag_answer toneRose
class node_llm,node_run_store,node_sessions,node_postgres,node_tracing toneIndigo
```

## Components

### User Experience

- [ReconMind Web](https://github.com/rahulramachandran-labs/reconmind/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Incident Views](https://github.com/rahulramachandran-labs/reconmind/blob/main/frontend/src/app/incidents/page.tsx): `frontend/src/app/incidents/page.tsx`
- [Review Queue](https://github.com/rahulramachandran-labs/reconmind/blob/main/frontend/src/app/review/page.tsx): `frontend/src/app/review/page.tsx`
- [Anomaly Verification](https://github.com/rahulramachandran-labs/reconmind/blob/main/frontend/src/app/verify/page.tsx): `frontend/src/app/verify/page.tsx`
- [Trace Views](https://github.com/rahulramachandran-labs/reconmind/blob/main/frontend/src/app/traces/page.tsx): `frontend/src/app/traces/page.tsx`

### API and Runs

- [FastAPI App](https://github.com/rahulramachandran-labs/reconmind/blob/main/app/main.py): `app/main.py`
- [Agent API](https://github.com/rahulramachandran-labs/reconmind/blob/main/app/api/agents.py): `app/api/agents.py`
- [Knowledge API](https://github.com/rahulramachandran-labs/reconmind/blob/main/app/api/knowledge.py): `app/api/knowledge.py`
- [Dashboard API](https://github.com/rahulramachandran-labs/reconmind/blob/main/app/api/dashboard.py): `app/api/dashboard.py`
- [Investigation Service](https://github.com/rahulramachandran-labs/reconmind/blob/main/app/agents/service.py): `app/agents/service.py`

### Investigation

- [Agent Graph](https://github.com/rahulramachandran-labs/reconmind/blob/main/app/agents/graph.py): `app/agents/graph.py`
- [Planner and Specialists](https://github.com/rahulramachandran-labs/reconmind/blob/main/app/agents/specialists.py): `app/agents/specialists.py`
- [Retail Recon Adapter](https://github.com/rahulramachandran-labs/reconmind/blob/main/app/domain/retail_recon/adapter.py): `app/domain/retail_recon/adapter.py`
- [Recon Checks](https://github.com/rahulramachandran-labs/reconmind/blob/main/app/domain/retail_recon/checks.py): `app/domain/retail_recon/checks.py`
- [Human Sign-off](https://github.com/rahulramachandran-labs/reconmind/blob/main/app/agents/review.py): `app/agents/review.py`

### Evidence and Retrieval

- [MCP Tool Access](https://github.com/rahulramachandran-labs/reconmind/blob/main/app/tools/mcp_toolbox.py): `app/tools/mcp_toolbox.py`
- [Warehouse Metadata MCP](https://github.com/rahulramachandran-labs/reconmind/blob/main/mcp_servers/warehouse_metadata/server.py): `mcp_servers/warehouse_metadata/server.py`
- [Orchestration Metadata MCP](https://github.com/rahulramachandran-labs/reconmind/blob/main/mcp_servers/orchestration_metadata/server.py): `mcp_servers/orchestration_metadata/server.py`
- [Hybrid Retrieval](https://github.com/rahulramachandran-labs/reconmind/blob/main/app/retrieval/service.py): `app/retrieval/service.py`
- [RAG Answering](https://github.com/rahulramachandran-labs/reconmind/blob/main/app/rag/answer.py): `app/rag/answer.py`

### State and Observability

- [LLM Provider Chain](https://github.com/rahulramachandran-labs/reconmind/blob/main/app/llm/providers.py): `app/llm/providers.py`
- [Run and Incident Store](https://github.com/rahulramachandran-labs/reconmind/tree/main/app/agents/store): `app/agents/store`
- [Chat Sessions](https://github.com/rahulramachandran-labs/reconmind/blob/main/app/memory/sessions.py): `app/memory/sessions.py`
- [PostgreSQL](https://github.com/rahulramachandran-labs/reconmind/blob/main/app/db/models.py): `app/db/models.py`
- [Run Tracing](https://github.com/rahulramachandran-labs/reconmind/blob/main/app/observability/tracer.py): `app/observability/tracer.py`

### Other components

- **Analyst / Reviewer**

## Connections

- Analyst / Reviewer → ReconMind Web: uses (evidence: `README.md`)
- ReconMind Web → FastAPI App: requests
- Analyst / Reviewer → Incident Views: browses incidents (evidence: `README.md`)
- Analyst / Reviewer → Review Queue: reviews findings (evidence: `README.md`)
- Analyst / Reviewer → Anomaly Verification: verifies anomalies (evidence: `README.md`)
- Analyst / Reviewer → Trace Views: inspects runs (evidence: `README.md`)
- FastAPI App → Agent API: mounts router (evidence: `app/main.py`)
- FastAPI App → Knowledge API: mounts router (evidence: `app/main.py`)
- FastAPI App → Dashboard API: mounts router (evidence: `app/main.py`)
- Agent API → Investigation Service: invokes (evidence: `app/api/agents.py`)
- Knowledge API → Hybrid Retrieval: searches (evidence: `app/api/knowledge.py`)
- Knowledge API → RAG Answering: answers with (evidence: `app/api/knowledge.py`)
- Investigation Service → Agent Graph: runs (evidence: `app/agents/service.py`)
- Agent Graph → Planner and Specialists: dispatches (evidence: `app/agents/graph.py`)
- Planner and Specialists → Retail Recon Adapter: uses domain contract (evidence: `app/agents/specialists.py`)
- Retail Recon Adapter → Recon Checks: performs checks
- Investigation Service → Human Sign-off: pauses for review (evidence: `app/agents/service.py`)
- Agent Graph → MCP Tool Access: gathers evidence (evidence: `README.md`)
- MCP Tool Access → Warehouse Metadata MCP: calls tools (evidence: `README.md`)
- MCP Tool Access → Orchestration Metadata MCP: calls tools (evidence: `README.md`)
- Agent Graph → Hybrid Retrieval: retrieves context
- RAG Answering → Hybrid Retrieval: searches (evidence: `app/rag/answer.py`)
- RAG Answering → LLM Provider Chain: generates answer (evidence: `app/rag/answer.py`)
- Planner and Specialists → LLM Provider Chain: analyzes findings (evidence: `app/agents/specialists.py`)
- FastAPI App → LLM Provider Chain: initializes (evidence: `app/main.py`)
- Investigation Service → Run and Incident Store: persists run data
- FastAPI App → Chat Sessions: selects session store (evidence: `app/main.py`)
- Chat Sessions → PostgreSQL: stores sessions (evidence: `app/memory/sessions.py`)
- Investigation Service → Run Tracing: records run steps (evidence: `app/agents/service.py`)
- Run Tracing → PostgreSQL: writes steps (evidence: `app/observability/tracer.py`)
