# thivakar101/arcsight3d architecture

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

- Interactive diagram: https://gitdiagram.com/thivakar101/arcsight3d
- Repository: https://github.com/thivakar101/arcsight3d

## Overview

#### Purpose and execution surfaces
ArcSight 3D converts uploaded PNG/JPG floor plans into explorable 3D exports. Its active system is a PyQt desktop client, Flask REST backend, PostgreSQL persistence layer, headless Blender generation, and Unity-side runtime visualization. Primary launch points are `desktop/app.py` and `backend/app.py`; Unity integration begins with `unity/Assets/Scripts/SceneBootstrap.cs`.

#### Client-to-API boundary
The desktop application owns user interaction, background work, and HTTP transport rather than processing locally. `desktop/ui/main_window.py` drives upload/process/export actions; `desktop/workers.py` keeps network and generation operations off the UI thread; `desktop/api_client.py` is the backend contract boundary. Backend routes partition operations into project, processing, health, and export APIs: `backend/api/project_routes.py`, `backend/api/processing_routes.py`, and `backend/api/export_routes.py`.

#### Backend application and orchestration
Flask initialization, environment-derived configuration, and shared extensions are centered in `backend/app.py`, `backend/config.py`, and `backend/extensions.py`. Controllers adapt HTTP requests to service calls, while services orchestrate persistence and long-running stages: `backend/controllers/project_controller.py`, `backend/services/processing_service.py`, and `backend/services/export_service.py`. This separates route/controller concerns from CV, OCR, and Blender execution.

#### Project data model and persistence
PostgreSQL is the source of truth for projects, uploaded blueprints, detections, processing state, and exported artifacts. SQLAlchemy entities include `backend/models/project.py`, `backend/models/blueprint.py`, and `backend/models/processing_job.py`; structural entities cover walls, doors, windows, rooms, OCR text, and detected objects. Repository modules isolate database access, notably `backend/database/repositories/project_repository.py` and `backend/database/repositories/object_repository.py`. PostgreSQL is provisioned through `docker-compose.yml` and `docker/postgres/init.sql`.

#### Blueprint analysis pipeline
Processing takes an ingested blueprint through image normalization and geometric extraction, coordinated by `backend/cv/detection_pipeline.py`. Preprocessing prepares the image in `backend/cv/preprocessing.py`; line and contour stages infer architectural geometry in `backend/cv/line_detector.py` and `backend/cv/contour_detector.py`. Resulting coordinates become persisted structural records rather than being passed directly to rendering.

#### OCR enrichment
OCR is an optional parallel enrichment path over the blueprint image. `backend/ocr/ocr_pipeline.py` invokes the Tesseract adapter in `backend/ocr/tesseract_engine.py`, then domain parsers identify dimensions and room labels via `backend/ocr/dimension_parser.py` and `backend/ocr/room_name_parser.py`. Tesseract is an external runtime configured through environment variables.

#### 3D export and consumption
An export request uses `backend/blender/blender_runner.py` to spawn the configured Blender executable headlessly. The Blender-side scene builder, `backend/blender/scripts/generate_scene.py`, reads persisted project geometry, builds wall/door meshes, and emits GLB or FBX artifacts; export coordination resides in `backend/services/export_service.py`. Unity consumers load the exported model through `unity/Assets/Scripts/RuntimeModelLoader.cs` and provide walkthrough controls with `unity/Assets/Scripts/FirstPersonController.cs`; GLB runtime support may require the external GLTFast package.

#### Operational boundaries
The backend depends on OpenCV, Tesseract, PostgreSQL, and a locally accessible Blender executable. Docker support covers the database and backend image via `docker/backend.Dockerfile`; the desktop client and Blender remain host-executed. `legacy/` is retained prototype material and is outside the current architecture.

