# yashwanth-r19/compass architecture

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

- Interactive diagram: https://gitdiagram.com/yashwanth-r19/compass
- Repository: https://github.com/yashwanth-r19/compass

## Overview

Compass analyzes a submitted Git repository by cloning it, mining commit history and source structure, then computing persisted facts and deterministic insights. Users explore the results through repository overview, guide, exploration, findings, and evolution views; the product also supports security checks, comparisons, and optional narrative summaries. The README documents the analysis pipeline and major capabilities. Source excerpts establish application and UI routing, but most API and engine implementations were not sampled, so their internal call relationships are not asserted.

Main entry points: [`backend/app/main.py`](https://github.com/yashwanth-r19/compass/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/engines`](https://github.com/yashwanth-r19/compass/tree/main/backend/app/engines) (Insight engines), [`backend/app/api/analysis.py`](https://github.com/yashwanth-r19/compass/blob/main/backend/app/api/analysis.py) (Analysis endpoints), [`backend/app/ingestion/cloner.py`](https://github.com/yashwanth-r19/compass/blob/main/backend/app/ingestion/cloner.py) (Clone and guardrails)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Repository ingestion"]
  node_jobs["Job runner<br/>[runner.py]"]
  node_clone["Clone and guardrails<br/>[cloner.py]"]
  node_mine["History mining<br/>[miner.py]"]
  node_structure["Language analysis<br/>[scanner.py]"]
  node_persist["Fact persistence<br/>[persist.py]"]
  node_security_scan["History security scan<br/>[scanner.py]"]
end

subgraph group_analysis["Deterministic analysis"]
  node_insights["Insight engines"]
  node_analysis_extra["Analysis capabilities"]
  node_narrative["Narrative generation<br/>[generate.py]"]
end

subgraph group_api["API and persistence"]
  node_api_server["FastAPI application<br/>[main.py]"]
  node_repo_api["Repository endpoints<br/>[repos.py]"]
  node_analysis_api["Analysis endpoints<br/>[analysis.py]"]
  node_narrative_api["Narrative endpoints<br/>[narrative.py]"]
  node_compare_api["Comparison endpoints<br/>[compare.py]"]
  node_database[("PostgreSQL<br/>[models.py]")]
end

subgraph group_frontend["User experience"]
  node_ui["Compass web app<br/>[App.tsx]"]
  node_repo_views["Repository surfaces"]
  node_api_hooks["API data hooks<br/>[hooks.ts]"]
  node_api_client["API client<br/>[client.ts]"]
end

node_engineer(("Engineer"))
node_git["Git repository"]
node_osv{{"OSV.dev"}}

node_engineer -->|"explores results"| node_ui
node_ui -->|"routes to"| node_repo_views
node_engineer -.->|"submits repository"| node_repo_api
node_git -->|"cloned from"| node_clone
node_repo_api -.->|"starts analysis"| node_jobs
node_jobs -.->|"runs pipeline"| node_clone
node_clone -->|"mines history"| node_mine
node_mine -->|"parses structure"| node_structure
node_structure -->|"persists facts"| node_persist
node_persist -->|"scans history"| node_security_scan
node_security_scan -->|"then computes"| node_insights
node_insights -->|"reads and writes"| node_database
node_insights -->|"checks advisories"| node_osv
node_insights -.->|"supports analysis"| node_analysis_extra
node_analysis_api -.->|"serves computed results"| node_insights
node_analysis_api -.->|"serves analysis"| node_analysis_extra
node_repo_views -.->|"requests results"| node_api_hooks
node_api_hooks -.->|"uses client"| node_api_client
node_api_client -.->|"calls API"| node_api_server
node_narrative_api -.->|"requests summaries"| node_narrative
node_compare_api -.->|"provides comparisons"| node_analysis_extra
node_api_server -->|"registers routes"| node_repo_api
node_api_server -->|"registers routes"| node_analysis_api
node_api_server -->|"registers routes"| node_narrative_api
node_api_server -->|"registers routes"| node_compare_api

click node_ui "https://github.com/yashwanth-r19/compass/blob/main/frontend/src/App.tsx"
click node_repo_views "https://github.com/yashwanth-r19/compass/tree/main/frontend/src/pages/repo"
click node_api_hooks "https://github.com/yashwanth-r19/compass/blob/main/frontend/src/api/hooks.ts"
click node_api_client "https://github.com/yashwanth-r19/compass/blob/main/frontend/src/api/client.ts"
click node_api_server "https://github.com/yashwanth-r19/compass/blob/main/backend/app/main.py"
click node_repo_api "https://github.com/yashwanth-r19/compass/blob/main/backend/app/api/repos.py"
click node_analysis_api "https://github.com/yashwanth-r19/compass/blob/main/backend/app/api/analysis.py"
click node_narrative_api "https://github.com/yashwanth-r19/compass/blob/main/backend/app/api/narrative.py"
click node_compare_api "https://github.com/yashwanth-r19/compass/blob/main/backend/app/api/compare.py"
click node_jobs "https://github.com/yashwanth-r19/compass/blob/main/backend/app/jobs/runner.py"
click node_clone "https://github.com/yashwanth-r19/compass/blob/main/backend/app/ingestion/cloner.py"
click node_mine "https://github.com/yashwanth-r19/compass/blob/main/backend/app/ingestion/miner.py"
click node_structure "https://github.com/yashwanth-r19/compass/blob/main/backend/app/languages/scanner.py"
click node_persist "https://github.com/yashwanth-r19/compass/blob/main/backend/app/ingestion/persist.py"
click node_security_scan "https://github.com/yashwanth-r19/compass/blob/main/backend/app/security/scanner.py"
click node_insights "https://github.com/yashwanth-r19/compass/tree/main/backend/app/engines"
click node_analysis_extra "https://github.com/yashwanth-r19/compass/tree/main/backend/app/analysis"
click node_narrative "https://github.com/yashwanth-r19/compass/blob/main/backend/app/narrative/generate.py"
click node_database "https://github.com/yashwanth-r19/compass/blob/main/backend/app/db/models.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_jobs,node_clone,node_mine,node_structure,node_persist,node_security_scan toneBlue
class node_insights,node_analysis_extra,node_narrative toneAmber
class node_api_server,node_repo_api,node_analysis_api,node_narrative_api,node_compare_api,node_database toneMint
class node_ui,node_repo_views,node_api_hooks,node_api_client toneRose
class node_engineer,node_git,node_osv toneIndigo
```

## Components

### Repository ingestion

- [Job runner](https://github.com/yashwanth-r19/compass/blob/main/backend/app/jobs/runner.py): `backend/app/jobs/runner.py`
- [Clone and guardrails](https://github.com/yashwanth-r19/compass/blob/main/backend/app/ingestion/cloner.py): `backend/app/ingestion/cloner.py`
- [History mining](https://github.com/yashwanth-r19/compass/blob/main/backend/app/ingestion/miner.py): `backend/app/ingestion/miner.py`
- [Language analysis](https://github.com/yashwanth-r19/compass/blob/main/backend/app/languages/scanner.py): `backend/app/languages/scanner.py`
- [Fact persistence](https://github.com/yashwanth-r19/compass/blob/main/backend/app/ingestion/persist.py): `backend/app/ingestion/persist.py`
- [History security scan](https://github.com/yashwanth-r19/compass/blob/main/backend/app/security/scanner.py): `backend/app/security/scanner.py`

### Deterministic analysis

- [Insight engines](https://github.com/yashwanth-r19/compass/tree/main/backend/app/engines): `backend/app/engines`
- [Analysis capabilities](https://github.com/yashwanth-r19/compass/tree/main/backend/app/analysis): `backend/app/analysis`
- [Narrative generation](https://github.com/yashwanth-r19/compass/blob/main/backend/app/narrative/generate.py): `backend/app/narrative/generate.py`

### API and persistence

- [FastAPI application](https://github.com/yashwanth-r19/compass/blob/main/backend/app/main.py): `backend/app/main.py`
- [Repository endpoints](https://github.com/yashwanth-r19/compass/blob/main/backend/app/api/repos.py): `backend/app/api/repos.py`
- [Analysis endpoints](https://github.com/yashwanth-r19/compass/blob/main/backend/app/api/analysis.py): `backend/app/api/analysis.py`
- [Narrative endpoints](https://github.com/yashwanth-r19/compass/blob/main/backend/app/api/narrative.py): `backend/app/api/narrative.py`
- [Comparison endpoints](https://github.com/yashwanth-r19/compass/blob/main/backend/app/api/compare.py): `backend/app/api/compare.py`
- [PostgreSQL](https://github.com/yashwanth-r19/compass/blob/main/backend/app/db/models.py): `backend/app/db/models.py`

### User experience

- [Compass web app](https://github.com/yashwanth-r19/compass/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Repository surfaces](https://github.com/yashwanth-r19/compass/tree/main/frontend/src/pages/repo): `frontend/src/pages/repo`
- [API data hooks](https://github.com/yashwanth-r19/compass/blob/main/frontend/src/api/hooks.ts): `frontend/src/api/hooks.ts`
- [API client](https://github.com/yashwanth-r19/compass/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### Other components

- **Engineer**
- **Git repository**
- **OSV.dev**

## Connections

- Engineer → Compass web app: explores results (evidence: `frontend/src/App.tsx`)
- Compass web app → Repository surfaces: routes to (evidence: `frontend/src/App.tsx`)
- Engineer → Repository endpoints: submits repository (evidence: `README.md`)
- Git repository → Clone and guardrails: cloned from (evidence: `README.md`)
- Repository endpoints → Job runner: starts analysis (evidence: `README.md`)
- Job runner → Clone and guardrails: runs pipeline (evidence: `README.md`)
- Clone and guardrails → History mining: mines history (evidence: `README.md`)
- History mining → Language analysis: parses structure (evidence: `README.md`)
- Language analysis → Fact persistence: persists facts (evidence: `README.md`)
- Fact persistence → History security scan: scans history (evidence: `README.md`)
- History security scan → Insight engines: then computes (evidence: `README.md`)
- Insight engines → PostgreSQL: reads and writes (evidence: `README.md`)
- Insight engines → OSV.dev: checks advisories (evidence: `README.md`)
- Insight engines → Analysis capabilities: supports analysis (evidence: `backend/app/analysis/compare.py`)
- Analysis endpoints → Insight engines: serves computed results
- Analysis endpoints → Analysis capabilities: serves analysis
- Repository surfaces → API data hooks: requests results (evidence: `frontend/src/pages/repo/FindingsSurfacePage.tsx`)
- API data hooks → API client: uses client
- API client → FastAPI application: calls API
- Narrative endpoints → Narrative generation: requests summaries
- Comparison endpoints → Analysis capabilities: provides comparisons
- FastAPI application → Repository endpoints: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Analysis endpoints: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Narrative endpoints: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Comparison endpoints: registers routes (evidence: `backend/app/main.py`)