# konkovdv/aerobim architecture

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

- Interactive diagram: https://gitdiagram.com/konkovdv/aerobim
- Repository: https://github.com/konkovdv/aerobim

## Overview

#### Purpose and entry points
AeroBIM is an openBIM acceptance-criteria assistant for IFC, IDS, drawings, requirements, and calculation evidence. It produces a deterministic ISO-19650 Shared-gate report with provenance, capability status, exports, and optional advisory AI; it is explicitly not a customer-ready CDE/MEP/calculation-correctness product.

Backend starts at `backend/src/aerobim/main.py`; FastAPI routing is assembled in `backend/src/aerobim/presentation/http/api.py`. The browser review shell starts at `frontend/src/main.tsx` and `frontend/src/App.tsx`.

#### Layered backend and composition
The Python backend follows inward Clean Architecture: domain models/ports, application use cases, infrastructure adapters, then HTTP presentation. Constructor DI binds ports to enabled adapters and environment-selected implementations.
- `backend/src/aerobim/domain/ports.py`
- `backend/src/aerobim/core/di/container.py`
- `backend/src/aerobim/infrastructure/di/bootstrap.py`

Configuration determines fail-closed profiles, authorization, optional engines, storage, and AI routing through `backend/src/aerobim/core/config/settings.py`.

#### Package ingestion and analysis orchestration
The central flow accepts uploaded/stored package inputs or direct analysis requests, constructs a package trace, applies completeness/intake gates, and runs the project-package orchestration. Larger requests can use the same-process job submission/polling path.
- `backend/src/aerobim/presentation/http/routes/uploads.py`
- `backend/src/aerobim/application/use_cases/analyze_project_package.py`
- `backend/src/aerobim/application/use_cases/analyze_project_package_jobs.py`

Outputs aggregate findings, evidence references, run manifest, capabilities, and a `PackageOutcome`; failed required capabilities prevent a passing Shared-gate result.

#### Deterministic validation engines
The deterministic core fuses IFC property/quantity checks, IDS validation, requirements extraction/interpretation, cross-document contradiction detection, drawing annotations, and optional clash/MEP checks.
- `backend/src/aerobim/application/services/analyze_orchestrators.py`
- `backend/src/aerobim/infrastructure/adapters/ifc_open_shell_validator.py`
- `backend/src/aerobim/infrastructure/adapters/ifc_tester_ids_validator.py`

Requirements can be compiled to IDS via `backend/src/aerobim/application/use_cases/compile_requirements_to_ids.py`; adapters isolate IfcOpenShell, IfcTester, Docling, CAD/PDF, and optional geometry dependencies from domain policy.

#### Evidence, verdict, and human review boundary
Domain objects encode findings, provenance, capability contracts, review state, signatures, and reproducibility. Verdict ownership is deterministic; advisory and HITL events do not independently turn a report into a pass.
- `backend/src/aerobim/domain/findings.py`
- `backend/src/aerobim/domain/finding_provenance.py`
- `backend/src/aerobim/application/use_cases/apply_norm_rule_hitl_event.py`

Reports support list/detail, review-event, KPI, and source/preview retrieval routes in `backend/src/aerobim/presentation/http/routes/reports.py`.

#### AI and drawing advisory boundary
Hybrid routing classifies data and applies privacy/trust policy before optional LLM/VLM advisory calls. It is verdict-neutral (`summary.passed` must be invariant with AI off/on), budgeted, audited, and guarded against unsafe egress.
- `backend/src/aerobim/application/services/hybrid_route_gate.py`
- `backend/src/aerobim/domain/hybrid/model_router.py`
- `backend/src/aerobim/infrastructure/adapters/openai_compat_llm_provider.py`

Drawing analysis uses structured/raster/region-restricted pipelines and evidence grounding, but human-level CV remains an explicitly missing capability.