Main entry points: [`backend/services/processing_service.py`](https://github.com/thivakar101/arcsight3d/blob/main/backend/services/processing_service.py) (Processing service), [`backend/api/project_routes.py`](https://github.com/thivakar101/arcsight3d/blob/main/backend/api/project_routes.py) (REST routes), [`backend/services/export_service.py`](https://github.com/thivakar101/arcsight3d/blob/main/backend/services/export_service.py) (Export service), [`backend/blender/scripts/generate_scene.py`](https://github.com/thivakar101/arcsight3d/blob/main/backend/blender/scripts/generate_scene.py) (Blender scene builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop Client"]
  node_desktop_app["PyQt application<br/>desktop entrypoint<br/>[app.py]"]
  node_desktop_ui["Main window<br/>UI actions<br/>[main_window.py]"]
  node_desktop_workers["Background workers<br/>async UI work<br/>[workers.py]"]
  node_api_client["API client<br/>HTTP contract<br/>[api_client.py]"]
end

subgraph group_backend["Flask Backend"]
  node_flask_app["Flask application<br/>backend entrypoint<br/>[app.py]"]
  node_api_routes["REST routes<br/>project, processing, export APIs<br/>[project_routes.py]"]
  node_processing_service["Processing service<br/>pipeline orchestration"]
  node_export_service["Export service<br/>export orchestration<br/>[export_service.py]"]
  node_project_repository["Project repository<br/>data access"]
  node_object_repository["Object repository<br/>structural data access"]
  node_postgres[("PostgreSQL<br/>system of record<br/>[docker-compose.yml]")]
end

subgraph group_analysis["Analysis &amp; OCR"]
  node_detection_pipeline["Detection pipeline<br/>CV orchestration"]
  node_geometry_extractors["Geometry extraction<br/>preprocessing, lines, contours<br/>[preprocessing.py]"]
  node_ocr_pipeline["OCR pipeline<br/>optional enrichment<br/>[ocr_pipeline.py]"]
  node_tesseract{{"Tesseract<br/>external OCR runtime"}}
end

subgraph group_export["3D Export"]
  node_blender_runner["Blender runner<br/>headless process launcher<br/>[blender_runner.py]"]
  node_scene_builder["Blender scene builder<br/>GLB/FBX generator<br/>[generate_scene.py]"]
end

subgraph group_unity["Unity Runtime"]
  node_unity_bootstrap["Scene bootstrap<br/>Unity integration entrypoint<br/>[SceneBootstrap.cs]"]
  node_runtime_loader["Runtime model loader<br/>Unity model loading"]
  node_walkthrough["Walkthrough controls<br/>first-person controller"]
end

node_desktop_app -->|"starts"| node_desktop_ui
node_desktop_ui -->|"dispatches"| node_desktop_workers
node_desktop_workers -->|"uses"| node_api_client
node_api_client -->|"HTTP requests"| node_api_routes
node_flask_app -->|"registers"| node_api_routes
node_api_routes -->|"processing requests"| node_processing_service
node_api_routes -->|"export requests"| node_export_service
node_processing_service -->|"runs CV"| node_detection_pipeline
node_processing_service -.->|"optional OCR"| node_ocr_pipeline
node_detection_pipeline -->|"coordinates stages"| node_geometry_extractors
node_ocr_pipeline -->|"invokes"| node_tesseract
node_processing_service -->|"updates project/job"| node_project_repository
node_processing_service -->|"persists detections"| node_object_repository
node_project_repository -->|"reads/writes"| node_postgres
node_object_repository -->|"reads/writes"| node_postgres
node_export_service -->|"loads project"| node_project_repository
node_export_service -->|"launches"| node_blender_runner
node_blender_runner -->|"executes headlessly"| node_scene_builder
node_scene_builder -->|"reads geometry"| node_postgres
node_scene_builder -->|"emits GLB/FBX"| node_runtime_loader
node_unity_bootstrap -->|"initializes"| node_runtime_loader
node_unity_bootstrap -->|"enables"| node_walkthrough

click node_desktop_app "https://github.com/thivakar101/arcsight3d/blob/main/desktop/app.py"
click node_desktop_ui "https://github.com/thivakar101/arcsight3d/blob/main/desktop/ui/main_window.py"
click node_desktop_workers "https://github.com/thivakar101/arcsight3d/blob/main/desktop/workers.py"
click node_api_client "https://github.com/thivakar101/arcsight3d/blob/main/desktop/api_client.py"
click node_flask_app "https://github.com/thivakar101/arcsight3d/blob/main/backend/app.py"
click node_api_routes "https://github.com/thivakar101/arcsight3d/blob/main/backend/api/project_routes.py"
click node_processing_service "https://github.com/thivakar101/arcsight3d/blob/main/backend/services/processing_service.py"
click node_export_service "https://github.com/thivakar101/arcsight3d/blob/main/backend/services/export_service.py"
click node_project_repository "https://github.com/thivakar101/arcsight3d/blob/main/backend/database/repositories/project_repository.py"
click node_object_repository "https://github.com/thivakar101/arcsight3d/blob/main/backend/database/repositories/object_repository.py"
click node_postgres "https://github.com/thivakar101/arcsight3d/blob/main/docker-compose.yml"
click node_detection_pipeline "https://github.com/thivakar101/arcsight3d/blob/main/backend/cv/detection_pipeline.py"
click node_geometry_extractors "https://github.com/thivakar101/arcsight3d/blob/main/backend/cv/preprocessing.py"
click node_ocr_pipeline "https://github.com/thivakar101/arcsight3d/blob/main/backend/ocr/ocr_pipeline.py"
click node_blender_runner "https://github.com/thivakar101/arcsight3d/blob/main/backend/blender/blender_runner.py"
click node_scene_builder "https://github.com/thivakar101/arcsight3d/blob/main/backend/blender/scripts/generate_scene.py"
click node_unity_bootstrap "https://github.com/thivakar101/arcsight3d/blob/main/unity/Assets/Scripts/SceneBootstrap.cs"
click node_runtime_loader "https://github.com/thivakar101/arcsight3d/blob/main/unity/Assets/Scripts/RuntimeModelLoader.cs"
click node_walkthrough "https://github.com/thivakar101/arcsight3d/blob/main/unity/Assets/Scripts/FirstPersonController.cs"

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_desktop_app,node_desktop_ui,node_desktop_workers,node_api_client toneBlue
class node_flask_app,node_api_routes,node_processing_service,node_export_service,node_project_repository,node_object_repository,node_postgres toneAmber
class node_detection_pipeline,node_geometry_extractors,node_ocr_pipeline,node_tesseract toneMint
class node_blender_runner,node_scene_builder toneRose
class node_unity_bootstrap,node_runtime_loader,node_walkthrough toneIndigo
```

## Components

### Desktop Client

- [PyQt application](https://github.com/thivakar101/arcsight3d/blob/main/desktop/app.py): desktop entrypoint · `desktop/app.py`
- [Main window](https://github.com/thivakar101/arcsight3d/blob/main/desktop/ui/main_window.py): UI actions · `desktop/ui/main_window.py`
- [Background workers](https://github.com/thivakar101/arcsight3d/blob/main/desktop/workers.py): async UI work · Keeps HTTP and generation work off the UI thread. · `desktop/workers.py`
- [API client](https://github.com/thivakar101/arcsight3d/blob/main/desktop/api_client.py): HTTP contract · `desktop/api_client.py`

### Flask Backend

- [Flask application](https://github.com/thivakar101/arcsight3d/blob/main/backend/app.py): backend entrypoint · Initializes configuration and shared extensions. · `backend/app.py`
- [REST routes](https://github.com/thivakar101/arcsight3d/blob/main/backend/api/project_routes.py): project, processing, export APIs · `backend/api/project_routes.py`
- [Processing service](https://github.com/thivakar101/arcsight3d/blob/main/backend/services/processing_service.py): pipeline orchestration · `backend/services/processing_service.py`
- [Export service](https://github.com/thivakar101/arcsight3d/blob/main/backend/services/export_service.py): export orchestration · `backend/services/export_service.py`
- [Project repository](https://github.com/thivakar101/arcsight3d/blob/main/backend/database/repositories/project_repository.py): data access · `backend/database/repositories/project_repository.py`
- [Object repository](https://github.com/thivakar101/arcsight3d/blob/main/backend/database/repositories/object_repository.py): structural data access · `backend/database/repositories/object_repository.py`
- [PostgreSQL](https://github.com/thivakar101/arcsight3d/blob/main/docker-compose.yml): system of record · Stores projects, blueprints, jobs, detections, and artifacts. · `docker-compose.yml`

### Analysis & OCR

- [Detection pipeline](https://github.com/thivakar101/arcsight3d/blob/main/backend/cv/detection_pipeline.py): CV orchestration · `backend/cv/detection_pipeline.py`
- [Geometry extraction](https://github.com/thivakar101/arcsight3d/blob/main/backend/cv/preprocessing.py): preprocessing, lines, contours · Normalizes blueprints and infers architectural geometry. · `backend/cv/preprocessing.py`
- [OCR pipeline](https://github.com/thivakar101/arcsight3d/blob/main/backend/ocr/ocr_pipeline.py): optional enrichment · Extracts dimensions and room labels. · `backend/ocr/ocr_pipeline.py`
- **Tesseract**: external OCR runtime

### 3D Export

- [Blender runner](https://github.com/thivakar101/arcsight3d/blob/main/backend/blender/blender_runner.py): headless process launcher · `backend/blender/blender_runner.py`
- [Blender scene builder](https://github.com/thivakar101/arcsight3d/blob/main/backend/blender/scripts/generate_scene.py): GLB/FBX generator · Reads persisted geometry and builds wall and door meshes. · `backend/blender/scripts/generate_scene.py`

### Unity Runtime

- [Scene bootstrap](https://github.com/thivakar101/arcsight3d/blob/main/unity/Assets/Scripts/SceneBootstrap.cs): Unity integration entrypoint · `unity/Assets/Scripts/SceneBootstrap.cs`
- [Runtime model loader](https://github.com/thivakar101/arcsight3d/blob/main/unity/Assets/Scripts/RuntimeModelLoader.cs): Unity model loading · `unity/Assets/Scripts/RuntimeModelLoader.cs`
- [Walkthrough controls](https://github.com/thivakar101/arcsight3d/blob/main/unity/Assets/Scripts/FirstPersonController.cs): first-person controller · `unity/Assets/Scripts/FirstPersonController.cs`

## Connections

- PyQt application → Main window: starts
- Main window → Background workers: dispatches
- Background workers → API client: uses
- API client → REST routes: HTTP requests
- Flask application → REST routes: registers
- REST routes → Processing service: processing requests
- REST routes → Export service: export requests
- Processing service → Detection pipeline: runs CV
- Processing service → OCR pipeline: optional OCR
- Detection pipeline → Geometry extraction: coordinates stages
- OCR pipeline → Tesseract: invokes
- Processing service → Project repository: updates project/job
- Processing service → Object repository: persists detections
- Project repository → PostgreSQL: reads/writes
- Object repository → PostgreSQL: reads/writes
- Export service → Project repository: loads project
- Export service → Blender runner: launches
- Blender runner → Blender scene builder: executes headlessly
- Blender scene builder → PostgreSQL: reads geometry
- Blender scene builder → Runtime model loader: emits GLB/FBX
- Scene bootstrap → Runtime model loader: initializes
- Scene bootstrap → Walkthrough controls: enables