# adrianhajdin/cartograph architecture

> Architecture diagram of the GitHub repository adrianhajdin/cartograph, 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/adrianhajdin/cartograph
- Repository: https://github.com/adrianhajdin/cartograph

## Overview

Cartograph turns a public JavaScript or TypeScript repository into a stored, interactive dependency map. The principal workflow is repository submission, fetch and parse, persistence, then analysis viewing; the map also supports route inspection, dependency blast-radius exploration, and grounded AI explanations and chat. The parser, graph projections, and AI context builder are distinct internal layers. Relationships below are limited to excerpted imports/calls and README statements; several application actions and optional observability wiring were not sampled, so uncertain links are omitted.

Main entry points: [`components/analysis-view.tsx`](https://github.com/adrianhajdin/cartograph/blob/main/components/analysis-view.tsx) (Analysis workspace), [`lib/pipeline/run.ts`](https://github.com/adrianhajdin/cartograph/blob/main/lib/pipeline/run.ts) (Analysis pipeline), [`app/(workspace)/analyses/[id]/page.tsx`](https://github.com/adrianhajdin/cartograph/blob/main/app/(workspace)/analyses/%5Bid%5D/page.tsx) (Analysis page), [`components/submit-form.tsx`](https://github.com/adrianhajdin/cartograph/blob/main/components/submit-form.tsx) (Submit analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_product["Product workflow"]
  node_submit["Submit analysis<br/>[submit-form.tsx]"]
  node_pipeline["Analysis pipeline<br/>[run.ts]"]
  node_fetch["Fetch repository<br/>[github.ts]"]
  node_storage["Analysis storage<br/>[store.ts]"]
  node_loader["Load analysis<br/>[load.ts]"]
end

subgraph group_parsing["Repository parsing"]
  node_parser["AST parser<br/>[index.ts]"]
  node_adapters["Framework adapters"]
end

subgraph group_analysis["Graph analysis"]
  node_graph["Graph projections<br/>[view.ts]"]
  node_reach["Dependency reach<br/>[reach.ts]"]
  node_insights["Graph insights<br/>[insights.ts]"]
end

subgraph group_experience["Map experience"]
  node_analysis_page["Analysis page<br/>[page.tsx]"]
  node_analysis_view["Analysis workspace<br/>[analysis-view.tsx]"]
  node_map["Dependency canvas<br/>[dependency-map.tsx]"]
  node_detail["Module details<br/>[detail-pane.tsx]"]
  node_routes["Route table<br/>[route-table.tsx]"]
  node_explanation["Explanation panel"]
end

subgraph group_ai["AI explanations"]
  node_context["Grounding context<br/>[context.ts]"]
  node_ai_tasks["AI tasks<br/>[tasks.ts]"]
end

node_developer(("Developer"))
node_github(("Public repository"))
node_database[("Supabase database")]
node_openai(("OpenAI"))

node_developer -->|"submits repository"| node_submit
node_submit -.->|"starts analysis"| node_pipeline
node_pipeline -->|"fetches source"| node_fetch
node_pipeline -->|"parses files"| node_parser
node_fetch -->|"downloads archive"| node_github
node_parser -->|"detects conventions"| node_adapters
node_pipeline -->|"stores results"| node_storage
node_storage -.->|"persists analysis"| node_database
node_analysis_page -->|"loads stored map"| node_loader
node_loader -->|"reads analysis"| node_database
node_analysis_page -->|"renders workspace"| node_analysis_view
node_analysis_view -->|"projects map"| node_graph
node_analysis_view -->|"renders canvas"| node_map
node_analysis_view -->|"renders details"| node_detail
node_analysis_view -->|"renders routes"| node_routes
node_detail -->|"finds insights"| node_insights
node_analysis_view -->|"calculates blast radius"| node_reach
node_analysis_view -->|"renders explanations"| node_explanation
node_explanation -.->|"requests grounded context"| node_context
node_context -->|"builds prompt context"| node_ai_tasks
node_ai_tasks -->|"requests explanations"| node_openai

click node_submit "https://github.com/adrianhajdin/cartograph/blob/main/components/submit-form.tsx"
click node_pipeline "https://github.com/adrianhajdin/cartograph/blob/main/lib/pipeline/run.ts"
click node_fetch "https://github.com/adrianhajdin/cartograph/blob/main/lib/pipeline/github.ts"
click node_storage "https://github.com/adrianhajdin/cartograph/blob/main/lib/pipeline/store.ts"
click node_parser "https://github.com/adrianhajdin/cartograph/blob/main/lib/parser/index.ts"
click node_adapters "https://github.com/adrianhajdin/cartograph/tree/main/lib/parser/adapters"
click node_loader "https://github.com/adrianhajdin/cartograph/blob/main/lib/analysis/load.ts"
click node_graph "https://github.com/adrianhajdin/cartograph/blob/main/lib/graph/view.ts"
click node_reach "https://github.com/adrianhajdin/cartograph/blob/main/lib/graph/reach.ts"
click node_insights "https://github.com/adrianhajdin/cartograph/blob/main/lib/graph/insights.ts"
click node_analysis_page "https://github.com/adrianhajdin/cartograph/blob/main/app/(workspace)/analyses/%5Bid%5D/page.tsx"
click node_analysis_view "https://github.com/adrianhajdin/cartograph/blob/main/components/analysis-view.tsx"
click node_map "https://github.com/adrianhajdin/cartograph/blob/main/components/map/dependency-map.tsx"
click node_detail "https://github.com/adrianhajdin/cartograph/blob/main/components/detail-pane.tsx"
click node_routes "https://github.com/adrianhajdin/cartograph/blob/main/components/route-table.tsx"
click node_explanation "https://github.com/adrianhajdin/cartograph/blob/main/components/explanation-panel.tsx"
click node_context "https://github.com/adrianhajdin/cartograph/blob/main/lib/analysis/context.ts"
click node_ai_tasks "https://github.com/adrianhajdin/cartograph/blob/main/lib/ai/tasks.ts"

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_submit,node_pipeline,node_fetch,node_storage,node_loader toneBlue
class node_parser,node_adapters,node_database toneAmber
class node_graph,node_reach,node_insights toneMint
class node_analysis_page,node_analysis_view,node_map,node_detail,node_routes,node_explanation toneRose
class node_context,node_ai_tasks,node_developer,node_github,node_openai toneIndigo
```

## Components

### Product workflow

- [Submit analysis](https://github.com/adrianhajdin/cartograph/blob/main/components/submit-form.tsx): `components/submit-form.tsx`
- [Analysis pipeline](https://github.com/adrianhajdin/cartograph/blob/main/lib/pipeline/run.ts): `lib/pipeline/run.ts`
- [Fetch repository](https://github.com/adrianhajdin/cartograph/blob/main/lib/pipeline/github.ts): `lib/pipeline/github.ts`
- [Analysis storage](https://github.com/adrianhajdin/cartograph/blob/main/lib/pipeline/store.ts): `lib/pipeline/store.ts`
- [Load analysis](https://github.com/adrianhajdin/cartograph/blob/main/lib/analysis/load.ts): `lib/analysis/load.ts`

### Repository parsing

- [AST parser](https://github.com/adrianhajdin/cartograph/blob/main/lib/parser/index.ts): `lib/parser/index.ts`
- [Framework adapters](https://github.com/adrianhajdin/cartograph/tree/main/lib/parser/adapters): `lib/parser/adapters`

### Graph analysis

- [Graph projections](https://github.com/adrianhajdin/cartograph/blob/main/lib/graph/view.ts): `lib/graph/view.ts`
- [Dependency reach](https://github.com/adrianhajdin/cartograph/blob/main/lib/graph/reach.ts): `lib/graph/reach.ts`
- [Graph insights](https://github.com/adrianhajdin/cartograph/blob/main/lib/graph/insights.ts): `lib/graph/insights.ts`

### Map experience

- [Analysis page](https://github.com/adrianhajdin/cartograph/blob/main/app/(workspace)/analyses/%5Bid%5D/page.tsx): `app/(workspace)/analyses/[id]/page.tsx`
- [Analysis workspace](https://github.com/adrianhajdin/cartograph/blob/main/components/analysis-view.tsx): `components/analysis-view.tsx`
- [Dependency canvas](https://github.com/adrianhajdin/cartograph/blob/main/components/map/dependency-map.tsx): `components/map/dependency-map.tsx`
- [Module details](https://github.com/adrianhajdin/cartograph/blob/main/components/detail-pane.tsx): `components/detail-pane.tsx`
- [Route table](https://github.com/adrianhajdin/cartograph/blob/main/components/route-table.tsx): `components/route-table.tsx`
- [Explanation panel](https://github.com/adrianhajdin/cartograph/blob/main/components/explanation-panel.tsx): `components/explanation-panel.tsx`

### AI explanations

- [Grounding context](https://github.com/adrianhajdin/cartograph/blob/main/lib/analysis/context.ts): `lib/analysis/context.ts`
- [AI tasks](https://github.com/adrianhajdin/cartograph/blob/main/lib/ai/tasks.ts): `lib/ai/tasks.ts`

### Other components

- **Developer**
- **Public repository**
- **Supabase database**
- **OpenAI**

## Connections

- Developer → Submit analysis: submits repository
- Submit analysis → Analysis pipeline: starts analysis
- Analysis pipeline → Fetch repository: fetches source (evidence: `lib/pipeline/run.ts`)
- Analysis pipeline → AST parser: parses files (evidence: `lib/pipeline/run.ts`)
- Fetch repository → Public repository: downloads archive
- AST parser → Framework adapters: detects conventions (evidence: `lib/parser/index.ts`)
- Analysis pipeline → Analysis storage: stores results (evidence: `lib/pipeline/run.ts`)
- Analysis storage → Supabase database: persists analysis
- Analysis page → Load analysis: loads stored map (evidence: `app/(workspace)/analyses/[id]/page.tsx`)
- Load analysis → Supabase database: reads analysis (evidence: `lib/analysis/load.ts`)
- Analysis page → Analysis workspace: renders workspace (evidence: `app/(workspace)/analyses/[id]/page.tsx`)
- Analysis workspace → Graph projections: projects map (evidence: `components/analysis-view.tsx`)
- Analysis workspace → Dependency canvas: renders canvas (evidence: `components/analysis-view.tsx`)
- Analysis workspace → Module details: renders details (evidence: `components/analysis-view.tsx`)
- Analysis workspace → Route table: renders routes (evidence: `components/analysis-view.tsx`)
- Module details → Graph insights: finds insights (evidence: `components/detail-pane.tsx`)
- Analysis workspace → Dependency reach: calculates blast radius (evidence: `components/analysis-view.tsx`)
- Analysis workspace → Explanation panel: renders explanations (evidence: `components/analysis-view.tsx`)
- Explanation panel → Grounding context: requests grounded context
- Grounding context → AI tasks: builds prompt context (evidence: `lib/analysis/context.ts`)
- AI tasks → OpenAI: requests explanations
