# sandeepklr12345-gif/cause-trace architecture

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

- Interactive diagram: https://gitdiagram.com/sandeepklr12345-gif/cause-trace
- Repository: https://github.com/sandeepklr12345-gif/cause-trace

## Overview

CauseTrace is an AI-assisted root-cause analysis workspace for API manufacturing. A reviewer supplies incident text or a document through the copilot; the backend extracts evidence and runs a routed analysis that can develop hypotheses, challenge causes, identify evidence gaps, and propose CAPA. Results populate a provenance-aware investigation for human review; only a person can confirm a root cause, and saving requires confirmation. The graph follows those documented stages and the sampled frontend/backend wiring. Some subsystem links rely on the README or SOURCE INDEX references; unsampled internals are not assumed beyond those references.

Main entry points: [`backend/app/routers/investigations.py`](https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/routers/investigations.py) (Review actions), [`backend/app/ai/nodes.py`](https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/ai/nodes.py) (Analysis stages), [`frontend/src/api.js`](https://github.com/sandeepklr12345-gif/cause-trace/blob/main/frontend/src/api.js) (API client), [`backend/app/routers/chat.py`](https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/routers/chat.py) (Chat endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Investigation workspace"]
  node_workspace["Workspace shell<br/>[App.jsx]"]
  node_copilot["AI copilot<br/>[Copilot.jsx]"]
  node_form["RCA form sections"]
  node_chatstate["Chat state<br/>[chatSlice.js]"]
  node_invstate["Investigation state"]
end

subgraph group_analysis["AI analysis"]
  node_chatroute["Chat endpoint<br/>[chat.py]"]
  node_upload["Document extraction<br/>[documents.py]"]
  node_graph["Analysis graph<br/>[graph.py]"]
  node_nodes["Analysis stages<br/>[nodes.py]"]
  node_prompts["Analysis prompts<br/>[prompts.py]"]
  node_llm["Structured LLM calls<br/>[llm.py]"]
  node_mock["Mock responses<br/>[mock.py]"]
  node_merge["Safety and scoring<br/>[merge.py]"]
end

subgraph group_review["Review and persistence"]
  node_reviewroute["Review actions<br/>[investigations.py]"]
  node_persist["Audit and undo<br/>[persist.py]"]
end

subgraph group_platform["Application platform"]
  node_client["API client<br/>[api.js]"]
  node_schemas["Investigation schemas<br/>[schemas.py]"]
  node_models["Database models<br/>[models.py]"]
  node_db[("PostgreSQL access<br/>[db.py]")]
end

node_reviewer(("Reviewer"))
node_groq["Groq service"]

node_reviewer -->|"provides input"| node_copilot
node_reviewer -->|"reviews results"| node_form
node_workspace -->|"renders"| node_copilot
node_workspace -->|"renders"| node_form
node_copilot -->|"dispatches chat"| node_chatstate
node_chatstate -->|"streams chat"| node_client
node_chatstate -->|"updates investigation"| node_invstate
node_invstate -->|"loads and edits"| node_client
node_client -->|"posts chat"| node_chatroute
node_client -->|"calls review APIs"| node_reviewroute
node_client -->|"uploads document"| node_upload
node_chatroute -->|"runs analysis"| node_graph
node_chatroute -->|"saves chat changes"| node_persist
node_reviewroute -->|"extracts uploaded text"| node_upload
node_graph -->|"dispatches stages"| node_nodes
node_nodes -->|"uses prompts"| node_prompts
node_nodes -->|"requests structured output"| node_llm
node_nodes -->|"merges analysis"| node_merge
node_nodes -->|"validates against"| node_schemas
node_llm -->|"uses in mock mode"| node_mock
node_llm -->|"invokes model"| node_groq
node_reviewroute -->|"sanitizes review edits"| node_merge
node_reviewroute -->|"records changes"| node_persist
node_reviewroute -->|"validates investigation"| node_schemas
node_chatroute -->|"loads session"| node_db
node_reviewroute -->|"loads session"| node_db
node_persist -->|"writes audit and snapshots"| node_models
node_models -->|"uses database base"| node_db
node_reviewroute -->|"reads investigation records"| node_models
node_reviewroute -->|"requires human confirmation"| node_reviewer

click node_workspace "https://github.com/sandeepklr12345-gif/cause-trace/blob/main/frontend/src/App.jsx"
click node_copilot "https://github.com/sandeepklr12345-gif/cause-trace/blob/main/frontend/src/components/Copilot.jsx"
click node_form "https://github.com/sandeepklr12345-gif/cause-trace/tree/main/frontend/src/components"
click node_chatstate "https://github.com/sandeepklr12345-gif/cause-trace/blob/main/frontend/src/store/chatSlice.js"
click node_invstate "https://github.com/sandeepklr12345-gif/cause-trace/blob/main/frontend/src/store/investigationSlice.js"
click node_client "https://github.com/sandeepklr12345-gif/cause-trace/blob/main/frontend/src/api.js"
click node_chatroute "https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/routers/chat.py"
click node_upload "https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/services/documents.py"
click node_graph "https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/ai/graph.py"
click node_nodes "https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/ai/nodes.py"
click node_prompts "https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/ai/prompts.py"
click node_llm "https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/ai/llm.py"
click node_mock "https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/ai/mock.py"
click node_merge "https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/ai/merge.py"
click node_schemas "https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/schemas.py"
click node_reviewroute "https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/routers/investigations.py"
click node_persist "https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/services/persist.py"
click node_models "https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/models.py"
click node_db "https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/db.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_workspace,node_copilot,node_form,node_chatstate,node_invstate,node_reviewer toneBlue
class node_chatroute,node_upload,node_graph,node_nodes,node_prompts,node_llm,node_mock,node_merge toneAmber
class node_reviewroute,node_persist toneMint
class node_client,node_schemas,node_models,node_db toneRose
class node_groq toneIndigo
```

## Components

### Investigation workspace

- [Workspace shell](https://github.com/sandeepklr12345-gif/cause-trace/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [AI copilot](https://github.com/sandeepklr12345-gif/cause-trace/blob/main/frontend/src/components/Copilot.jsx): `frontend/src/components/Copilot.jsx`
- [RCA form sections](https://github.com/sandeepklr12345-gif/cause-trace/tree/main/frontend/src/components): `frontend/src/components`
- [Chat state](https://github.com/sandeepklr12345-gif/cause-trace/blob/main/frontend/src/store/chatSlice.js): `frontend/src/store/chatSlice.js`
- [Investigation state](https://github.com/sandeepklr12345-gif/cause-trace/blob/main/frontend/src/store/investigationSlice.js): `frontend/src/store/investigationSlice.js`

### AI analysis

- [Chat endpoint](https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/routers/chat.py): `backend/app/routers/chat.py`
- [Document extraction](https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/services/documents.py): `backend/app/services/documents.py`
- [Analysis graph](https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/ai/graph.py): `backend/app/ai/graph.py`
- [Analysis stages](https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/ai/nodes.py): `backend/app/ai/nodes.py`
- [Analysis prompts](https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/ai/prompts.py): `backend/app/ai/prompts.py`
- [Structured LLM calls](https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/ai/llm.py): `backend/app/ai/llm.py`
- [Mock responses](https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/ai/mock.py): `backend/app/ai/mock.py`
- [Safety and scoring](https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/ai/merge.py): `backend/app/ai/merge.py`

### Review and persistence

- [Review actions](https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/routers/investigations.py): `backend/app/routers/investigations.py`
- [Audit and undo](https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/services/persist.py): `backend/app/services/persist.py`

### Application platform

- [API client](https://github.com/sandeepklr12345-gif/cause-trace/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [Investigation schemas](https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/schemas.py): `backend/app/schemas.py`
- [Database models](https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/models.py): `backend/app/models.py`
- [PostgreSQL access](https://github.com/sandeepklr12345-gif/cause-trace/blob/main/backend/app/db.py): `backend/app/db.py`

### Other components

- **Reviewer**
- **Groq service**

## Connections

- Reviewer → AI copilot: provides input (evidence: `frontend/src/components/Copilot.jsx`)
- Reviewer → RCA form sections: reviews results
- Workspace shell → AI copilot: renders (evidence: `frontend/src/App.jsx`)
- Workspace shell → RCA form sections: renders (evidence: `frontend/src/App.jsx`)
- AI copilot → Chat state: dispatches chat (evidence: `frontend/src/components/Copilot.jsx`)
- Chat state → API client: streams chat (evidence: `frontend/src/store/chatSlice.js`)
- Chat state → Investigation state: updates investigation (evidence: `frontend/src/store/chatSlice.js`)
- Investigation state → API client: loads and edits (evidence: `frontend/src/store/investigationSlice.js`)
- API client → Chat endpoint: posts chat (evidence: `frontend/src/api.js`)
- API client → Review actions: calls review APIs (evidence: `frontend/src/api.js`)
- API client → Document extraction: uploads document (evidence: `frontend/src/api.js`)
- Chat endpoint → Analysis graph: runs analysis (evidence: `backend/app/routers/chat.py`)
- Chat endpoint → Audit and undo: saves chat changes (evidence: `backend/app/routers/chat.py`)
- Review actions → Document extraction: extracts uploaded text (evidence: `backend/app/routers/investigations.py`)
- Analysis graph → Analysis stages: dispatches stages (evidence: `backend/app/ai/graph.py`)
- Analysis stages → Analysis prompts: uses prompts (evidence: `backend/app/ai/nodes.py`)
- Analysis stages → Structured LLM calls: requests structured output (evidence: `backend/app/ai/nodes.py`)
- Analysis stages → Safety and scoring: merges analysis (evidence: `backend/app/ai/nodes.py`)
- Analysis stages → Investigation schemas: validates against (evidence: `backend/app/ai/nodes.py`)
- Structured LLM calls → Mock responses: uses in mock mode (evidence: `backend/app/ai/llm.py`)
- Structured LLM calls → Groq service: invokes model (evidence: `backend/app/ai/llm.py`)
- Review actions → Safety and scoring: sanitizes review edits (evidence: `backend/app/routers/investigations.py`)
- Review actions → Audit and undo: records changes (evidence: `backend/app/routers/investigations.py`)
- Review actions → Investigation schemas: validates investigation (evidence: `backend/app/routers/investigations.py`)
- Chat endpoint → PostgreSQL access: loads session (evidence: `backend/app/routers/chat.py`)
- Review actions → PostgreSQL access: loads session (evidence: `backend/app/routers/investigations.py`)
- Audit and undo → Database models: writes audit and snapshots (evidence: `backend/app/services/persist.py`)
- Database models → PostgreSQL access: uses database base (evidence: `backend/app/models.py`)
- Review actions → Database models: reads investigation records (evidence: `backend/app/routers/investigations.py`)
- Review actions → Reviewer: requires human confirmation