# luo-yangsiqi/cad- architecture

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

- Interactive diagram: https://gitdiagram.com/luo-yangsiqi/cad-
- Repository: https://github.com/luo-yangsiqi/cad-

## Overview

This is a CAD knowledge-base application: users upload drawings, inspect revisions and evidence, and ask natural-language questions answered through semantic retrieval plus PostgreSQL verification. The graph preserves the documented DWG/OCR/Vision ingestion stages and the separate chat, exact-query, and hybrid-search capabilities. Several subsystem links are based on README descriptions because their implementations were not sampled; uncertain call wiring is omitted.

Main entry points: [`app/ingestion/pipeline.py`](https://github.com/luo-yangsiqi/cad-/blob/main/app/ingestion/pipeline.py) (Upload orchestrator), [`app/retrieval/hybrid_retrieval_service.py`](https://github.com/luo-yangsiqi/cad-/blob/main/app/retrieval/hybrid_retrieval_service.py) (Hybrid retrieval), [`frontend/src/app/App.tsx`](https://github.com/luo-yangsiqi/cad-/blob/main/frontend/src/app/App.tsx) (Workspace pages), [`app/api/main.py`](https://github.com/luo-yangsiqi/cad-/blob/main/app/api/main.py) (FastAPI routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Workspace experience"]
  node_workspace["Workspace pages<br/>[App.tsx]"]
  node_drawing_views["Drawing views"]
  node_upload_view["Upload status<br/>[UploadJobPage.tsx]"]
  node_frontend_api["API client<br/>[api.ts]"]
  node_http_api["FastAPI routes<br/>[main.py]"]
  node_chat_routes["Chat endpoint<br/>[chat.py]"]
end

subgraph group_ingestion["Drawing ingestion"]
  node_pipeline["Upload orchestrator<br/>[pipeline.py]"]
  node_dwg_extract["DWG extraction<br/>[extract_cad.py]"]
  node_ocr_stage["OCR processing"]
  node_alignment["CAD OCR alignment<br/>[align_cad_ocr.py]"]
  node_vision_stage["Vision observations<br/>[run_vision.py]"]
  node_unified_features["Feature fusion"]
  node_pg_import["Fact import<br/>[import_all.py]"]
  node_uploads[("Upload artifacts")]
end

subgraph group_query["Query and retrieval"]
  node_chat_service["Chat orchestration<br/>[chat_service.py]"]
  node_tools["Whitelisted tools<br/>[cad_query_tools.py]"]
  node_query_service["Query facade"]
  node_hybrid["Hybrid retrieval"]
  node_planner["Constraint planner<br/>[query_planner.py]"]
end

subgraph group_data["Persistence and indexing"]
  node_semantic["Semantic search<br/>[service.py]"]
  node_repository["Drawing repository"]
  node_ingestion_repo["Job repository"]
  node_postgres[("PostgreSQL<br/>[connection.py]")]
  node_qdrant[("Qdrant vectors")]
end

subgraph group_models["Model integrations"]
  node_text_model["DeepSeek text API"]
  node_vision_client["Vision client"]
  node_vision_model["DeepSeek Vision API"]
end

node_engineer(("CAD user"))

node_engineer -->|"uses"| node_workspace
node_workspace -->|"routes to"| node_drawing_views
node_workspace -->|"routes to"| node_upload_view
node_drawing_views -->|"requests data"| node_frontend_api
node_upload_view -->|"submits and polls"| node_frontend_api
node_frontend_api -->|"HTTP requests"| node_http_api
node_http_api -->|"starts upload"| node_pipeline
node_pipeline -->|"saves artifacts"| node_uploads
node_pipeline -->|"creates and updates jobs"| node_ingestion_repo
node_pipeline -->|"runs extraction"| node_dwg_extract
node_pipeline -->|"runs OCR"| node_ocr_stage
node_pipeline -->|"runs alignment"| node_alignment
node_pipeline -.->|"optionally runs"| node_vision_stage
node_pipeline -->|"builds features"| node_unified_features
node_pipeline -->|"imports facts"| node_pg_import
node_pipeline -->|"indexes chunks"| node_semantic
node_dwg_extract -->|"writes structured output"| node_uploads
node_vision_stage -->|"requests analysis"| node_vision_client
node_vision_client -->|"sends image"| node_vision_model
node_http_api -->|"mounts routes"| node_chat_routes
node_chat_routes -->|"dispatches chat"| node_chat_service
node_chat_service -->|"requests response"| node_text_model
node_chat_service -->|"executes selected tools"| node_tools
node_tools -->|"delegates validated queries"| node_query_service
node_query_service -->|"reads exact facts"| node_repository
node_query_service -->|"dispatches hybrid search"| node_hybrid
node_hybrid -->|"builds constraints"| node_planner
node_hybrid -->|"recalls candidates"| node_semantic
node_hybrid -->|"verifies and audits"| node_repository
node_semantic -->|"queries vectors"| node_qdrant
node_repository -->|"reads and writes"| node_postgres
node_ingestion_repo -->|"persists job metadata"| node_postgres
node_pg_import -->|"imports drawing facts"| node_postgres

click node_workspace "https://github.com/luo-yangsiqi/cad-/blob/main/frontend/src/app/App.tsx"
click node_drawing_views "https://github.com/luo-yangsiqi/cad-/blob/main/frontend/src/pages/DrawingWorkspacePage.tsx"
click node_upload_view "https://github.com/luo-yangsiqi/cad-/blob/main/frontend/src/pages/UploadJobPage.tsx"
click node_frontend_api "https://github.com/luo-yangsiqi/cad-/blob/main/frontend/src/services/api.ts"
click node_http_api "https://github.com/luo-yangsiqi/cad-/blob/main/app/api/main.py"
click node_chat_routes "https://github.com/luo-yangsiqi/cad-/blob/main/app/api/chat.py"
click node_pipeline "https://github.com/luo-yangsiqi/cad-/blob/main/app/ingestion/pipeline.py"
click node_dwg_extract "https://github.com/luo-yangsiqi/cad-/blob/main/scripts/extract_cad.py"
click node_ocr_stage "https://github.com/luo-yangsiqi/cad-/blob/main/scripts/process_cad_ocr_batch.py"
click node_alignment "https://github.com/luo-yangsiqi/cad-/blob/main/scripts/align_cad_ocr.py"
click node_vision_stage "https://github.com/luo-yangsiqi/cad-/blob/main/scripts/run_vision.py"
click node_unified_features "https://github.com/luo-yangsiqi/cad-/blob/main/scripts/build_unified_features.py"
click node_pg_import "https://github.com/luo-yangsiqi/cad-/blob/main/scripts/db/import_all.py"
click node_chat_service "https://github.com/luo-yangsiqi/cad-/blob/main/app/services/chat_service.py"
click node_tools "https://github.com/luo-yangsiqi/cad-/blob/main/app/tools/cad_query_tools.py"
click node_query_service "https://github.com/luo-yangsiqi/cad-/blob/main/app/services/cad_query_service.py"
click node_hybrid "https://github.com/luo-yangsiqi/cad-/blob/main/app/retrieval/hybrid_retrieval_service.py"
click node_planner "https://github.com/luo-yangsiqi/cad-/blob/main/app/retrieval/query_planner.py"
click node_semantic "https://github.com/luo-yangsiqi/cad-/blob/main/app/semantic/service.py"
click node_repository "https://github.com/luo-yangsiqi/cad-/blob/main/app/repositories/drawing_repository.py"
click node_ingestion_repo "https://github.com/luo-yangsiqi/cad-/blob/main/app/repositories/ingestion_repository.py"
click node_postgres "https://github.com/luo-yangsiqi/cad-/blob/main/app/db/connection.py"
click node_vision_client "https://github.com/luo-yangsiqi/cad-/blob/main/app/llm/deepseek_vision_client.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_workspace,node_drawing_views,node_upload_view,node_frontend_api,node_http_api,node_chat_routes,node_engineer toneBlue
class node_pipeline,node_dwg_extract,node_ocr_stage,node_alignment,node_vision_stage,node_unified_features,node_pg_import,node_uploads toneAmber
class node_chat_service,node_tools,node_query_service,node_hybrid,node_planner toneMint
class node_semantic,node_repository,node_ingestion_repo,node_postgres,node_qdrant toneRose
class node_text_model,node_vision_client,node_vision_model toneIndigo
```

## Components

### Workspace experience

- [Workspace pages](https://github.com/luo-yangsiqi/cad-/blob/main/frontend/src/app/App.tsx): `frontend/src/app/App.tsx`
- [Drawing views](https://github.com/luo-yangsiqi/cad-/blob/main/frontend/src/pages/DrawingWorkspacePage.tsx): `frontend/src/pages/DrawingWorkspacePage.tsx`
- [Upload status](https://github.com/luo-yangsiqi/cad-/blob/main/frontend/src/pages/UploadJobPage.tsx): `frontend/src/pages/UploadJobPage.tsx`
- [API client](https://github.com/luo-yangsiqi/cad-/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [FastAPI routes](https://github.com/luo-yangsiqi/cad-/blob/main/app/api/main.py): `app/api/main.py`
- [Chat endpoint](https://github.com/luo-yangsiqi/cad-/blob/main/app/api/chat.py): `app/api/chat.py`

### Drawing ingestion

- [Upload orchestrator](https://github.com/luo-yangsiqi/cad-/blob/main/app/ingestion/pipeline.py): `app/ingestion/pipeline.py`
- [DWG extraction](https://github.com/luo-yangsiqi/cad-/blob/main/scripts/extract_cad.py): `scripts/extract_cad.py`
- [OCR processing](https://github.com/luo-yangsiqi/cad-/blob/main/scripts/process_cad_ocr_batch.py): `scripts/process_cad_ocr_batch.py`
- [CAD OCR alignment](https://github.com/luo-yangsiqi/cad-/blob/main/scripts/align_cad_ocr.py): `scripts/align_cad_ocr.py`
- [Vision observations](https://github.com/luo-yangsiqi/cad-/blob/main/scripts/run_vision.py): `scripts/run_vision.py`
- [Feature fusion](https://github.com/luo-yangsiqi/cad-/blob/main/scripts/build_unified_features.py): `scripts/build_unified_features.py`
- [Fact import](https://github.com/luo-yangsiqi/cad-/blob/main/scripts/db/import_all.py): `scripts/db/import_all.py`
- **Upload artifacts**

### Query and retrieval

- [Chat orchestration](https://github.com/luo-yangsiqi/cad-/blob/main/app/services/chat_service.py): `app/services/chat_service.py`
- [Whitelisted tools](https://github.com/luo-yangsiqi/cad-/blob/main/app/tools/cad_query_tools.py): `app/tools/cad_query_tools.py`
- [Query facade](https://github.com/luo-yangsiqi/cad-/blob/main/app/services/cad_query_service.py): `app/services/cad_query_service.py`
- [Hybrid retrieval](https://github.com/luo-yangsiqi/cad-/blob/main/app/retrieval/hybrid_retrieval_service.py): `app/retrieval/hybrid_retrieval_service.py`
- [Constraint planner](https://github.com/luo-yangsiqi/cad-/blob/main/app/retrieval/query_planner.py): `app/retrieval/query_planner.py`

### Persistence and indexing

- [Semantic search](https://github.com/luo-yangsiqi/cad-/blob/main/app/semantic/service.py): `app/semantic/service.py`
- [Drawing repository](https://github.com/luo-yangsiqi/cad-/blob/main/app/repositories/drawing_repository.py): `app/repositories/drawing_repository.py`
- [Job repository](https://github.com/luo-yangsiqi/cad-/blob/main/app/repositories/ingestion_repository.py): `app/repositories/ingestion_repository.py`
- [PostgreSQL](https://github.com/luo-yangsiqi/cad-/blob/main/app/db/connection.py): `app/db/connection.py`
- **Qdrant vectors**

### Model integrations

- **DeepSeek text API**
- [Vision client](https://github.com/luo-yangsiqi/cad-/blob/main/app/llm/deepseek_vision_client.py): `app/llm/deepseek_vision_client.py`
- **DeepSeek Vision API**

### Other components

- **CAD user**

## Connections

- CAD user → Workspace pages: uses
- Workspace pages → Drawing views: routes to
- Workspace pages → Upload status: routes to
- Drawing views → API client: requests data
- Upload status → API client: submits and polls
- API client → FastAPI routes: HTTP requests
- FastAPI routes → Upload orchestrator: starts upload
- Upload orchestrator → Upload artifacts: saves artifacts
- Upload orchestrator → Job repository: creates and updates jobs
- Upload orchestrator → DWG extraction: runs extraction
- Upload orchestrator → OCR processing: runs OCR
- Upload orchestrator → CAD OCR alignment: runs alignment
- Upload orchestrator → Vision observations: optionally runs
- Upload orchestrator → Feature fusion: builds features
- Upload orchestrator → Fact import: imports facts
- Upload orchestrator → Semantic search: indexes chunks
- DWG extraction → Upload artifacts: writes structured output
- Vision observations → Vision client: requests analysis
- Vision client → DeepSeek Vision API: sends image
- FastAPI routes → Chat endpoint: mounts routes
- Chat endpoint → Chat orchestration: dispatches chat
- Chat orchestration → DeepSeek text API: requests response
- Chat orchestration → Whitelisted tools: executes selected tools
- Whitelisted tools → Query facade: delegates validated queries
- Query facade → Drawing repository: reads exact facts
- Query facade → Hybrid retrieval: dispatches hybrid search
- Hybrid retrieval → Constraint planner: builds constraints
- Hybrid retrieval → Semantic search: recalls candidates
- Hybrid retrieval → Drawing repository: verifies and audits
- Semantic search → Qdrant vectors: queries vectors
- Drawing repository → PostgreSQL: reads and writes
- Job repository → PostgreSQL: persists job metadata
- Fact import → PostgreSQL: imports drawing facts