#### Persistence, exports, and integrations
Report payloads and binary artifacts sit behind ports: local filesystem/object storage by default, optional S3/MinIO artifacts and Postgres summary indexing. BCF 2.1/3.0 ZIP is exported structurally; API push is experimental and independent CDE import is not verified.
- `backend/src/aerobim/infrastructure/adapters/local_object_store.py`
- `backend/src/aerobim/infrastructure/adapters/s3_object_store.py`
- `backend/src/aerobim/infrastructure/adapters/bcf3_exporter.py`

Relevant HTTP export endpoints are in `backend/src/aerobim/presentation/http/routes/exports.py`; BCF API push is represented by `backend/src/aerobim/application/use_cases/push_report_to_bcf_api.py`.

#### Runtime and client surfaces
Material runtime: Python 3.12+, FastAPI/Uvicorn in Docker; compose definitions are `docker-compose.yml` and `docker-compose.production.yml`. Optional infrastructure includes Redis job storage, Postgres, and S3-compatible storage. The TypeScript/Vite frontend renders IFC via web-ifc/Three.js and presents findings, provenance, capability honesty, and drawing evidence.
- `frontend/src/lib/api.ts`
- `frontend/src/lib/ifc-scene.ts`
- `frontend/src/components/ProvenancePanel.tsx`

Main entry points: [`backend/src/aerobim/application/services/analyze_orchestrators.py`](https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/application/services/analyze_orchestrators.py) (Deterministic orchestrators), [`backend/src/aerobim/presentation/http/api.py`](https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/presentation/http/api.py) (FastAPI API assembly), [`backend/src/aerobim/application/use_cases/analyze_project_package.py`](https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/application/use_cases/analyze_project_package.py) (Package analysis), [`backend/src/aerobim/core/di/container.py`](https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/core/di/container.py) (DI container)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Python backend"]
  node_api["FastAPI API assembly<br/>HTTP presentation<br/>[api.py]"]
  node_uploads["Package upload routes<br/>HTTP routes<br/>[uploads.py]"]
  node_reports["Report review routes<br/>HTTP routes<br/>[reports.py]"]
  node_exports["Export routes<br/>HTTP routes<br/>[exports.py]"]
  node_package_analysis{{"Package analysis<br/>use case"}}
  node_job_analysis["Analysis jobs<br/>use case"]
  node_orchestrators{{"Deterministic orchestrators<br/>application service"}}
  node_requirements_ids["Requirements to IDS<br/>use case"]
  node_domain["Findings &amp; provenance<br/>domain policy<br/>[findings.py]"]
  node_hitl["HITL review events<br/>use case"]
  node_settings["Runtime settings<br/>configuration<br/>[settings.py]"]
  node_di["DI container<br/>composition root<br/>[container.py]"]
  node_ifc_validator["IFC validation<br/>IfcOpenShell adapter"]
  node_ids_validator["IDS validation<br/>IfcTester adapter"]
end

subgraph group_advisory["Optional advisory"]
  node_hybrid_gate["Hybrid route gate<br/>AI policy service"]
  node_llm["LLM/VLM provider<br/>OpenAI-compatible adapter"]
end

subgraph group_storage["Persistence &amp; integrations"]
  node_object_store[("Artifact storage<br/>object-store adapter")]
  node_bcf_export["BCF ZIP export<br/>export adapter<br/>[bcf3_exporter.py]"]
end

subgraph group_frontend["Browser client"]
  node_web_app["Review application<br/>Vite React client<br/>[App.tsx]"]
  node_ifc_scene["IFC scene viewer<br/>web-ifc / Three.js<br/>[ifc-scene.ts]"]
end

