# jjwang1118/graphcode architecture

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

- Interactive diagram: https://gitdiagram.com/jjwang1118/graphcode
- Repository: https://github.com/jjwang1118/graphcode

## Overview

Codegraph analyzes a local Python project into one typed code knowledge graph, then serves graph and impact queries to an interactive explorer. The main path runs from a user-supplied path through safe ingestion, scanning, parsing, fact generation and name resolution, graph construction, query/view shaping and serialization, then through the API client into 2D/3D canvases. The README documents these stages and capabilities; the sampled excerpts verify key orchestration and UI edges. Other detailed internal calls are omitted where source was not sampled.

Main entry points: [`backend/app/pipeline.py`](https://github.com/jjwang1118/graphcode/blob/main/backend/app/pipeline.py) (Analysis pipeline), [`frontend/src/App.tsx`](https://github.com/jjwang1118/graphcode/blob/main/frontend/src/App.tsx) (Explorer application), [`backend/app/api/analyze.py`](https://github.com/jjwang1118/graphcode/blob/main/backend/app/api/analyze.py) (Analyze API), [`frontend/src/api/client.ts`](https://github.com/jjwang1118/graphcode/blob/main/frontend/src/api/client.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Analysis backend"]
  node_ingest["Safe ingestion<br/>[local.py]"]
  node_scan["Tree scan<br/>[walk.py]"]
  node_parse["Python parser<br/>[python.py]"]
  node_language["Language registry<br/>[registry.py]"]
  node_facts["Fact production<br/>[production.py]"]
  node_resolve["Name resolution"]
  node_pipeline["Analysis pipeline<br/>[pipeline.py]"]
  node_build["Graph construction<br/>[build.py]"]
  node_query["Graph queries<br/>[query.py]"]
  node_views["Graph views<br/>[views.py]"]
  node_store["Graph persistence<br/>[store.py]"]
  node_analyze_api["Analyze API<br/>[analyze.py]"]
  node_impact_api["Impact API<br/>[impact.py]"]
end

subgraph group_frontend["Graph explorer"]
  node_app["Explorer application<br/>[App.tsx]"]
  node_client["API client<br/>[client.ts]"]
  node_transform["Graph transform<br/>[transform.ts]"]
  node_sidebar["Explorer controls<br/>[Sidebar.tsx]"]
  node_canvas2d["2D canvas<br/>[GraphCanvas.tsx]"]
  node_canvas3d["3D canvas<br/>[Graph3D.tsx]"]
  node_detail["Node details<br/>[DetailBox.tsx]"]
  node_layout["Graph layouts<br/>[layouts.ts]"]
  node_levels["Level selection<br/>[levels.ts]"]
  node_style["Graph styling<br/>[style.ts]"]
  node_graph_views["Explorer views<br/>[views.ts]"]
end

subgraph group_contract["Graph model"]
  node_model["Graph schema<br/>[graph.py]"]
  node_ids["Graph identifiers<br/>[ids.py]"]
end

node_user(("Explorer user"))
node_local_project["Local project"]

node_user -->|"chooses path"| node_app
node_local_project -->|"provides path"| node_ingest
node_app -->|"requests analysis"| node_client
node_app -->|"requests impact"| node_client
node_client -->|"posts analysis"| node_analyze_api
node_client -->|"posts impact"| node_impact_api
node_analyze_api -->|"validates path"| node_ingest
node_analyze_api -->|"runs analysis"| node_pipeline
node_impact_api -->|"reuses graph setup"| node_analyze_api
node_ingest -.->|"supplies root"| node_pipeline
node_pipeline -->|"scans root"| node_scan
node_pipeline -->|"parses files"| node_parse
node_pipeline -->|"selects parser"| node_language
node_pipeline -->|"resolves names"| node_resolve
node_pipeline -->|"produces graph facts"| node_facts
node_pipeline -->|"builds graph"| node_build
node_parse -->|"registered by"| node_language
node_facts -->|"uses resolution"| node_resolve
node_scan -->|"creates node ids"| node_ids
node_build -->|"returns CodeGraph"| node_query
node_query -->|"uses tree edge rules"| node_views
node_analyze_api -->|"collapses and filters"| node_views
node_query -.->|"uses persistence"| node_store
node_pipeline -->|"emits graph data"| node_model
node_build -->|"validates graph data"| node_model
node_app -->|"transforms impact"| node_transform
node_analyze_api -->|"returns graph document"| node_client
node_impact_api -->|"returns impact graph"| node_client
node_app -->|"renders controls"| node_sidebar
node_app -.->|"renders graph"| node_canvas2d
node_app -.->|"renders graph"| node_canvas3d
node_transform -->|"supplies elements"| node_canvas2d
node_transform -.->|"supplies elements"| node_canvas3d
node_canvas2d -->|"shows details"| node_detail
node_canvas3d -->|"shows details"| node_detail
node_canvas2d -->|"uses layout options"| node_layout
node_sidebar -->|"selects level"| node_levels
node_canvas2d -.->|"uses visual rules"| node_style
node_sidebar -->|"selects view"| node_graph_views

click node_ingest "https://github.com/jjwang1118/graphcode/blob/main/backend/app/ingest/local.py"
click node_scan "https://github.com/jjwang1118/graphcode/blob/main/backend/app/scan/walk.py"
click node_parse "https://github.com/jjwang1118/graphcode/blob/main/backend/app/parsers/python.py"
click node_language "https://github.com/jjwang1118/graphcode/blob/main/backend/app/languages/registry.py"
click node_facts "https://github.com/jjwang1118/graphcode/blob/main/backend/app/facts/production.py"
click node_resolve "https://github.com/jjwang1118/graphcode/tree/main/backend/app/resolve"
click node_pipeline "https://github.com/jjwang1118/graphcode/blob/main/backend/app/pipeline.py"
click node_build "https://github.com/jjwang1118/graphcode/blob/main/backend/app/graph/build.py"
click node_query "https://github.com/jjwang1118/graphcode/blob/main/backend/app/graph/query.py"
click node_views "https://github.com/jjwang1118/graphcode/blob/main/backend/app/graph/views.py"
click node_store "https://github.com/jjwang1118/graphcode/blob/main/backend/app/graph/store.py"
click node_analyze_api "https://github.com/jjwang1118/graphcode/blob/main/backend/app/api/analyze.py"
click node_impact_api "https://github.com/jjwang1118/graphcode/blob/main/backend/app/api/impact.py"
click node_model "https://github.com/jjwang1118/graphcode/blob/main/backend/app/models/graph.py"
click node_ids "https://github.com/jjwang1118/graphcode/blob/main/backend/app/models/ids.py"
click node_app "https://github.com/jjwang1118/graphcode/blob/main/frontend/src/App.tsx"
click node_client "https://github.com/jjwang1118/graphcode/blob/main/frontend/src/api/client.ts"
click node_transform "https://github.com/jjwang1118/graphcode/blob/main/frontend/src/graph/transform.ts"
click node_sidebar "https://github.com/jjwang1118/graphcode/blob/main/frontend/src/components/Sidebar.tsx"
click node_canvas2d "https://github.com/jjwang1118/graphcode/blob/main/frontend/src/components/GraphCanvas.tsx"
click node_canvas3d "https://github.com/jjwang1118/graphcode/blob/main/frontend/src/components/Graph3D.tsx"
click node_detail "https://github.com/jjwang1118/graphcode/blob/main/frontend/src/components/DetailBox.tsx"
click node_layout "https://github.com/jjwang1118/graphcode/blob/main/frontend/src/graph/layouts.ts"
click node_levels "https://github.com/jjwang1118/graphcode/blob/main/frontend/src/graph/levels.ts"
click node_style "https://github.com/jjwang1118/graphcode/blob/main/frontend/src/graph/style.ts"
click node_graph_views "https://github.com/jjwang1118/graphcode/blob/main/frontend/src/graph/views.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_ingest,node_scan,node_parse,node_language,node_facts,node_resolve,node_pipeline,node_build,node_query,node_views,node_store,node_analyze_api,node_impact_api,node_user toneBlue
class node_app,node_client,node_transform,node_sidebar,node_canvas2d,node_canvas3d,node_detail,node_layout,node_levels,node_style,node_graph_views toneAmber
class node_model,node_ids toneMint
class node_local_project toneIndigo
```

## Components

### Analysis backend

- [Safe ingestion](https://github.com/jjwang1118/graphcode/blob/main/backend/app/ingest/local.py): `backend/app/ingest/local.py`
- [Tree scan](https://github.com/jjwang1118/graphcode/blob/main/backend/app/scan/walk.py): `backend/app/scan/walk.py`
- [Python parser](https://github.com/jjwang1118/graphcode/blob/main/backend/app/parsers/python.py): `backend/app/parsers/python.py`
- [Language registry](https://github.com/jjwang1118/graphcode/blob/main/backend/app/languages/registry.py): `backend/app/languages/registry.py`
- [Fact production](https://github.com/jjwang1118/graphcode/blob/main/backend/app/facts/production.py): `backend/app/facts/production.py`
- [Name resolution](https://github.com/jjwang1118/graphcode/tree/main/backend/app/resolve): `backend/app/resolve`
- [Analysis pipeline](https://github.com/jjwang1118/graphcode/blob/main/backend/app/pipeline.py): `backend/app/pipeline.py`
- [Graph construction](https://github.com/jjwang1118/graphcode/blob/main/backend/app/graph/build.py): `backend/app/graph/build.py`
- [Graph queries](https://github.com/jjwang1118/graphcode/blob/main/backend/app/graph/query.py): `backend/app/graph/query.py`
- [Graph views](https://github.com/jjwang1118/graphcode/blob/main/backend/app/graph/views.py): `backend/app/graph/views.py`
- [Graph persistence](https://github.com/jjwang1118/graphcode/blob/main/backend/app/graph/store.py): `backend/app/graph/store.py`
- [Analyze API](https://github.com/jjwang1118/graphcode/blob/main/backend/app/api/analyze.py): `backend/app/api/analyze.py`
- [Impact API](https://github.com/jjwang1118/graphcode/blob/main/backend/app/api/impact.py): `backend/app/api/impact.py`

### Graph explorer

- [Explorer application](https://github.com/jjwang1118/graphcode/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/jjwang1118/graphcode/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Graph transform](https://github.com/jjwang1118/graphcode/blob/main/frontend/src/graph/transform.ts): `frontend/src/graph/transform.ts`
- [Explorer controls](https://github.com/jjwang1118/graphcode/blob/main/frontend/src/components/Sidebar.tsx): `frontend/src/components/Sidebar.tsx`
- [2D canvas](https://github.com/jjwang1118/graphcode/blob/main/frontend/src/components/GraphCanvas.tsx): `frontend/src/components/GraphCanvas.tsx`
- [3D canvas](https://github.com/jjwang1118/graphcode/blob/main/frontend/src/components/Graph3D.tsx): `frontend/src/components/Graph3D.tsx`
- [Node details](https://github.com/jjwang1118/graphcode/blob/main/frontend/src/components/DetailBox.tsx): `frontend/src/components/DetailBox.tsx`
- [Graph layouts](https://github.com/jjwang1118/graphcode/blob/main/frontend/src/graph/layouts.ts): `frontend/src/graph/layouts.ts`
- [Level selection](https://github.com/jjwang1118/graphcode/blob/main/frontend/src/graph/levels.ts): `frontend/src/graph/levels.ts`
- [Graph styling](https://github.com/jjwang1118/graphcode/blob/main/frontend/src/graph/style.ts): `frontend/src/graph/style.ts`
- [Explorer views](https://github.com/jjwang1118/graphcode/blob/main/frontend/src/graph/views.ts): `frontend/src/graph/views.ts`

### Graph model

- [Graph schema](https://github.com/jjwang1118/graphcode/blob/main/backend/app/models/graph.py): `backend/app/models/graph.py`
- [Graph identifiers](https://github.com/jjwang1118/graphcode/blob/main/backend/app/models/ids.py): `backend/app/models/ids.py`

### Other components

- **Explorer user**
- **Local project**

## Connections

- Explorer user → Explorer application: chooses path (evidence: `frontend/src/App.tsx`)
- Local project → Safe ingestion: provides path (evidence: `README.md`)
- Explorer application → API client: requests analysis (evidence: `frontend/src/App.tsx`)
- Explorer application → API client: requests impact (evidence: `frontend/src/App.tsx`)
- API client → Analyze API: posts analysis (evidence: `frontend/src/api/client.ts`)
- API client → Impact API: posts impact (evidence: `frontend/src/api/client.ts`)
- Analyze API → Safe ingestion: validates path (evidence: `backend/app/api/analyze.py`)
- Analyze API → Analysis pipeline: runs analysis (evidence: `backend/app/api/analyze.py`)
- Impact API → Analyze API: reuses graph setup (evidence: `backend/app/api/impact.py`)
- Safe ingestion → Analysis pipeline: supplies root
- Analysis pipeline → Tree scan: scans root (evidence: `backend/app/pipeline.py`)
- Analysis pipeline → Python parser: parses files (evidence: `backend/app/pipeline.py`)
- Analysis pipeline → Language registry: selects parser (evidence: `backend/app/pipeline.py`)
- Analysis pipeline → Name resolution: resolves names (evidence: `backend/app/pipeline.py`)
- Analysis pipeline → Fact production: produces graph facts (evidence: `backend/app/pipeline.py`)
- Analysis pipeline → Graph construction: builds graph (evidence: `backend/app/pipeline.py`)
- Python parser → Language registry: registered by (evidence: `backend/app/languages/registry.py`)
- Fact production → Name resolution: uses resolution (evidence: `backend/app/facts/production.py`)
- Tree scan → Graph identifiers: creates node ids (evidence: `backend/app/scan/walk.py`)
- Graph construction → Graph queries: returns CodeGraph (evidence: `backend/app/graph/build.py`)
- Graph queries → Graph views: uses tree edge rules (evidence: `backend/app/graph/query.py`)
- Analyze API → Graph views: collapses and filters (evidence: `backend/app/api/analyze.py`)
- Graph queries → Graph persistence: uses persistence
- Analysis pipeline → Graph schema: emits graph data (evidence: `backend/app/pipeline.py`)
- Graph construction → Graph schema: validates graph data (evidence: `backend/app/graph/build.py`)
- Explorer application → Graph transform: transforms impact (evidence: `frontend/src/App.tsx`)
- Analyze API → API client: returns graph document (evidence: `README.md`)
- Impact API → API client: returns impact graph (evidence: `README.md`)
- Explorer application → Explorer controls: renders controls (evidence: `frontend/src/App.tsx`)
- Explorer application → 2D canvas: renders graph (evidence: `frontend/src/App.tsx`)
- Explorer application → 3D canvas: renders graph (evidence: `frontend/src/App.tsx`)
- Graph transform → 2D canvas: supplies elements (evidence: `frontend/src/components/GraphCanvas.tsx`)
- Graph transform → 3D canvas: supplies elements (evidence: `frontend/src/components/Graph3D.tsx`)
- 2D canvas → Node details: shows details (evidence: `frontend/src/components/GraphCanvas.tsx`)
- 3D canvas → Node details: shows details (evidence: `frontend/src/components/Graph3D.tsx`)
- 2D canvas → Graph layouts: uses layout options (evidence: `frontend/src/components/GraphCanvas.tsx`)
- Explorer controls → Level selection: selects level (evidence: `frontend/src/components/Sidebar.tsx`)
- 2D canvas → Graph styling: uses visual rules (evidence: `frontend/src/components/GraphCanvas.tsx`)
- Explorer controls → Explorer views: selects view (evidence: `frontend/src/components/Sidebar.tsx`)
