# a-shojaei/constructai-oss architecture

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

- Interactive diagram: https://gitdiagram.com/a-shojaei/constructai-oss
- Repository: https://github.com/a-shojaei/constructai-oss

## Overview

ConstructAI is a full-lifecycle construction management platform: operators use a dashboard to manage projects and work, while domain services provide estimating, scheduling, safety, quality, and financial controls. Its API also supports document ingestion, AI-assisted answers, and multi-agent workflows; edge devices process camera feeds and publish detection events. The README documents the main product layers and capabilities. Several backend subsystems are represented from the file tree and README rather than inspected source, so those links are documented at a high level rather than traced through individual routes.

Main entry points: [`apps/api/app/api/v1/projects.py`](https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/api/v1/projects.py) (REST and WebSocket API), [`apps/api/app/services/ingestion/pipeline.py`](https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/services/ingestion/pipeline.py) (Document ingestion), [`apps/api/app/services/rag/retrieval.py`](https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/services/rag/retrieval.py) (Retrieval and generation), [`apps/api/app/main.py`](https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/main.py) (API runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Operator client"]
  node_dashboard["Web dashboard<br/>[page.tsx]"]
end

subgraph group_api["API and tenancy"]
  node_api_routes["REST and WebSocket API<br/>[projects.py]"]
  node_api_runtime["API runtime<br/>[main.py]"]
  node_tenant["Tenant context<br/>[tenant_context.py]"]
  node_database[("PostgreSQL data<br/>[database.py]")]
end

subgraph group_domain["Construction operations"]
  node_documents["Document management"]
  node_ingestion["Document ingestion<br/>[pipeline.py]"]
  node_project_ops["Project operations<br/>[project.py]"]
  node_estimating["Estimating and bids"]
  node_scheduling["Schedule analysis<br/>[cpm_engine.py]"]
  node_controls["Cost and cash controls<br/>[evm_engine.py]"]
  node_field_safety["Field safety and quality<br/>[predictive_risk.py]"]
end

subgraph group_ai["AI and intelligence"]
  node_orchestration["Agent orchestration"]
  node_guardrails["AI output validation<br/>[pipeline.py]"]
  node_rag["Retrieval and generation<br/>[retrieval.py]"]
  node_llm["LLM gateway<br/>[llm_gateway.py]"]
  node_cross_project["Cross-project analytics"]
end

subgraph group_edge["Edge vision"]
  node_edge_pipeline["Edge camera pipeline<br/>[edge_pipeline.py]"]
  node_mqtt["MQTT publisher<br/>[mqtt_client.py]"]
  node_offline_buffer[("Offline event buffer<br/>[offline_buffer.py]")]
end

node_operator(("Construction operator"))
node_mqtt_broker(("MQTT broker"))

node_operator -->|"uses"| node_dashboard
node_dashboard -->|"requests data"| node_api_routes
node_api_runtime -->|"serves routes"| node_api_routes
node_api_runtime -.->|"enforces tenancy"| node_tenant
node_api_routes -.->|"routes operations"| node_project_ops
node_project_ops -.->|"persists project data"| node_database
node_api_routes -.->|"routes document work"| node_documents
node_documents -.->|"processes uploads"| node_ingestion
node_ingestion -->|"stores chunks"| node_database
node_ingestion -->|"generates embeddings"| node_rag
node_api_routes -.->|"supports bid decisions"| node_estimating
node_api_routes -.->|"supports schedules"| node_scheduling
node_api_routes -.->|"supports cost controls"| node_controls
node_api_routes -.->|"supports field safety"| node_field_safety
node_api_routes -.->|"invokes AI workflows"| node_orchestration
node_orchestration -.->|"validates output"| node_guardrails
node_guardrails -.->|"uses confidence scoring"| node_llm
node_api_routes -.->|"answers questions"| node_rag
node_cross_project -->|"embeds RFI subjects"| node_rag
node_cross_project -->|"uses model gateway"| node_llm
node_edge_pipeline -->|"publishes detections"| node_mqtt
node_edge_pipeline -->|"buffers offline events"| node_offline_buffer
node_mqtt -->|"publishes events"| node_mqtt_broker

click node_dashboard "https://github.com/a-shojaei/constructai-oss/blob/main/apps/web/src/app/(dashboard)/projects/page.tsx"
click node_api_routes "https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/api/v1/projects.py"
click node_api_runtime "https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/main.py"
click node_tenant "https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/middleware/tenant_context.py"
click node_database "https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/database.py"
click node_documents "https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/services/document_service.py"
click node_ingestion "https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/services/ingestion/pipeline.py"
click node_project_ops "https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/services/project.py"
click node_estimating "https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/services/estimating/bid_decision_engine.py"
click node_scheduling "https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/services/scheduling/cpm_engine.py"
click node_controls "https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/services/controls/evm_engine.py"
click node_field_safety "https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/services/safety/predictive_risk.py"
click node_orchestration "https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/services/orchestration/orchestrator_agent.py"
click node_guardrails "https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/services/guardrails/pipeline.py"
click node_rag "https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/services/rag/retrieval.py"
click node_llm "https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/services/reliability/llm_gateway.py"
click node_cross_project "https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/services/memory/cross_project_analytics.py"
click node_edge_pipeline "https://github.com/a-shojaei/constructai-oss/blob/main/edge/src/edge_pipeline.py"
click node_mqtt "https://github.com/a-shojaei/constructai-oss/blob/main/edge/src/mqtt_client.py"
click node_offline_buffer "https://github.com/a-shojaei/constructai-oss/blob/main/edge/src/offline_buffer.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 toneBlue
class node_api_routes,node_api_runtime,node_tenant,node_database toneAmber
class node_documents,node_ingestion,node_project_ops,node_estimating,node_scheduling,node_controls,node_field_safety toneMint
class node_orchestration,node_guardrails,node_rag,node_llm,node_cross_project toneRose
class node_edge_pipeline,node_mqtt,node_offline_buffer,node_operator,node_mqtt_broker toneIndigo
```

## Components

### Operator client

- [Web dashboard](https://github.com/a-shojaei/constructai-oss/blob/main/apps/web/src/app/(dashboard)/projects/page.tsx): `apps/web/src/app/(dashboard)/projects/page.tsx`

### API and tenancy

- [REST and WebSocket API](https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/api/v1/projects.py): `apps/api/app/api/v1/projects.py`
- [API runtime](https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/main.py): `apps/api/app/main.py`
- [Tenant context](https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/middleware/tenant_context.py): `apps/api/app/middleware/tenant_context.py`
- [PostgreSQL data](https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/database.py): `apps/api/app/database.py`

### Construction operations

- [Document management](https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/services/document_service.py): `apps/api/app/services/document_service.py`
- [Document ingestion](https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/services/ingestion/pipeline.py): `apps/api/app/services/ingestion/pipeline.py`
- [Project operations](https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/services/project.py): `apps/api/app/services/project.py`
- [Estimating and bids](https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/services/estimating/bid_decision_engine.py): `apps/api/app/services/estimating/bid_decision_engine.py`
- [Schedule analysis](https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/services/scheduling/cpm_engine.py): `apps/api/app/services/scheduling/cpm_engine.py`
- [Cost and cash controls](https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/services/controls/evm_engine.py): `apps/api/app/services/controls/evm_engine.py`
- [Field safety and quality](https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/services/safety/predictive_risk.py): `apps/api/app/services/safety/predictive_risk.py`

### AI and intelligence

- [Agent orchestration](https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/services/orchestration/orchestrator_agent.py): `apps/api/app/services/orchestration/orchestrator_agent.py`
- [AI output validation](https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/services/guardrails/pipeline.py): `apps/api/app/services/guardrails/pipeline.py`
- [Retrieval and generation](https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/services/rag/retrieval.py): `apps/api/app/services/rag/retrieval.py`
- [LLM gateway](https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/services/reliability/llm_gateway.py): `apps/api/app/services/reliability/llm_gateway.py`
- [Cross-project analytics](https://github.com/a-shojaei/constructai-oss/blob/main/apps/api/app/services/memory/cross_project_analytics.py): `apps/api/app/services/memory/cross_project_analytics.py`

### Edge vision

- [Edge camera pipeline](https://github.com/a-shojaei/constructai-oss/blob/main/edge/src/edge_pipeline.py): `edge/src/edge_pipeline.py`
- [MQTT publisher](https://github.com/a-shojaei/constructai-oss/blob/main/edge/src/mqtt_client.py): `edge/src/mqtt_client.py`
- [Offline event buffer](https://github.com/a-shojaei/constructai-oss/blob/main/edge/src/offline_buffer.py): `edge/src/offline_buffer.py`

### Other components

- **Construction operator**
- **MQTT broker**

## Connections

- Construction operator → Web dashboard: uses (evidence: `README.md`)
- Web dashboard → REST and WebSocket API: requests data (evidence: `README.md`)
- API runtime → REST and WebSocket API: serves routes (evidence: `README.md`)
- API runtime → Tenant context: enforces tenancy
- REST and WebSocket API → Project operations: routes operations
- Project operations → PostgreSQL data: persists project data
- REST and WebSocket API → Document management: routes document work
- Document management → Document ingestion: processes uploads
- Document ingestion → PostgreSQL data: stores chunks (evidence: `apps/api/app/services/ingestion/pipeline.py`)
- Document ingestion → Retrieval and generation: generates embeddings
- REST and WebSocket API → Estimating and bids: supports bid decisions
- REST and WebSocket API → Schedule analysis: supports schedules
- REST and WebSocket API → Cost and cash controls: supports cost controls
- REST and WebSocket API → Field safety and quality: supports field safety
- REST and WebSocket API → Agent orchestration: invokes AI workflows
- Agent orchestration → AI output validation: validates output
- AI output validation → LLM gateway: uses confidence scoring
- REST and WebSocket API → Retrieval and generation: answers questions
- Cross-project analytics → Retrieval and generation: embeds RFI subjects
- Cross-project analytics → LLM gateway: uses model gateway (evidence: `apps/api/app/services/memory/cross_project_analytics.py`)
- Edge camera pipeline → MQTT publisher: publishes detections (evidence: `edge/src/edge_pipeline.py`)
- Edge camera pipeline → Offline event buffer: buffers offline events (evidence: `edge/src/edge_pipeline.py`)
- MQTT publisher → MQTT broker: publishes events (evidence: `edge/src/mqtt_client.py`)