node_api -->|"mounts"| node_uploads
node_api -->|"mounts"| node_reports
node_api -->|"mounts"| node_exports
node_uploads -->|"starts analysis"| node_package_analysis
node_uploads -->|"submits large jobs"| node_job_analysis
node_job_analysis -->|"runs"| node_package_analysis
node_package_analysis -->|"orchestrates"| node_orchestrators
node_package_analysis -->|"reads and writes artifacts"| node_object_store
node_orchestrators -->|"validates IFC"| node_ifc_validator
node_orchestrators -->|"validates IDS"| node_ids_validator
node_requirements_ids -->|"produces IDS for validation"| node_ids_validator
node_orchestrators -->|"creates deterministic findings"| node_domain
node_orchestrators -.->|"requests advisory"| node_hybrid_gate
node_hybrid_gate -.->|"allowed advisory calls"| node_llm
node_reports -->|"retrieves outcomes"| node_domain
node_reports -->|"applies review events"| node_hitl
node_exports -->|"exports reports"| node_bcf_export
node_di -->|"uses selections"| node_settings
node_di -.->|"binds port"| node_ifc_validator
node_di -.->|"binds port"| node_object_store
node_web_app -->|"calls HTTP API"| node_api
node_web_app -->|"renders IFC"| node_ifc_scene

