# farheenaiml/trace architecture

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

- Interactive diagram: https://gitdiagram.com/farheenaiml/trace
- Repository: https://github.com/farheenaiml/trace

## Overview

TRACE connects GitHub repositories, extracts and indexes decision evidence, then serves repository Q&A and maintainer tools. Its main workflow runs from repository submission through asynchronous ingestion, rationale extraction, graph/vector indexing, and issue triage; engineers then query the indexed evidence through the web app. Separate branches provide repository health trends and weekly briefs. The README documents the backend pipeline and product pages; sampled source confirms some calls, but not all route-to-API wiring, so uncertain links are omitted.

Main entry points: [`backend/main.py`](https://github.com/farheenaiml/trace/blob/main/backend/main.py) (REST API and jobs), [`backend/graph_store.py`](https://github.com/farheenaiml/trace/blob/main/backend/graph_store.py) (Graph and vector indexing), [`backend/llm.py`](https://github.com/farheenaiml/trace/blob/main/backend/llm.py) (LLM client), [`frontend/src/routes/index.tsx`](https://github.com/farheenaiml/trace/blob/main/frontend/src/routes/index.tsx) (Repository connect)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_landing["Repository connect<br/>[index.tsx]"]
  node_repo_ui["Repository dashboard"]
  node_recall_ui["Decision recall"]
  node_answer_ui["Answer display<br/>[AnswerPanel.tsx]"]
  node_guardian_ui["Guardian triage"]
  node_health_ui["Health dashboard"]
end

subgraph group_api["API and orchestration"]
  node_api_main["REST API and jobs<br/>[main.py]"]
end

subgraph group_knowledge["Decision knowledge pipeline"]
  node_ingest["Repository ingestion<br/>[ingest.py]"]
  node_extract["Rationale extraction<br/>[extractor.py]"]
  node_graph_store["Graph and vector indexing<br/>[graph_store.py]"]
  node_llm["LLM client<br/>[llm.py]"]
end

subgraph group_maintainer["Maintainer intelligence"]
  node_guardian["Issue triage agent<br/>[agent.py]"]
  node_health["Health metrics<br/>[health.py]"]
  node_brief["Weekly brief<br/>[brief.py]"]
end

node_engineer(("Engineer"))
node_github["GitHub"]
node_neo4j[("Neo4j graph")]
node_qdrant[("Qdrant vectors")]

node_engineer -->|"connects repository"| node_landing
node_landing -->|"submits repository"| node_api_main
node_api_main -->|"schedules ingestion"| node_ingest
node_ingest -->|"fetches repository data"| node_github
node_api_main -->|"runs extraction"| node_extract
node_api_main -->|"loads indexes"| node_graph_store
node_graph_store -->|"writes graph"| node_neo4j
node_graph_store -->|"writes vectors"| node_qdrant
node_api_main -->|"runs triage"| node_guardian
node_api_main -->|"calls client"| node_llm
node_guardian -->|"requests scoring"| node_llm
node_brief -->|"requests summary"| node_llm
node_engineer -->|"opens repository"| node_repo_ui
node_engineer -->|"asks decision question"| node_recall_ui
node_recall_ui -->|"requests evidence answer"| node_api_main
node_api_main -->|"queries indexed evidence"| node_graph_store
node_api_main -->|"synthesizes answer"| node_llm
node_api_main -->|"returns grounded answer"| node_answer_ui
node_engineer -->|"reviews triage"| node_guardian_ui
node_guardian_ui -->|"requests scan status"| node_api_main
node_engineer -->|"views health"| node_health_ui
node_api_main -->|"serves health metrics"| node_health
node_api_main -->|"generates weekly brief"| node_brief

click node_landing "https://github.com/farheenaiml/trace/blob/main/frontend/src/routes/index.tsx"
click node_repo_ui "https://github.com/farheenaiml/trace/blob/main/frontend/src/routes/repo.%24repoId.index.tsx"
click node_recall_ui "https://github.com/farheenaiml/trace/blob/main/frontend/src/routes/repo.%24repoId.recall.tsx"
click node_answer_ui "https://github.com/farheenaiml/trace/blob/main/frontend/src/components/trace/AnswerPanel.tsx"
click node_guardian_ui "https://github.com/farheenaiml/trace/blob/main/frontend/src/routes/repo.%24repoId.guardian.tsx"
click node_health_ui "https://github.com/farheenaiml/trace/blob/main/frontend/src/routes/repo.%24repoId.health.tsx"
click node_api_main "https://github.com/farheenaiml/trace/blob/main/backend/main.py"
click node_ingest "https://github.com/farheenaiml/trace/blob/main/backend/ingest.py"
click node_extract "https://github.com/farheenaiml/trace/blob/main/backend/extractor.py"
click node_graph_store "https://github.com/farheenaiml/trace/blob/main/backend/graph_store.py"
click node_llm "https://github.com/farheenaiml/trace/blob/main/backend/llm.py"
click node_guardian "https://github.com/farheenaiml/trace/blob/main/backend/agent.py"
click node_health "https://github.com/farheenaiml/trace/blob/main/backend/health.py"
click node_brief "https://github.com/farheenaiml/trace/blob/main/backend/brief.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_landing,node_repo_ui,node_recall_ui,node_answer_ui,node_guardian_ui,node_health_ui toneBlue
class node_api_main,node_neo4j,node_qdrant toneAmber
class node_ingest,node_extract,node_graph_store,node_llm toneMint
class node_guardian,node_health,node_brief toneRose
class node_engineer,node_github toneIndigo
```

## Components

### Web experience

- [Repository connect](https://github.com/farheenaiml/trace/blob/main/frontend/src/routes/index.tsx): `frontend/src/routes/index.tsx`
- [Repository dashboard](https://github.com/farheenaiml/trace/blob/main/frontend/src/routes/repo.%24repoId.index.tsx): `frontend/src/routes/repo.$repoId.index.tsx`
- [Decision recall](https://github.com/farheenaiml/trace/blob/main/frontend/src/routes/repo.%24repoId.recall.tsx): `frontend/src/routes/repo.$repoId.recall.tsx`
- [Answer display](https://github.com/farheenaiml/trace/blob/main/frontend/src/components/trace/AnswerPanel.tsx): `frontend/src/components/trace/AnswerPanel.tsx`
- [Guardian triage](https://github.com/farheenaiml/trace/blob/main/frontend/src/routes/repo.%24repoId.guardian.tsx): `frontend/src/routes/repo.$repoId.guardian.tsx`
- [Health dashboard](https://github.com/farheenaiml/trace/blob/main/frontend/src/routes/repo.%24repoId.health.tsx): `frontend/src/routes/repo.$repoId.health.tsx`

### API and orchestration

- [REST API and jobs](https://github.com/farheenaiml/trace/blob/main/backend/main.py): `backend/main.py`

### Decision knowledge pipeline

- [Repository ingestion](https://github.com/farheenaiml/trace/blob/main/backend/ingest.py): `backend/ingest.py`
- [Rationale extraction](https://github.com/farheenaiml/trace/blob/main/backend/extractor.py): `backend/extractor.py`
- [Graph and vector indexing](https://github.com/farheenaiml/trace/blob/main/backend/graph_store.py): `backend/graph_store.py`
- [LLM client](https://github.com/farheenaiml/trace/blob/main/backend/llm.py): `backend/llm.py`

### Maintainer intelligence

- [Issue triage agent](https://github.com/farheenaiml/trace/blob/main/backend/agent.py): `backend/agent.py`
- [Health metrics](https://github.com/farheenaiml/trace/blob/main/backend/health.py): `backend/health.py`
- [Weekly brief](https://github.com/farheenaiml/trace/blob/main/backend/brief.py): `backend/brief.py`

### Other components

- **Engineer**
- **GitHub**
- **Neo4j graph**
- **Qdrant vectors**

## Connections

- Engineer → Repository connect: connects repository (evidence: `frontend/src/routes/index.tsx`)
- Repository connect → REST API and jobs: submits repository (evidence: `frontend/src/routes/index.tsx`)
- REST API and jobs → Repository ingestion: schedules ingestion (evidence: `README.md`)
- Repository ingestion → GitHub: fetches repository data (evidence: `README.md`)
- REST API and jobs → Rationale extraction: runs extraction (evidence: `README.md`)
- REST API and jobs → Graph and vector indexing: loads indexes (evidence: `README.md`)
- Graph and vector indexing → Neo4j graph: writes graph (evidence: `README.md`)
- Graph and vector indexing → Qdrant vectors: writes vectors (evidence: `README.md`)
- REST API and jobs → Issue triage agent: runs triage (evidence: `README.md`)
- REST API and jobs → LLM client: calls client (evidence: `backend/main.py`)
- Issue triage agent → LLM client: requests scoring (evidence: `backend/agent.py`)
- Weekly brief → LLM client: requests summary (evidence: `backend/brief.py`)
- Engineer → Repository dashboard: opens repository (evidence: `README.md`)
- Engineer → Decision recall: asks decision question (evidence: `README.md`)
- Decision recall → REST API and jobs: requests evidence answer (evidence: `README.md`)
- REST API and jobs → Graph and vector indexing: queries indexed evidence (evidence: `backend/main.py`)
- REST API and jobs → LLM client: synthesizes answer (evidence: `backend/main.py`)
- REST API and jobs → Answer display: returns grounded answer (evidence: `README.md`)
- Engineer → Guardian triage: reviews triage (evidence: `README.md`)
- Guardian triage → REST API and jobs: requests scan status (evidence: `frontend/src/routes/repo.$repoId.guardian.tsx`)
- Engineer → Health dashboard: views health (evidence: `README.md`)
- REST API and jobs → Health metrics: serves health metrics (evidence: `README.md`)
- REST API and jobs → Weekly brief: generates weekly brief (evidence: `README.md`)