# joseph-k-iype/arch-scan architecture

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

- Interactive diagram: https://gitdiagram.com/joseph-k-iype/arch-scan
- Repository: https://github.com/joseph-k-iype/arch-scan

## Overview

Archiscan scans Git repositories into versioned, evidence-backed architecture snapshots, which users browse, compare, export, correct, and attest in a React dashboard. The principal backend workflow acquires Git objects, extracts and resolves facts, optionally investigates bounded claims with an LLM, then publishes a snapshot. The graph also preserves documented agent/trace, webhook, MCP, and human-review capabilities. Relationships are limited to excerpted calls, SOURCE INDEX references, or README statements; some capability implementations were not sampled, so their links cite documentation rather than implying inspected internals.

Main entry points: [`backend/scanner.py`](https://github.com/joseph-k-iype/arch-scan/blob/main/backend/scanner.py) (Scan orchestration), [`backend/app.py`](https://github.com/joseph-k-iype/arch-scan/blob/main/backend/app.py) (REST API), [`backend/llm.py`](https://github.com/joseph-k-iype/arch-scan/blob/main/backend/llm.py) (LLM investigation), [`src/App.tsx`](https://github.com/joseph-k-iype/arch-scan/blob/main/src/App.tsx) (Workspace dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_acquisition["Scan pipeline"]
  node_git["Git acquisition<br/>[git.py]"]
  node_scanner["Scan orchestration<br/>[scanner.py]"]
end

subgraph group_facts["Architecture facts"]
  node_extract["Static extraction<br/>[extract.py]"]
  node_catalog["Pattern catalog<br/>[catalog.py]"]
  node_analysis["Logical analysis"]
  node_investigator["LLM investigation<br/>[llm.py]"]
end

subgraph group_platform["Platform services"]
  node_artifact[("Extraction artifacts<br/>[storage.py]")]
  node_database[("Versioned fact store<br/>[models.py]")]
  node_api["REST API<br/>[app.py]"]
  node_services["Graph and snapshot queries<br/>[services.py]"]
  node_auth["Identity and access<br/>[auth.py]"]
  node_review["Review operations<br/>[app.py]"]
end

subgraph group_experience["Dashboard"]
  node_dashboard["Workspace dashboard<br/>[App.tsx]"]
  node_client["API client<br/>[api.ts]"]
  node_explorer["Architecture explorer"]
  node_graph["Graph rendering"]
end

subgraph group_extensions["Integrations"]
  node_claude["Claude adapter"]
  node_webhook["GitHub webhooks<br/>[app.py]"]
  node_mcp["MCP server<br/>[mcp_server.py]"]
  node_gateway["LLM gateway<br/>[gateway.py]"]
  node_traces["Agent observations<br/>[app.py]"]
end

node_user(("Repository reviewer"))
node_provider["Git hosting"]
node_llmservice["OpenAI-compatible endpoint"]

node_user -->|"uses"| node_dashboard
node_dashboard -->|"requests data"| node_client
node_dashboard -->|"opens explorer"| node_explorer
node_explorer -->|"loads graph"| node_client
node_explorer -->|"renders diagram"| node_graph
node_client -->|"calls REST"| node_api
node_api -->|"authorizes requests"| node_auth
node_api -->|"starts scans"| node_scanner
node_scanner -->|"acquires commit"| node_git
node_provider -->|"supplies objects"| node_git
node_scanner -->|"extracts blobs"| node_extract
node_scanner -->|"caches artifacts"| node_artifact
node_extract -->|"recognizes patterns"| node_catalog
node_scanner -->|"investigates claims"| node_investigator
node_scanner -->|"builds logical layers"| node_analysis
node_investigator -->|"delegates optionally"| node_claude
node_investigator -->|"judges claims"| node_llmservice
node_scanner -->|"publishes snapshot"| node_database
node_api -->|"queries graph"| node_services
node_services -->|"reads facts"| node_database
node_api -->|"supports review"| node_review
node_user -->|"corrects and attests"| node_review
node_api -->|"receives pushes"| node_webhook
node_webhook -->|"triggers scans"| node_scanner
node_user -.->|"uses authenticated tools"| node_mcp
node_gateway -->|"forwards requests"| node_llmservice
node_api -->|"imports observations"| node_traces

click node_git "https://github.com/joseph-k-iype/arch-scan/blob/main/backend/git.py"
click node_scanner "https://github.com/joseph-k-iype/arch-scan/blob/main/backend/scanner.py"
click node_extract "https://github.com/joseph-k-iype/arch-scan/blob/main/backend/extract.py"
click node_catalog "https://github.com/joseph-k-iype/arch-scan/blob/main/backend/catalog.py"
click node_analysis "https://github.com/joseph-k-iype/arch-scan/blob/main/backend/architecture_analysis.py"
click node_investigator "https://github.com/joseph-k-iype/arch-scan/blob/main/backend/llm.py"
click node_claude "https://github.com/joseph-k-iype/arch-scan/blob/main/backend/claude_investigator.py"
click node_artifact "https://github.com/joseph-k-iype/arch-scan/blob/main/backend/storage.py"
click node_database "https://github.com/joseph-k-iype/arch-scan/blob/main/backend/models.py"
click node_api "https://github.com/joseph-k-iype/arch-scan/blob/main/backend/app.py"
click node_services "https://github.com/joseph-k-iype/arch-scan/blob/main/backend/services.py"
click node_auth "https://github.com/joseph-k-iype/arch-scan/blob/main/backend/auth.py"
click node_dashboard "https://github.com/joseph-k-iype/arch-scan/blob/main/src/App.tsx"
click node_client "https://github.com/joseph-k-iype/arch-scan/blob/main/src/api.ts"
click node_explorer "https://github.com/joseph-k-iype/arch-scan/blob/main/src/components/ArchitectureExplorer.tsx"
click node_graph "https://github.com/joseph-k-iype/arch-scan/blob/main/src/components/ArchitectureGraph.tsx"
click node_review "https://github.com/joseph-k-iype/arch-scan/blob/main/backend/app.py"
click node_webhook "https://github.com/joseph-k-iype/arch-scan/blob/main/backend/app.py"
click node_mcp "https://github.com/joseph-k-iype/arch-scan/blob/main/backend/mcp_server.py"
click node_gateway "https://github.com/joseph-k-iype/arch-scan/blob/main/backend/gateway.py"
click node_traces "https://github.com/joseph-k-iype/arch-scan/blob/main/backend/app.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_git,node_scanner,node_user toneBlue
class node_extract,node_catalog,node_analysis,node_investigator toneAmber
class node_artifact,node_database,node_api,node_services,node_auth,node_review toneMint
class node_dashboard,node_client,node_explorer,node_graph toneRose
class node_claude,node_webhook,node_mcp,node_gateway,node_traces,node_provider,node_llmservice toneIndigo
```

## Components

### Scan pipeline

- [Git acquisition](https://github.com/joseph-k-iype/arch-scan/blob/main/backend/git.py): `backend/git.py`
- [Scan orchestration](https://github.com/joseph-k-iype/arch-scan/blob/main/backend/scanner.py): `backend/scanner.py`

### Architecture facts

- [Static extraction](https://github.com/joseph-k-iype/arch-scan/blob/main/backend/extract.py): `backend/extract.py`
- [Pattern catalog](https://github.com/joseph-k-iype/arch-scan/blob/main/backend/catalog.py): `backend/catalog.py`
- [Logical analysis](https://github.com/joseph-k-iype/arch-scan/blob/main/backend/architecture_analysis.py): `backend/architecture_analysis.py`
- [LLM investigation](https://github.com/joseph-k-iype/arch-scan/blob/main/backend/llm.py): `backend/llm.py`

### Platform services

- [Extraction artifacts](https://github.com/joseph-k-iype/arch-scan/blob/main/backend/storage.py): `backend/storage.py`
- [Versioned fact store](https://github.com/joseph-k-iype/arch-scan/blob/main/backend/models.py): `backend/models.py`
- [REST API](https://github.com/joseph-k-iype/arch-scan/blob/main/backend/app.py): `backend/app.py`
- [Graph and snapshot queries](https://github.com/joseph-k-iype/arch-scan/blob/main/backend/services.py): `backend/services.py`
- [Identity and access](https://github.com/joseph-k-iype/arch-scan/blob/main/backend/auth.py): `backend/auth.py`
- [Review operations](https://github.com/joseph-k-iype/arch-scan/blob/main/backend/app.py): `backend/app.py`

### Dashboard

- [Workspace dashboard](https://github.com/joseph-k-iype/arch-scan/blob/main/src/App.tsx): `src/App.tsx`
- [API client](https://github.com/joseph-k-iype/arch-scan/blob/main/src/api.ts): `src/api.ts`
- [Architecture explorer](https://github.com/joseph-k-iype/arch-scan/blob/main/src/components/ArchitectureExplorer.tsx): `src/components/ArchitectureExplorer.tsx`
- [Graph rendering](https://github.com/joseph-k-iype/arch-scan/blob/main/src/components/ArchitectureGraph.tsx): `src/components/ArchitectureGraph.tsx`

### Integrations

- [Claude adapter](https://github.com/joseph-k-iype/arch-scan/blob/main/backend/claude_investigator.py): `backend/claude_investigator.py`
- [GitHub webhooks](https://github.com/joseph-k-iype/arch-scan/blob/main/backend/app.py): `backend/app.py`
- [MCP server](https://github.com/joseph-k-iype/arch-scan/blob/main/backend/mcp_server.py): `backend/mcp_server.py`
- [LLM gateway](https://github.com/joseph-k-iype/arch-scan/blob/main/backend/gateway.py): `backend/gateway.py`
- [Agent observations](https://github.com/joseph-k-iype/arch-scan/blob/main/backend/app.py): `backend/app.py`

### Other components

- **Repository reviewer**
- **Git hosting**
- **OpenAI-compatible endpoint**

## Connections

- Repository reviewer → Workspace dashboard: uses (evidence: `README.md`)
- Workspace dashboard → API client: requests data (evidence: `src/App.tsx`)
- Workspace dashboard → Architecture explorer: opens explorer (evidence: `src/App.tsx`)
- Architecture explorer → API client: loads graph (evidence: `src/components/ArchitectureExplorer.tsx`)
- Architecture explorer → Graph rendering: renders diagram
- API client → REST API: calls REST (evidence: `README.md`)
- REST API → Identity and access: authorizes requests (evidence: `backend/app.py`)
- REST API → Scan orchestration: starts scans (evidence: `backend/app.py`)
- Scan orchestration → Git acquisition: acquires commit (evidence: `backend/scanner.py`)
- Git hosting → Git acquisition: supplies objects (evidence: `README.md`)
- Scan orchestration → Static extraction: extracts blobs (evidence: `backend/scanner.py`)
- Scan orchestration → Extraction artifacts: caches artifacts (evidence: `backend/scanner.py`)
- Static extraction → Pattern catalog: recognizes patterns (evidence: `README.md`)
- Scan orchestration → LLM investigation: investigates claims (evidence: `backend/scanner.py`)
- Scan orchestration → Logical analysis: builds logical layers (evidence: `backend/scanner.py`)
- LLM investigation → Claude adapter: delegates optionally (evidence: `backend/llm.py`)
- LLM investigation → OpenAI-compatible endpoint: judges claims (evidence: `README.md`)
- Scan orchestration → Versioned fact store: publishes snapshot (evidence: `README.md`)
- REST API → Graph and snapshot queries: queries graph (evidence: `backend/app.py`)
- Graph and snapshot queries → Versioned fact store: reads facts (evidence: `backend/services.py`)
- REST API → Review operations: supports review (evidence: `README.md`)
- Repository reviewer → Review operations: corrects and attests (evidence: `README.md`)
- REST API → GitHub webhooks: receives pushes (evidence: `README.md`)
- GitHub webhooks → Scan orchestration: triggers scans (evidence: `README.md`)
- Repository reviewer → MCP server: uses authenticated tools (evidence: `README.md`)
- LLM gateway → OpenAI-compatible endpoint: forwards requests (evidence: `README.md`)
- REST API → Agent observations: imports observations (evidence: `README.md`)