click node_api "https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/presentation/http/api.py"
click node_uploads "https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/presentation/http/routes/uploads.py"
click node_reports "https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/presentation/http/routes/reports.py"
click node_exports "https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/presentation/http/routes/exports.py"
click node_package_analysis "https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/application/use_cases/analyze_project_package.py"
click node_job_analysis "https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/application/use_cases/analyze_project_package_jobs.py"
click node_orchestrators "https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/application/services/analyze_orchestrators.py"
click node_requirements_ids "https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/application/use_cases/compile_requirements_to_ids.py"
click node_domain "https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/domain/findings.py"
click node_hitl "https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/application/use_cases/apply_norm_rule_hitl_event.py"
click node_settings "https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/core/config/settings.py"
click node_di "https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/core/di/container.py"
click node_ifc_validator "https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/infrastructure/adapters/ifc_open_shell_validator.py"
click node_ids_validator "https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/infrastructure/adapters/ifc_tester_ids_validator.py"
click node_hybrid_gate "https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/application/services/hybrid_route_gate.py"
click node_llm "https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/infrastructure/adapters/openai_compat_llm_provider.py"
click node_object_store "https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/infrastructure/adapters/local_object_store.py"
click node_bcf_export "https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/infrastructure/adapters/bcf3_exporter.py"
click node_web_app "https://github.com/konkovdv/aerobim/blob/main/frontend/src/App.tsx"
click node_ifc_scene "https://github.com/konkovdv/aerobim/blob/main/frontend/src/lib/ifc-scene.ts"

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_api,node_uploads,node_reports,node_exports,node_package_analysis,node_job_analysis,node_orchestrators,node_requirements_ids,node_domain,node_hitl,node_settings,node_di,node_ifc_validator,node_ids_validator toneBlue
class node_hybrid_gate,node_llm toneAmber
class node_object_store,node_bcf_export toneMint
class node_web_app,node_ifc_scene toneRose
```

## Components

### Python backend

Clean Architecture validation service.

- [FastAPI API assembly](https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/presentation/http/api.py): HTTP presentation · `backend/src/aerobim/presentation/http/api.py`
- [Package upload routes](https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/presentation/http/routes/uploads.py): HTTP routes · `backend/src/aerobim/presentation/http/routes/uploads.py`
- [Report review routes](https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/presentation/http/routes/reports.py): HTTP routes · Serves reports, review events, KPIs, sources, and previews. · `backend/src/aerobim/presentation/http/routes/reports.py`
- [Export routes](https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/presentation/http/routes/exports.py): HTTP routes · `backend/src/aerobim/presentation/http/routes/exports.py`
- [Package analysis](https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/application/use_cases/analyze_project_package.py): use case · Builds package trace, gates intake, and returns PackageOutcome. · `backend/src/aerobim/application/use_cases/analyze_project_package.py`
- [Analysis jobs](https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/application/use_cases/analyze_project_package_jobs.py): use case · Same-process submission and polling for larger requests. · `backend/src/aerobim/application/use_cases/analyze_project_package_jobs.py`
- [Deterministic orchestrators](https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/application/services/analyze_orchestrators.py): application service · Aggregates validation findings, evidence, manifest, and capabilities. · `backend/src/aerobim/application/services/analyze_orchestrators.py`
- [Requirements to IDS](https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/application/use_cases/compile_requirements_to_ids.py): use case · `backend/src/aerobim/application/use_cases/compile_requirements_to_ids.py`
- [Findings & provenance](https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/domain/findings.py): domain policy · Owns deterministic verdict, review state, signatures, and reproducibility. · `backend/src/aerobim/domain/findings.py`
- [HITL review events](https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/application/use_cases/apply_norm_rule_hitl_event.py): use case · Human events cannot independently create a passing verdict. · `backend/src/aerobim/application/use_cases/apply_norm_rule_hitl_event.py`
- [Runtime settings](https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/core/config/settings.py): configuration · Selects fail-closed profiles, adapters, storage, and AI policy. · `backend/src/aerobim/core/config/settings.py`
- [DI container](https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/core/di/container.py): composition root · Binds ports to enabled implementations. · `backend/src/aerobim/core/di/container.py`
- [IFC validation](https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/infrastructure/adapters/ifc_open_shell_validator.py): IfcOpenShell adapter · Checks IFC properties and quantities. · `backend/src/aerobim/infrastructure/adapters/ifc_open_shell_validator.py`
- [IDS validation](https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/infrastructure/adapters/ifc_tester_ids_validator.py): IfcTester adapter · `backend/src/aerobim/infrastructure/adapters/ifc_tester_ids_validator.py`

### Optional advisory

Verdict-neutral and capability-gated.

- [Hybrid route gate](https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/application/services/hybrid_route_gate.py): AI policy service · Classifies data and enforces privacy, trust, budget, and egress policy. · `backend/src/aerobim/application/services/hybrid_route_gate.py`
- [LLM/VLM provider](https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/infrastructure/adapters/openai_compat_llm_provider.py): OpenAI-compatible adapter · Optional audited advisory output only. · `backend/src/aerobim/infrastructure/adapters/openai_compat_llm_provider.py`

### Persistence & integrations

- [Artifact storage](https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/infrastructure/adapters/local_object_store.py): object-store adapter · Local storage by default; S3-compatible storage is optional. · `backend/src/aerobim/infrastructure/adapters/local_object_store.py`
- [BCF ZIP export](https://github.com/konkovdv/aerobim/blob/main/backend/src/aerobim/infrastructure/adapters/bcf3_exporter.py): export adapter · Produces structural BCF 2.1/3.0 ZIP exports. · `backend/src/aerobim/infrastructure/adapters/bcf3_exporter.py`

### Browser client

- [Review application](https://github.com/konkovdv/aerobim/blob/main/frontend/src/App.tsx): Vite React client · Presents findings, provenance, capabilities, and drawing evidence. · `frontend/src/App.tsx`
- [IFC scene viewer](https://github.com/konkovdv/aerobim/blob/main/frontend/src/lib/ifc-scene.ts): web-ifc / Three.js · `frontend/src/lib/ifc-scene.ts`

## Connections

- FastAPI API assembly → Package upload routes: mounts
- FastAPI API assembly → Report review routes: mounts
- FastAPI API assembly → Export routes: mounts
- Package upload routes → Package analysis: starts analysis
- Package upload routes → Analysis jobs: submits large jobs
- Analysis jobs → Package analysis: runs
- Package analysis → Deterministic orchestrators: orchestrates
- Package analysis → Artifact storage: reads and writes artifacts
- Deterministic orchestrators → IFC validation: validates IFC
- Deterministic orchestrators → IDS validation: validates IDS
- Requirements to IDS → IDS validation: produces IDS for validation
- Deterministic orchestrators → Findings & provenance: creates deterministic findings
- Deterministic orchestrators → Hybrid route gate: requests advisory
- Hybrid route gate → LLM/VLM provider: allowed advisory calls
- Report review routes → Findings & provenance: retrieves outcomes
- Report review routes → HITL review events: applies review events
- Export routes → BCF ZIP export: exports reports
- DI container → Runtime settings: uses selections
- DI container → IFC validation: binds port
- DI container → Artifact storage: binds port
- Review application → FastAPI API assembly: calls HTTP API
- Review application → IFC scene viewer: renders IFC