# psdwtf/ai-pcb-generator architecture

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

- Interactive diagram: https://gitdiagram.com/psdwtf/ai-pcb-generator
- Repository: https://github.com/psdwtf/ai-pcb-generator

## Overview

This is a FastAPI web studio and REST API for turning circuit descriptions, netlists, or schematic images into routed KiCad boards and manufacturing exports. Its main workflow submits a generation job, builds a board, optionally simulates and checks it, routes it, exports artifacts, then exposes status, preview, and downloads. The README documents the end-to-end KiCad/FreeRouting/export stages; source-index references and excerpts support the backend links. Some service internals and UI wiring were not sampled, so those relationships are omitted where not documented.

Main entry points: [`app/services/job_manager.py`](https://github.com/psdwtf/ai-pcb-generator/blob/main/app/services/job_manager.py) (Job Pipeline), [`app/main.py`](https://github.com/psdwtf/ai-pcb-generator/blob/main/app/main.py) (FastAPI Application), [`app/services/kicad_service.py`](https://github.com/psdwtf/ai-pcb-generator/blob/main/app/services/kicad_service.py) (KiCad Export & Import), [`app/routes/pcb.py`](https://github.com/psdwtf/ai-pcb-generator/blob/main/app/routes/pcb.py) (PCB Endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web Interface"]
  node_dashboard["Web Dashboard<br/>[ui.py]"]
  node_browser_ui["Interactive UI<br/>[app.js]"]
end

subgraph group_api["API &amp; Jobs"]
  node_pcb_api["PCB Endpoints<br/>[pcb.py]"]
  node_job_api["Job Status &amp; Files<br/>[jobs.py]"]
  node_job_manager["Job Pipeline<br/>[job_manager.py]"]
  node_job_state[("Job State &amp; Artifacts<br/>[job_manager.py]")]
  node_schemas["Request &amp; Job Models<br/>[schemas.py]"]
  node_config["Runtime Configuration<br/>[config.py]"]
  node_app_entry["FastAPI Application<br/>[main.py]"]
end

subgraph group_design["Circuit Design"]
  node_image_parser["Schematic Image Parser<br/>[image_parser.py]"]
  node_llm_design["AI Circuit Design<br/>[llm.py]"]
  node_circuit_generator["Board Generator"]
  node_hardware_assistant["Hardware Guidance"]
end

subgraph group_checks["Analysis &amp; Checks"]
  node_simulation["SPICE Simulation<br/>[simulator.py]"]
  node_thermal_drc["Thermal Trace DRC<br/>[drc.py]"]
  node_trace_calc["Trace Calculator<br/>[calculator.py]"]
  node_legacy_auditor["Legacy Netlist Audit<br/>[llm_auditor.py]"]
  node_audit_db[("Audit Records<br/>[db.py]")]
end

subgraph group_board["Routing &amp; Fabrication"]
  node_kicad["KiCad Export &amp; Import<br/>[kicad_service.py]"]
  node_freerouting["Auto-Router"]
  node_kicad_cli["KiCad CLI"]
  node_java_router["Java FreeRouting"]
end

node_user(("Circuit Designer"))
node_gemini["Gemini API"]

node_user -->|"uses"| node_dashboard
node_dashboard -->|"serves"| node_browser_ui
node_user -->|"submits design"| node_pcb_api
node_pcb_api -->|"queues job"| node_job_manager
node_pcb_api -->|"parses upload"| node_image_parser
node_job_manager -->|"updates"| node_job_state
node_job_api -->|"reads status"| node_job_state
node_job_api -->|"serves artifacts"| node_job_state
node_app_entry -->|"registers routes"| node_pcb_api
node_app_entry -->|"registers routes"| node_job_api
node_job_manager -->|"requests design"| node_llm_design
node_job_manager -->|"generates board"| node_circuit_generator
node_job_manager -->|"runs simulation"| node_simulation
node_job_manager -->|"checks traces"| node_thermal_drc
node_job_manager -->|"exports layout"| node_kicad
node_job_manager -->|"routes board"| node_freerouting
node_kicad -->|"exports DSN"| node_freerouting
node_freerouting -->|"runs routing"| node_java_router
node_freerouting -->|"returns SES"| node_kicad
node_kicad -->|"exports fabrication"| node_kicad_cli
node_llm_design -->|"requests generation"| node_gemini
node_app_entry -->|"calculates traces"| node_trace_calc
node_app_entry -->|"gets guidance"| node_hardware_assistant
node_app_entry -->|"calls legacy audit"| node_legacy_auditor
node_app_entry -->|"reads audit records"| node_audit_db
node_user -->|"polls and downloads"| node_job_api
node_kicad -.->|"stores exports"| node_job_state

click node_dashboard "https://github.com/psdwtf/ai-pcb-generator/blob/main/app/routes/ui.py"
click node_browser_ui "https://github.com/psdwtf/ai-pcb-generator/blob/main/app/static/js/app.js"
click node_pcb_api "https://github.com/psdwtf/ai-pcb-generator/blob/main/app/routes/pcb.py"
click node_job_api "https://github.com/psdwtf/ai-pcb-generator/blob/main/app/routes/jobs.py"
click node_job_manager "https://github.com/psdwtf/ai-pcb-generator/blob/main/app/services/job_manager.py"
click node_job_state "https://github.com/psdwtf/ai-pcb-generator/blob/main/app/services/job_manager.py"
click node_schemas "https://github.com/psdwtf/ai-pcb-generator/blob/main/app/models/schemas.py"
click node_config "https://github.com/psdwtf/ai-pcb-generator/blob/main/app/config.py"
click node_app_entry "https://github.com/psdwtf/ai-pcb-generator/blob/main/app/main.py"
click node_image_parser "https://github.com/psdwtf/ai-pcb-generator/blob/main/app/services/image_parser.py"
click node_llm_design "https://github.com/psdwtf/ai-pcb-generator/blob/main/app/services/llm.py"
click node_circuit_generator "https://github.com/psdwtf/ai-pcb-generator/blob/main/app/services/circuit_generator.py"
click node_simulation "https://github.com/psdwtf/ai-pcb-generator/blob/main/app/services/simulator.py"
click node_thermal_drc "https://github.com/psdwtf/ai-pcb-generator/blob/main/app/services/drc.py"
click node_trace_calc "https://github.com/psdwtf/ai-pcb-generator/blob/main/app/services/calculator.py"
click node_legacy_auditor "https://github.com/psdwtf/ai-pcb-generator/blob/main/app/llm_auditor.py"
click node_audit_db "https://github.com/psdwtf/ai-pcb-generator/blob/main/app/db.py"
click node_kicad "https://github.com/psdwtf/ai-pcb-generator/blob/main/app/services/kicad_service.py"
click node_freerouting "https://github.com/psdwtf/ai-pcb-generator/blob/main/app/services/freerouting_service.py"
click node_hardware_assistant "https://github.com/psdwtf/ai-pcb-generator/blob/main/app/services/hardware_assistant.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_dashboard,node_browser_ui toneBlue
class node_pcb_api,node_job_api,node_job_manager,node_job_state,node_schemas,node_config,node_app_entry toneAmber
class node_image_parser,node_llm_design,node_circuit_generator,node_hardware_assistant,node_gemini toneMint
class node_simulation,node_thermal_drc,node_trace_calc,node_legacy_auditor,node_audit_db toneRose
class node_kicad,node_freerouting,node_kicad_cli,node_java_router,node_user toneIndigo
```

## Components

### Web Interface

- [Web Dashboard](https://github.com/psdwtf/ai-pcb-generator/blob/main/app/routes/ui.py): `app/routes/ui.py`
- [Interactive UI](https://github.com/psdwtf/ai-pcb-generator/blob/main/app/static/js/app.js): `app/static/js/app.js`

### API & Jobs

- [PCB Endpoints](https://github.com/psdwtf/ai-pcb-generator/blob/main/app/routes/pcb.py): `app/routes/pcb.py`
- [Job Status & Files](https://github.com/psdwtf/ai-pcb-generator/blob/main/app/routes/jobs.py): `app/routes/jobs.py`
- [Job Pipeline](https://github.com/psdwtf/ai-pcb-generator/blob/main/app/services/job_manager.py): `app/services/job_manager.py`
- [Job State & Artifacts](https://github.com/psdwtf/ai-pcb-generator/blob/main/app/services/job_manager.py): `app/services/job_manager.py`
- [Request & Job Models](https://github.com/psdwtf/ai-pcb-generator/blob/main/app/models/schemas.py): `app/models/schemas.py`
- [Runtime Configuration](https://github.com/psdwtf/ai-pcb-generator/blob/main/app/config.py): `app/config.py`
- [FastAPI Application](https://github.com/psdwtf/ai-pcb-generator/blob/main/app/main.py): `app/main.py`

### Circuit Design

- [Schematic Image Parser](https://github.com/psdwtf/ai-pcb-generator/blob/main/app/services/image_parser.py): `app/services/image_parser.py`
- [AI Circuit Design](https://github.com/psdwtf/ai-pcb-generator/blob/main/app/services/llm.py): `app/services/llm.py`
- [Board Generator](https://github.com/psdwtf/ai-pcb-generator/blob/main/app/services/circuit_generator.py): `app/services/circuit_generator.py`
- [Hardware Guidance](https://github.com/psdwtf/ai-pcb-generator/blob/main/app/services/hardware_assistant.py): `app/services/hardware_assistant.py`

### Analysis & Checks

- [SPICE Simulation](https://github.com/psdwtf/ai-pcb-generator/blob/main/app/services/simulator.py): `app/services/simulator.py`
- [Thermal Trace DRC](https://github.com/psdwtf/ai-pcb-generator/blob/main/app/services/drc.py): `app/services/drc.py`
- [Trace Calculator](https://github.com/psdwtf/ai-pcb-generator/blob/main/app/services/calculator.py): `app/services/calculator.py`
- [Legacy Netlist Audit](https://github.com/psdwtf/ai-pcb-generator/blob/main/app/llm_auditor.py): `app/llm_auditor.py`
- [Audit Records](https://github.com/psdwtf/ai-pcb-generator/blob/main/app/db.py): `app/db.py`

### Routing & Fabrication

- [KiCad Export & Import](https://github.com/psdwtf/ai-pcb-generator/blob/main/app/services/kicad_service.py): `app/services/kicad_service.py`
- [Auto-Router](https://github.com/psdwtf/ai-pcb-generator/blob/main/app/services/freerouting_service.py): `app/services/freerouting_service.py`
- **KiCad CLI**
- **Java FreeRouting**

### Other components

- **Circuit Designer**
- **Gemini API**

## Connections

- Circuit Designer → Web Dashboard: uses (evidence: `README.md`)
- Web Dashboard → Interactive UI: serves (evidence: `README.md`)
- Circuit Designer → PCB Endpoints: submits design (evidence: `README.md`)
- PCB Endpoints → Job Pipeline: queues job (evidence: `app/routes/pcb.py`)
- PCB Endpoints → Schematic Image Parser: parses upload (evidence: `app/routes/pcb.py`)
- Job Pipeline → Job State & Artifacts: updates (evidence: `app/services/job_manager.py`)
- Job Status & Files → Job State & Artifacts: reads status (evidence: `app/routes/jobs.py`)
- Job Status & Files → Job State & Artifacts: serves artifacts (evidence: `app/routes/jobs.py`)
- FastAPI Application → PCB Endpoints: registers routes (evidence: `app/main.py`)
- FastAPI Application → Job Status & Files: registers routes (evidence: `app/main.py`)
- Job Pipeline → AI Circuit Design: requests design (evidence: `app/services/job_manager.py`)
- Job Pipeline → Board Generator: generates board (evidence: `README.md`)
- Job Pipeline → SPICE Simulation: runs simulation (evidence: `app/services/job_manager.py`)
- Job Pipeline → Thermal Trace DRC: checks traces (evidence: `app/services/job_manager.py`)
- Job Pipeline → KiCad Export & Import: exports layout (evidence: `README.md`)
- Job Pipeline → Auto-Router: routes board (evidence: `README.md`)
- KiCad Export & Import → Auto-Router: exports DSN (evidence: `README.md`)
- Auto-Router → Java FreeRouting: runs routing (evidence: `app/services/freerouting_service.py`)
- Auto-Router → KiCad Export & Import: returns SES (evidence: `README.md`)
- KiCad Export & Import → KiCad CLI: exports fabrication (evidence: `README.md`)
- AI Circuit Design → Gemini API: requests generation (evidence: `app/services/llm.py`)
- FastAPI Application → Trace Calculator: calculates traces (evidence: `app/main.py`)
- FastAPI Application → Hardware Guidance: gets guidance (evidence: `app/main.py`)
- FastAPI Application → Legacy Netlist Audit: calls legacy audit (evidence: `app/main.py`)
- FastAPI Application → Audit Records: reads audit records (evidence: `app/main.py`)
- Circuit Designer → Job Status & Files: polls and downloads (evidence: `README.md`)
- KiCad Export & Import → Job State & Artifacts: stores exports (evidence: `app/services/job_manager.py`)
