# poorav007/speccraftai architecture

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

- Interactive diagram: https://gitdiagram.com/poorav007/speccraftai
- Repository: https://github.com/poorav007/speccraftai

## Overview

SpecCraft AI is an API-specification generator with a lightweight browser uploader/route-preview workflow and a separate Python static-analysis pipeline. In the shown frontend flow, a user submits code through the import page, the client parser builds a minimal OpenAPI preview, and the app persists the result in browser storage. The repository also names editor, validation, diff, export, viewer, and history capabilities. Backend excerpts show safe source ingestion and FastAPI AST extraction; they do not show frontend-to-backend wiring, so the two flows remain separate here.

Main entry points: [`backend/speccraft/parser/fastapi_adapter.py`](https://github.com/poorav007/speccraftai/blob/main/backend/speccraft/parser/fastapi_adapter.py) (FastAPI parser), [`backend/speccraft/models.py`](https://github.com/poorav007/speccraftai/blob/main/backend/speccraft/models.py) (Source models), [`frontend/src/pages/CodebaseImportPage.jsx`](https://github.com/poorav007/speccraftai/blob/main/frontend/src/pages/CodebaseImportPage.jsx) (Code import), [`frontend/src/App.jsx`](https://github.com/poorav007/speccraftai/blob/main/frontend/src/App.jsx) (App state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser workflow"]
  node_import_page["Code import"]
  node_uploader["Project uploader"]
  node_client_parser["Route parser<br/>[parser.js]"]
  node_app["App state<br/>[App.jsx]"]
  node_browser_store[("Browser storage<br/>[localStorage.js]")]
end

subgraph group_backend["Static analysis"]
  node_source_reader["Source reader<br/>[reader.py]"]
  node_path_safety["Path safety<br/>[path_safety.py]"]
  node_source_models["Source models<br/>[models.py]"]
  node_parser_contract["Parser contract<br/>[base.py]"]
  node_fastapi_parser["FastAPI parser<br/>[fastapi_adapter.py]"]
  node_schema_builder["Schema builder<br/>[schema_builder.py]"]
  node_diagnostics["Diagnostics<br/>[diagnostics.py]"]
  node_timing["Parse timing<br/>[timing.py]"]
end

subgraph group_capabilities["Spec lifecycle"]
  node_ast_analysis["AST analysis"]
  node_spec_editor["Spec editor"]
  node_validation["Validation results"]
  node_diff["Spec comparison"]
  node_export["Spec export"]
  node_viewer["Interactive viewer"]
  node_history["Settings and history"]
end

node_user(("Engineer"))

node_user -->|"submits code"| node_import_page
node_import_page -->|"renders"| node_uploader
node_uploader -->|"parses routes"| node_client_parser
node_app -->|"renders"| node_import_page
node_app -->|"loads and saves"| node_browser_store
node_source_reader -->|"validates paths"| node_path_safety
node_source_reader -->|"creates source files"| node_source_models
node_parser_contract -->|"uses result models"| node_source_models
node_fastapi_parser -->|"builds extraction results"| node_source_models
node_fastapi_parser -->|"implements contract"| node_parser_contract
node_fastapi_parser -->|"uses schema extraction"| node_schema_builder
node_fastapi_parser -->|"measures parsing"| node_timing
node_source_models -->|"includes diagnostics"| node_diagnostics

click node_import_page "https://github.com/poorav007/speccraftai/blob/main/frontend/src/pages/CodebaseImportPage.jsx"
click node_uploader "https://github.com/poorav007/speccraftai/blob/main/frontend/src/components/import/ProjectUploader.jsx"
click node_client_parser "https://github.com/poorav007/speccraftai/blob/main/frontend/src/utils/parser.js"
click node_app "https://github.com/poorav007/speccraftai/blob/main/frontend/src/App.jsx"
click node_browser_store "https://github.com/poorav007/speccraftai/blob/main/frontend/src/utils/localStorage.js"
click node_source_reader "https://github.com/poorav007/speccraftai/blob/main/backend/speccraft/reader.py"
click node_path_safety "https://github.com/poorav007/speccraftai/blob/main/backend/speccraft/utils/path_safety.py"
click node_source_models "https://github.com/poorav007/speccraftai/blob/main/backend/speccraft/models.py"
click node_parser_contract "https://github.com/poorav007/speccraftai/blob/main/backend/speccraft/parser/base.py"
click node_fastapi_parser "https://github.com/poorav007/speccraftai/blob/main/backend/speccraft/parser/fastapi_adapter.py"
click node_schema_builder "https://github.com/poorav007/speccraftai/blob/main/backend/speccraft/schema_builder.py"
click node_diagnostics "https://github.com/poorav007/speccraftai/blob/main/backend/speccraft/diagnostics.py"
click node_timing "https://github.com/poorav007/speccraftai/blob/main/backend/speccraft/utils/timing.py"
click node_ast_analysis "https://github.com/poorav007/speccraftai/blob/main/frontend/src/pages/AstAnalysisPage.jsx"
click node_spec_editor "https://github.com/poorav007/speccraftai/blob/main/frontend/src/pages/SpecificationEditorPage.jsx"
click node_validation "https://github.com/poorav007/speccraftai/blob/main/frontend/src/pages/ValidationResultsPage.jsx"
click node_diff "https://github.com/poorav007/speccraftai/blob/main/frontend/src/pages/SpecificationDiffPage.jsx"
click node_export "https://github.com/poorav007/speccraftai/blob/main/frontend/src/pages/ExportCenterPage.jsx"
click node_viewer "https://github.com/poorav007/speccraftai/blob/main/frontend/src/pages/InteractiveViewerPage.jsx"
click node_history "https://github.com/poorav007/speccraftai/blob/main/frontend/src/pages/SettingsHistoryPage.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_import_page,node_uploader,node_client_parser,node_app,node_browser_store toneBlue
class node_source_reader,node_path_safety,node_source_models,node_parser_contract,node_fastapi_parser,node_schema_builder,node_diagnostics,node_timing toneAmber
class node_ast_analysis,node_spec_editor,node_validation,node_diff,node_export,node_viewer,node_history toneMint
class node_user toneIndigo
```

## Components

### Browser workflow

- [Code import](https://github.com/poorav007/speccraftai/blob/main/frontend/src/pages/CodebaseImportPage.jsx): `frontend/src/pages/CodebaseImportPage.jsx`
- [Project uploader](https://github.com/poorav007/speccraftai/blob/main/frontend/src/components/import/ProjectUploader.jsx): `frontend/src/components/import/ProjectUploader.jsx`
- [Route parser](https://github.com/poorav007/speccraftai/blob/main/frontend/src/utils/parser.js): `frontend/src/utils/parser.js`
- [App state](https://github.com/poorav007/speccraftai/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Browser storage](https://github.com/poorav007/speccraftai/blob/main/frontend/src/utils/localStorage.js): `frontend/src/utils/localStorage.js`

### Static analysis

- [Source reader](https://github.com/poorav007/speccraftai/blob/main/backend/speccraft/reader.py): `backend/speccraft/reader.py`
- [Path safety](https://github.com/poorav007/speccraftai/blob/main/backend/speccraft/utils/path_safety.py): `backend/speccraft/utils/path_safety.py`
- [Source models](https://github.com/poorav007/speccraftai/blob/main/backend/speccraft/models.py): `backend/speccraft/models.py`
- [Parser contract](https://github.com/poorav007/speccraftai/blob/main/backend/speccraft/parser/base.py): `backend/speccraft/parser/base.py`
- [FastAPI parser](https://github.com/poorav007/speccraftai/blob/main/backend/speccraft/parser/fastapi_adapter.py): `backend/speccraft/parser/fastapi_adapter.py`
- [Schema builder](https://github.com/poorav007/speccraftai/blob/main/backend/speccraft/schema_builder.py): `backend/speccraft/schema_builder.py`
- [Diagnostics](https://github.com/poorav007/speccraftai/blob/main/backend/speccraft/diagnostics.py): `backend/speccraft/diagnostics.py`
- [Parse timing](https://github.com/poorav007/speccraftai/blob/main/backend/speccraft/utils/timing.py): `backend/speccraft/utils/timing.py`

### Spec lifecycle

- [AST analysis](https://github.com/poorav007/speccraftai/blob/main/frontend/src/pages/AstAnalysisPage.jsx): `frontend/src/pages/AstAnalysisPage.jsx`
- [Spec editor](https://github.com/poorav007/speccraftai/blob/main/frontend/src/pages/SpecificationEditorPage.jsx): `frontend/src/pages/SpecificationEditorPage.jsx`
- [Validation results](https://github.com/poorav007/speccraftai/blob/main/frontend/src/pages/ValidationResultsPage.jsx): `frontend/src/pages/ValidationResultsPage.jsx`
- [Spec comparison](https://github.com/poorav007/speccraftai/blob/main/frontend/src/pages/SpecificationDiffPage.jsx): `frontend/src/pages/SpecificationDiffPage.jsx`
- [Spec export](https://github.com/poorav007/speccraftai/blob/main/frontend/src/pages/ExportCenterPage.jsx): `frontend/src/pages/ExportCenterPage.jsx`
- [Interactive viewer](https://github.com/poorav007/speccraftai/blob/main/frontend/src/pages/InteractiveViewerPage.jsx): `frontend/src/pages/InteractiveViewerPage.jsx`
- [Settings and history](https://github.com/poorav007/speccraftai/blob/main/frontend/src/pages/SettingsHistoryPage.jsx): `frontend/src/pages/SettingsHistoryPage.jsx`

### Other components

- **Engineer**

## Connections

- Engineer → Code import: submits code (evidence: `frontend/src/pages/CodebaseImportPage.jsx`)
- Code import → Project uploader: renders (evidence: `frontend/src/pages/CodebaseImportPage.jsx`)
- Project uploader → Route parser: parses routes (evidence: `frontend/src/components/import/ProjectUploader.jsx`)
- App state → Code import: renders (evidence: `frontend/src/App.jsx`)
- App state → Browser storage: loads and saves (evidence: `frontend/src/App.jsx`)
- Source reader → Path safety: validates paths (evidence: `backend/speccraft/reader.py`)
- Source reader → Source models: creates source files (evidence: `backend/speccraft/reader.py`)
- Parser contract → Source models: uses result models (evidence: `backend/speccraft/parser/base.py`)
- FastAPI parser → Source models: builds extraction results (evidence: `backend/speccraft/parser/fastapi_adapter.py`)
- FastAPI parser → Parser contract: implements contract (evidence: `backend/speccraft/parser/fastapi_adapter.py`)
- FastAPI parser → Schema builder: uses schema extraction (evidence: `backend/speccraft/parser/fastapi_adapter.py`)
- FastAPI parser → Parse timing: measures parsing (evidence: `backend/speccraft/parser/fastapi_adapter.py`)
- Source models → Diagnostics: includes diagnostics (evidence: `backend/speccraft/models.py`)
