# harsha-rvceian/devtrace architecture

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

- Interactive diagram: https://gitdiagram.com/harsha-rvceian/devtrace
- Repository: https://github.com/harsha-rvceian/devtrace

## Overview

DevTrace records software-development provenance: interactions, decisions, alternatives, evidence, commits, and code changes. The main workflow captures project activity, extracts proposed decisions from conversation text, leaves approval to a developer, stores supported links, and presents history in the dashboard. Git capture and project timelines are additional documented capabilities. The sampled files show the API, NLP entry point, database session, and frontend wiring; several domain routes and integrations are represented from the README and source index, so their internal call paths are not expanded.

Main entry points: [`app/main.py`](https://github.com/harsha-rvceian/devtrace/blob/main/app/main.py) (FastAPI Application), [`frontend/src/App.jsx`](https://github.com/harsha-rvceian/devtrace/blob/main/frontend/src/App.jsx) (Dashboard App), [`nlp/rule_engine.py`](https://github.com/harsha-rvceian/devtrace/blob/main/nlp/rule_engine.py) (Rule Engine), [`nlp/pipeline.py`](https://github.com/harsha-rvceian/devtrace/blob/main/nlp/pipeline.py) (NLP Pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and API"]
  node_api["FastAPI Application<br/>[main.py]"]
  node_project_routes["Project API<br/>[projects.py]"]
  node_interaction_routes["Interaction API<br/>[interactions.py]"]
  node_commit_capture["Git Collector<br/>[collector.py]"]
  node_diff_parser["Diff Parser<br/>[diff_parser.py]"]
  node_nlp_route["NLP API<br/>[nlp.py]"]
  node_identity["User Resolution<br/>[dependencies.py]"]
end

subgraph group_extract["Decision Extraction"]
  node_pipeline["NLP Pipeline<br/>[pipeline.py]"]
  node_rules["Rule Engine<br/>[rule_engine.py]"]
  node_llm_engine["Optional LLM Engine<br/>[llm_engine.py]"]
  node_nlp_models["Extraction Data<br/>[models.py]"]
  node_decision_extract["Decision Extraction"]
  node_rationale_extract["Rationale Extraction"]
  node_alternative_extract["Alternative Extraction"]
end

subgraph group_records["Provenance Records"]
  node_db_session["Database Sessions<br/>[session.py]"]
  node_database[("PostgreSQL<br/>[entities.py]")]
  node_decision_service["Decision Records"]
  node_alternative_service["Alternative Records"]
  node_provenance_service["Code Provenance"]
  node_timeline_service["Project Timeline"]
end

subgraph group_experience["Developer Dashboard"]
  node_web_app["Dashboard App<br/>[App.jsx]"]
  node_api_client["REST Client<br/>[client.js]"]
  node_candidate_studio["Candidate Review"]
  node_provenance_view["Provenance View<br/>[Provenance.jsx]"]
  node_decision_view["Decision View<br/>[Decisions.jsx]"]
  node_timeline_view["Timeline View<br/>[Timeline.jsx]"]
end

node_developer(("Developer"))
node_ai_tool(("AI Coding Tool"))
node_git[("Git Repository")]

node_developer -->|"uses"| node_api
node_ai_tool -.->|"submits interaction"| node_interaction_routes
node_git -->|"provides history"| node_commit_capture
node_api -->|"registers routes"| node_project_routes
node_api -->|"registers routes"| node_interaction_routes
node_api -->|"registers routes"| node_nlp_route
node_project_routes -->|"resolves user"| node_identity
node_interaction_routes -->|"extracts candidates"| node_pipeline
node_commit_capture -->|"parses diffs"| node_diff_parser
node_commit_capture -->|"sends commit data"| node_api
node_nlp_route -->|"requests extraction"| node_pipeline
node_pipeline -->|"runs rules"| node_rules
node_pipeline -.->|"optionally runs LLM"| node_llm_engine
node_rules -->|"creates candidates"| node_nlp_models
node_llm_engine -->|"validates candidates"| node_nlp_models
node_rules -->|"uses extraction"| node_decision_extract
node_rules -->|"uses extraction"| node_alternative_extract
node_rules -->|"uses extraction"| node_rationale_extract
node_api -->|"opens sessions"| node_db_session
node_db_session -->|"connects to"| node_database
node_api -->|"stores provenance"| node_database
node_api -->|"coordinates decisions"| node_decision_service
node_api -->|"coordinates alternatives"| node_alternative_service
node_api -->|"links code changes"| node_provenance_service
node_api -->|"builds timelines"| node_timeline_service
node_developer -->|"reviews history"| node_web_app
node_web_app -->|"fetches dashboard data"| node_api_client
node_candidate_studio -->|"submits candidates"| node_api_client
node_api_client -->|"calls REST API"| node_api
node_web_app -->|"shows review"| node_candidate_studio
node_web_app -->|"shows provenance"| node_provenance_view
node_web_app -->|"shows decisions"| node_decision_view
node_web_app -->|"shows timeline"| node_timeline_view

click node_api "https://github.com/harsha-rvceian/devtrace/blob/main/app/main.py"
click node_project_routes "https://github.com/harsha-rvceian/devtrace/blob/main/app/api/routes/projects.py"
click node_interaction_routes "https://github.com/harsha-rvceian/devtrace/blob/main/app/api/routes/interactions.py"
click node_commit_capture "https://github.com/harsha-rvceian/devtrace/blob/main/integrations/git/collector.py"
click node_diff_parser "https://github.com/harsha-rvceian/devtrace/blob/main/integrations/git/diff_parser.py"
click node_nlp_route "https://github.com/harsha-rvceian/devtrace/blob/main/app/api/routes/nlp.py"
click node_identity "https://github.com/harsha-rvceian/devtrace/blob/main/app/api/dependencies.py"
click node_pipeline "https://github.com/harsha-rvceian/devtrace/blob/main/nlp/pipeline.py"
click node_rules "https://github.com/harsha-rvceian/devtrace/blob/main/nlp/rule_engine.py"
click node_llm_engine "https://github.com/harsha-rvceian/devtrace/blob/main/nlp/llm_engine.py"
click node_nlp_models "https://github.com/harsha-rvceian/devtrace/blob/main/nlp/models.py"
click node_decision_extract "https://github.com/harsha-rvceian/devtrace/blob/main/nlp/decision_extractor.py"
click node_rationale_extract "https://github.com/harsha-rvceian/devtrace/blob/main/nlp/rationale_extractor.py"
click node_alternative_extract "https://github.com/harsha-rvceian/devtrace/blob/main/nlp/alternative_extractor.py"
click node_db_session "https://github.com/harsha-rvceian/devtrace/blob/main/app/db/session.py"
click node_database "https://github.com/harsha-rvceian/devtrace/blob/main/app/models/entities.py"
click node_decision_service "https://github.com/harsha-rvceian/devtrace/blob/main/app/services/decision_service.py"
click node_alternative_service "https://github.com/harsha-rvceian/devtrace/blob/main/app/services/alternative_service.py"
click node_provenance_service "https://github.com/harsha-rvceian/devtrace/blob/main/app/services/provenance_service.py"
click node_timeline_service "https://github.com/harsha-rvceian/devtrace/blob/main/app/services/timeline_service.py"
click node_web_app "https://github.com/harsha-rvceian/devtrace/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/harsha-rvceian/devtrace/blob/main/frontend/src/api/client.js"
click node_candidate_studio "https://github.com/harsha-rvceian/devtrace/blob/main/frontend/src/pages/CandidateStudio.jsx"
click node_provenance_view "https://github.com/harsha-rvceian/devtrace/blob/main/frontend/src/pages/Provenance.jsx"
click node_decision_view "https://github.com/harsha-rvceian/devtrace/blob/main/frontend/src/pages/Decisions.jsx"
click node_timeline_view "https://github.com/harsha-rvceian/devtrace/blob/main/frontend/src/components/Timeline.jsx"

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_api,node_project_routes,node_interaction_routes,node_commit_capture,node_diff_parser,node_nlp_route,node_identity toneBlue
class node_pipeline,node_rules,node_llm_engine,node_nlp_models,node_decision_extract,node_rationale_extract,node_alternative_extract,node_git toneAmber
class node_db_session,node_database,node_decision_service,node_alternative_service,node_provenance_service,node_timeline_service toneMint
class node_web_app,node_api_client,node_candidate_studio,node_provenance_view,node_decision_view,node_timeline_view toneRose
class node_developer,node_ai_tool toneIndigo
```

## Components

### Capture and API

- [FastAPI Application](https://github.com/harsha-rvceian/devtrace/blob/main/app/main.py): `app/main.py`
- [Project API](https://github.com/harsha-rvceian/devtrace/blob/main/app/api/routes/projects.py): `app/api/routes/projects.py`
- [Interaction API](https://github.com/harsha-rvceian/devtrace/blob/main/app/api/routes/interactions.py): `app/api/routes/interactions.py`
- [Git Collector](https://github.com/harsha-rvceian/devtrace/blob/main/integrations/git/collector.py): `integrations/git/collector.py`
- [Diff Parser](https://github.com/harsha-rvceian/devtrace/blob/main/integrations/git/diff_parser.py): `integrations/git/diff_parser.py`
- [NLP API](https://github.com/harsha-rvceian/devtrace/blob/main/app/api/routes/nlp.py): `app/api/routes/nlp.py`
- [User Resolution](https://github.com/harsha-rvceian/devtrace/blob/main/app/api/dependencies.py): `app/api/dependencies.py`

### Decision Extraction

- [NLP Pipeline](https://github.com/harsha-rvceian/devtrace/blob/main/nlp/pipeline.py): `nlp/pipeline.py`
- [Rule Engine](https://github.com/harsha-rvceian/devtrace/blob/main/nlp/rule_engine.py): `nlp/rule_engine.py`
- [Optional LLM Engine](https://github.com/harsha-rvceian/devtrace/blob/main/nlp/llm_engine.py): `nlp/llm_engine.py`
- [Extraction Data](https://github.com/harsha-rvceian/devtrace/blob/main/nlp/models.py): `nlp/models.py`
- [Decision Extraction](https://github.com/harsha-rvceian/devtrace/blob/main/nlp/decision_extractor.py): `nlp/decision_extractor.py`
- [Rationale Extraction](https://github.com/harsha-rvceian/devtrace/blob/main/nlp/rationale_extractor.py): `nlp/rationale_extractor.py`
- [Alternative Extraction](https://github.com/harsha-rvceian/devtrace/blob/main/nlp/alternative_extractor.py): `nlp/alternative_extractor.py`

### Provenance Records

- [Database Sessions](https://github.com/harsha-rvceian/devtrace/blob/main/app/db/session.py): `app/db/session.py`
- [PostgreSQL](https://github.com/harsha-rvceian/devtrace/blob/main/app/models/entities.py): `app/models/entities.py`
- [Decision Records](https://github.com/harsha-rvceian/devtrace/blob/main/app/services/decision_service.py): `app/services/decision_service.py`
- [Alternative Records](https://github.com/harsha-rvceian/devtrace/blob/main/app/services/alternative_service.py): `app/services/alternative_service.py`
- [Code Provenance](https://github.com/harsha-rvceian/devtrace/blob/main/app/services/provenance_service.py): `app/services/provenance_service.py`
- [Project Timeline](https://github.com/harsha-rvceian/devtrace/blob/main/app/services/timeline_service.py): `app/services/timeline_service.py`

### Developer Dashboard

- [Dashboard App](https://github.com/harsha-rvceian/devtrace/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [REST Client](https://github.com/harsha-rvceian/devtrace/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`
- [Candidate Review](https://github.com/harsha-rvceian/devtrace/blob/main/frontend/src/pages/CandidateStudio.jsx): `frontend/src/pages/CandidateStudio.jsx`
- [Provenance View](https://github.com/harsha-rvceian/devtrace/blob/main/frontend/src/pages/Provenance.jsx): `frontend/src/pages/Provenance.jsx`
- [Decision View](https://github.com/harsha-rvceian/devtrace/blob/main/frontend/src/pages/Decisions.jsx): `frontend/src/pages/Decisions.jsx`
- [Timeline View](https://github.com/harsha-rvceian/devtrace/blob/main/frontend/src/components/Timeline.jsx): `frontend/src/components/Timeline.jsx`

### Other components

- **Developer**
- **AI Coding Tool**
- **Git Repository**

## Connections

- Developer → FastAPI Application: uses (evidence: `README.md`)
- AI Coding Tool → Interaction API: submits interaction (evidence: `README.md`)
- Git Repository → Git Collector: provides history (evidence: `README.md`)
- FastAPI Application → Project API: registers routes (evidence: `app/main.py`)
- FastAPI Application → Interaction API: registers routes (evidence: `app/main.py`)
- FastAPI Application → NLP API: registers routes (evidence: `app/main.py`)
- Project API → User Resolution: resolves user (evidence: `app/api/routes/projects.py`)
- Interaction API → NLP Pipeline: extracts candidates (evidence: `app/api/routes/interactions.py`)
- Git Collector → Diff Parser: parses diffs (evidence: `integrations/git/collector.py`)
- Git Collector → FastAPI Application: sends commit data (evidence: `README.md`)
- NLP API → NLP Pipeline: requests extraction
- NLP Pipeline → Rule Engine: runs rules (evidence: `nlp/pipeline.py`)
- NLP Pipeline → Optional LLM Engine: optionally runs LLM (evidence: `nlp/pipeline.py`)
- Rule Engine → Extraction Data: creates candidates (evidence: `nlp/rule_engine.py`)
- Optional LLM Engine → Extraction Data: validates candidates (evidence: `nlp/llm_engine.py`)
- Rule Engine → Decision Extraction: uses extraction (evidence: `nlp/rule_engine.py`)
- Rule Engine → Alternative Extraction: uses extraction (evidence: `nlp/rule_engine.py`)
- Rule Engine → Rationale Extraction: uses extraction (evidence: `nlp/rule_engine.py`)
- FastAPI Application → Database Sessions: opens sessions
- Database Sessions → PostgreSQL: connects to (evidence: `app/db/session.py`)
- FastAPI Application → PostgreSQL: stores provenance (evidence: `README.md`)
- FastAPI Application → Decision Records: coordinates decisions
- FastAPI Application → Alternative Records: coordinates alternatives
- FastAPI Application → Code Provenance: links code changes
- FastAPI Application → Project Timeline: builds timelines
- Developer → Dashboard App: reviews history (evidence: `README.md`)
- Dashboard App → REST Client: fetches dashboard data (evidence: `frontend/src/App.jsx`)
- Candidate Review → REST Client: submits candidates (evidence: `frontend/src/pages/CandidateStudio.jsx`)
- REST Client → FastAPI Application: calls REST API (evidence: `frontend/src/api/client.js`)
- Dashboard App → Candidate Review: shows review (evidence: `frontend/src/App.jsx`)
- Dashboard App → Provenance View: shows provenance (evidence: `frontend/src/App.jsx`)
- Dashboard App → Decision View: shows decisions (evidence: `frontend/src/App.jsx`)
- Dashboard App → Timeline View: shows timeline (evidence: `frontend/src/App.jsx`)
