# orenh57/test2 architecture

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

- Interactive diagram: https://gitdiagram.com/orenh57/test2
- Repository: https://github.com/orenh57/test2

## Overview

#### Purpose and runtime entry points
CereBI is a tenant-scoped operational digital-twin and intelligence platform. Operational source data is ingested, mapped into a MongoDB-backed twin, then queried by console APIs and bounded calculation workflows. Production runtime starts through the FastAPI application factory at `src/cerebi/app/backend/server.py`, with composition/lifecycle wiring in `src/cerebi/app/backend/composition/application_factories.py` and `src/cerebi/app/backend/composition/lifespan.py`. The browser UI is a React/Vite SPA rooted at `src/cerebi/app/frontend/src/main.jsx`.

#### Application boundary and UI
The backend is the sole browser-to-data HTTP boundary; browsers do not access MongoDB. Route modules expose domains including analytics, twin/object browsing, tenant administration, configuration, and task execution: `src/cerebi/app/backend/routes/analytics.py`, `src/cerebi/app/backend/routes/object_browser.py`, and `src/cerebi/app/backend/routes/task_execution.py`. The frontend consumes these APIs through `src/cerebi/app/frontend/src/api/client.js`; major operational views include `src/cerebi/app/frontend/src/pages/DigitalTwinExplorerPage.jsx` and `src/cerebi/app/frontend/src/pages/WorkbenchPage.jsx`. Built frontend assets are served by the backend, while Vite is a separate development runtime.

#### Composition, tenancy, and authorization
`app` owns dependency composition and tenant scoping, keeping `data` and `intelligence` implementation-independent. Tenant access and configuration are composed in `src/cerebi/app/backend/composition/tenant_access.py` and `src/cerebi/app/backend/configuration.py`. Backend workflows translate HTTP operations into domain reads or commands, notably `src/cerebi/app/backend/workflows/tenant_catalog.py`, `src/cerebi/app/backend/workflows/data_operations.py`, and `src/cerebi/app/backend/workflows/task_execution.py`. Analytics-specific and loopback security controls sit at `src/cerebi/app/backend/security/analytics.py` and `src/cerebi/app/backend/security/loopback.py`.

#### Digital twin ingestion and persistence
The data subsystem transforms external sources into normalized twin objects and relationships. Ingestion supports spreadsheet/Drive CSV synchronization and snapshot loading through `src/cerebi/data/ingestion/sync_worker.py`, `src/cerebi/data/ingestion/spreadsheet_ingestion.py`, and `src/cerebi/data/ingestion/twin_snapshot_loader.py`. Object-model mapping and validation form the source-to-twin boundary in `src/cerebi/data/object_model/loader.py`, `src/cerebi/data/object_model/config_mapper.py`, and `src/cerebi/data/object_model/validation.py`. Twin documents and relationships are stored and queried via `src/cerebi/data/storage/twin_storage.py`, `src/cerebi/data/storage/twin_relationships.py`, and `src/cerebi/data/relationships/twin_map_mongo.py`.

#### External inputs and infrastructure
MongoDB is the operational system of record for tenant configuration, twins, registry state, and persisted intelligence results. The only production Mongo driver-construction boundary is `src/cerebi/foundation/mongo/provider.py`, configured through `src/cerebi/foundation/mongo/configuration.py`. Aurora/RDS support is an explicit read-only source adapter in `src/cerebi/data/storage/aurora.py`, not a normal request-path dependency. Weather enrichment integrates NWS and Open-Meteo through `src/cerebi/data/inputs/weather/nws.py` and `src/cerebi/data/inputs/weather/openmeteo.py`.

#### Intelligence execution pipeline
Intelligence is configured by a model/task registry, then executes capabilities against twin-derived inputs. Bootstrap assembles tenant/client frameworks and validates registry configuration in `src/cerebi/intelligence/bootstrap/container.py`, `src/cerebi/intelligence/bootstrap/registry_config.py`, and `src/cerebi/intelligence/registry/service.py`. The calculation runner resolves inputs, guards execution, invokes adapters, finalizes results, and supports caching/locking: `src/cerebi/intelligence/calculation/runner.py`, `src/cerebi/intelligence/calculation/resolution.py`, and `src/cerebi/intelligence/calculation/result_finalization.py`. Capability adapters include route-delay scoring at `src/cerebi/intelligence/capabilities/route_delay/adapter.py` and relationship ranking at `src/cerebi/intelligence/capabilities/relationship_ranking/adapter.py`.

#### Results, impact, and recommendations
Completed calculations can persist results, write twin-facing outputs, evaluate impact configuration, and generate recommendations. These boundaries are represented by `src/cerebi/intelligence/persistence/mongo/store.py`, `src/cerebi/intelligence/twin/result_sink.py`, `src/cerebi/intelligence/impact/engine.py`, and `src/cerebi/intelligence/recommendation/service.py`. Memory and no-op implementations across these subsystems provide non-production or isolated execution modes; Mongo implementations are the durable runtime path.

Main entry points: [`src/cerebi/intelligence/calculation/runner.py`](https://github.com/orenh57/test2/blob/main/src/cerebi/intelligence/calculation/runner.py) (Calculation runner), [`src/cerebi/data/storage/twin_storage.py`](https://github.com/orenh57/test2/blob/main/src/cerebi/data/storage/twin_storage.py) (Twin storage), [`src/cerebi/app/backend/composition/application_factories.py`](https://github.com/orenh57/test2/blob/main/src/cerebi/app/backend/composition/application_factories.py) (App composition), [`src/cerebi/app/backend/workflows/task_execution.py`](https://github.com/orenh57/test2/blob/main/src/cerebi/app/backend/workflows/task_execution.py) (Backend workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser UI"]
  node_spa["React/Vite SPA<br/>frontend<br/>[main.jsx]"]
  node_api_client["API client<br/>frontend client<br/>[client.js]"]
end

subgraph group_backend["Application"]
  node_server{{"FastAPI server<br/>runtime entry<br/>[server.py]"}}
  node_composition["App composition<br/>dependency wiring"]
  node_tenant_access["Tenant access<br/>tenant scoping<br/>[tenant_access.py]"]
  node_routes["HTTP routes<br/>API routes<br/>[analytics.py]"]
  node_workflows["Backend workflows<br/>application workflows<br/>[task_execution.py]"]
  node_security["Analytics security<br/>security controls<br/>[analytics.py]"]
  node_mongo_provider["Mongo provider<br/>driver boundary<br/>[provider.py]"]
end

subgraph group_data["Digital Twin Data"]
  node_ingestion["Source ingestion<br/>ingestion pipeline<br/>[sync_worker.py]"]
  node_object_mapping["Object mapping<br/>twin normalization<br/>[loader.py]"]
  node_twin_storage["Twin storage<br/>twin repository<br/>[twin_storage.py]"]
  node_aurora["Aurora read adapter<br/>read-only source<br/>[aurora.py]"]
  node_weather["Weather inputs<br/>external enrichment<br/>[nws.py]"]
end

subgraph group_intelligence["Intelligence"]
  node_bootstrap["Intelligence bootstrap<br/>framework assembly<br/>[container.py]"]
  node_registry["Model/task registry<br/>capability registry<br/>[service.py]"]
  node_runner["Calculation runner<br/>execution pipeline<br/>[runner.py]"]
  node_capabilities["Capability adapters<br/>calculation adapters<br/>[adapter.py]"]
  node_result_store["Result store<br/>durable results<br/>[store.py]"]
  node_result_sink["Twin result sink<br/>twin output writer<br/>[result_sink.py]"]
  node_impact["Impact engine<br/>impact evaluation<br/>[engine.py]"]
  node_recommendations["Recommendations<br/>recommendation service<br/>[service.py]"]
end

node_mongodb[("MongoDB<br/>operational system of record")]

node_spa -->|"uses"| node_api_client
node_api_client -->|"HTTP API"| node_server
node_server -->|"starts with"| node_composition
node_composition -->|"composes"| node_tenant_access
node_composition -->|"registers"| node_routes
node_composition -->|"constructs"| node_mongo_provider
node_routes -->|"enforces"| node_security
node_routes -->|"dispatches"| node_workflows
node_tenant_access -->|"scopes tenants"| node_workflows
node_workflows -->|"reads and commands"| node_twin_storage
node_workflows -->|"requests tasks"| node_bootstrap
node_mongo_provider -->|"connects"| node_mongodb
node_ingestion -->|"raw records"| node_object_mapping
node_object_mapping -->|"normalized twins"| node_twin_storage
node_aurora -.->|"read-only source"| node_ingestion
node_twin_storage -->|"twin documents"| node_mongodb
node_bootstrap -->|"initializes"| node_registry
node_bootstrap -->|"configures"| node_runner
node_registry -->|"resolves tasks"| node_runner
node_runner -->|"resolves twin inputs"| node_twin_storage
node_weather -->|"enrichment inputs"| node_runner
node_runner -->|"invokes"| node_capabilities
node_runner -->|"persists"| node_result_store
node_runner -->|"writes outputs"| node_result_sink
node_runner -->|"evaluates"| node_impact
node_impact -->|"informs"| node_recommendations
node_result_store -->|"results"| node_mongodb
node_result_sink -->|"twin-facing results"| node_twin_storage
node_registry -->|"registry state"| node_mongodb

click node_spa "https://github.com/orenh57/test2/blob/main/src/cerebi/app/frontend/src/main.jsx"
click node_api_client "https://github.com/orenh57/test2/blob/main/src/cerebi/app/frontend/src/api/client.js"
click node_server "https://github.com/orenh57/test2/blob/main/src/cerebi/app/backend/server.py"
click node_composition "https://github.com/orenh57/test2/blob/main/src/cerebi/app/backend/composition/application_factories.py"
click node_tenant_access "https://github.com/orenh57/test2/blob/main/src/cerebi/app/backend/composition/tenant_access.py"
click node_routes "https://github.com/orenh57/test2/blob/main/src/cerebi/app/backend/routes/analytics.py"
click node_workflows "https://github.com/orenh57/test2/blob/main/src/cerebi/app/backend/workflows/task_execution.py"
click node_security "https://github.com/orenh57/test2/blob/main/src/cerebi/app/backend/security/analytics.py"
click node_mongo_provider "https://github.com/orenh57/test2/blob/main/src/cerebi/foundation/mongo/provider.py"
click node_ingestion "https://github.com/orenh57/test2/blob/main/src/cerebi/data/ingestion/sync_worker.py"
click node_object_mapping "https://github.com/orenh57/test2/blob/main/src/cerebi/data/object_model/loader.py"
click node_twin_storage "https://github.com/orenh57/test2/blob/main/src/cerebi/data/storage/twin_storage.py"
click node_aurora "https://github.com/orenh57/test2/blob/main/src/cerebi/data/storage/aurora.py"
click node_weather "https://github.com/orenh57/test2/blob/main/src/cerebi/data/inputs/weather/nws.py"
click node_bootstrap "https://github.com/orenh57/test2/blob/main/src/cerebi/intelligence/bootstrap/container.py"
click node_registry "https://github.com/orenh57/test2/blob/main/src/cerebi/intelligence/registry/service.py"
click node_runner "https://github.com/orenh57/test2/blob/main/src/cerebi/intelligence/calculation/runner.py"
click node_capabilities "https://github.com/orenh57/test2/blob/main/src/cerebi/intelligence/capabilities/route_delay/adapter.py"
click node_result_store "https://github.com/orenh57/test2/blob/main/src/cerebi/intelligence/persistence/mongo/store.py"
click node_result_sink "https://github.com/orenh57/test2/blob/main/src/cerebi/intelligence/twin/result_sink.py"
click node_impact "https://github.com/orenh57/test2/blob/main/src/cerebi/intelligence/impact/engine.py"
click node_recommendations "https://github.com/orenh57/test2/blob/main/src/cerebi/intelligence/recommendation/service.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_spa,node_api_client toneBlue
class node_server,node_composition,node_tenant_access,node_routes,node_workflows,node_security,node_mongo_provider toneAmber
class node_ingestion,node_object_mapping,node_twin_storage,node_aurora,node_weather toneMint
class node_bootstrap,node_registry,node_runner,node_capabilities,node_result_store,node_result_sink,node_impact,node_recommendations toneRose
class node_mongodb toneNeutral
```

## Components

### Browser UI

- [React/Vite SPA](https://github.com/orenh57/test2/blob/main/src/cerebi/app/frontend/src/main.jsx): frontend · Operational console; production assets are served by the backend. · `src/cerebi/app/frontend/src/main.jsx`
- [API client](https://github.com/orenh57/test2/blob/main/src/cerebi/app/frontend/src/api/client.js): frontend client · `src/cerebi/app/frontend/src/api/client.js`

### Application

- [FastAPI server](https://github.com/orenh57/test2/blob/main/src/cerebi/app/backend/server.py): runtime entry · Sole browser-to-data HTTP boundary. · `src/cerebi/app/backend/server.py`
- [App composition](https://github.com/orenh57/test2/blob/main/src/cerebi/app/backend/composition/application_factories.py): dependency wiring · Builds application services and lifecycle dependencies. · `src/cerebi/app/backend/composition/application_factories.py`
- [Tenant access](https://github.com/orenh57/test2/blob/main/src/cerebi/app/backend/composition/tenant_access.py): tenant scoping · Composes tenant access and configuration. · `src/cerebi/app/backend/composition/tenant_access.py`
- [HTTP routes](https://github.com/orenh57/test2/blob/main/src/cerebi/app/backend/routes/analytics.py): API routes · Exposes analytics, twin browsing, and task execution. · `src/cerebi/app/backend/routes/analytics.py`
- [Backend workflows](https://github.com/orenh57/test2/blob/main/src/cerebi/app/backend/workflows/task_execution.py): application workflows · Translates HTTP operations into twin reads, commands, and tasks. · `src/cerebi/app/backend/workflows/task_execution.py`
- [Analytics security](https://github.com/orenh57/test2/blob/main/src/cerebi/app/backend/security/analytics.py): security controls · Analytics and loopback execution controls. · `src/cerebi/app/backend/security/analytics.py`
- [Mongo provider](https://github.com/orenh57/test2/blob/main/src/cerebi/foundation/mongo/provider.py): driver boundary · Only production Mongo driver-construction boundary. · `src/cerebi/foundation/mongo/provider.py`

### Digital Twin Data

- [Source ingestion](https://github.com/orenh57/test2/blob/main/src/cerebi/data/ingestion/sync_worker.py): ingestion pipeline · Synchronizes spreadsheet/Drive CSV sources and loads snapshots. · `src/cerebi/data/ingestion/sync_worker.py`
- [Object mapping](https://github.com/orenh57/test2/blob/main/src/cerebi/data/object_model/loader.py): twin normalization · Maps and validates external records into the twin model. · `src/cerebi/data/object_model/loader.py`
- [Twin storage](https://github.com/orenh57/test2/blob/main/src/cerebi/data/storage/twin_storage.py): twin repository · Stores and queries twin documents and relationships. · `src/cerebi/data/storage/twin_storage.py`
- [Aurora read adapter](https://github.com/orenh57/test2/blob/main/src/cerebi/data/storage/aurora.py): read-only source · Explicit non-request-path RDS source adapter. · `src/cerebi/data/storage/aurora.py`
- [Weather inputs](https://github.com/orenh57/test2/blob/main/src/cerebi/data/inputs/weather/nws.py): external enrichment · NWS and Open-Meteo integrations. · `src/cerebi/data/inputs/weather/nws.py`

### Intelligence

- [Intelligence bootstrap](https://github.com/orenh57/test2/blob/main/src/cerebi/intelligence/bootstrap/container.py): framework assembly · Builds tenant/client frameworks and validates registry configuration. · `src/cerebi/intelligence/bootstrap/container.py`
- [Model/task registry](https://github.com/orenh57/test2/blob/main/src/cerebi/intelligence/registry/service.py): capability registry · `src/cerebi/intelligence/registry/service.py`
- [Calculation runner](https://github.com/orenh57/test2/blob/main/src/cerebi/intelligence/calculation/runner.py): execution pipeline · Resolves inputs, guards execution, invokes adapters, and finalizes results. · `src/cerebi/intelligence/calculation/runner.py`
- [Capability adapters](https://github.com/orenh57/test2/blob/main/src/cerebi/intelligence/capabilities/route_delay/adapter.py): calculation adapters · Includes route-delay scoring and relationship ranking. · `src/cerebi/intelligence/capabilities/route_delay/adapter.py`
- [Result store](https://github.com/orenh57/test2/blob/main/src/cerebi/intelligence/persistence/mongo/store.py): durable results · Persists completed intelligence results in Mongo. · `src/cerebi/intelligence/persistence/mongo/store.py`
- [Twin result sink](https://github.com/orenh57/test2/blob/main/src/cerebi/intelligence/twin/result_sink.py): twin output writer · Writes calculation outputs for twin consumers. · `src/cerebi/intelligence/twin/result_sink.py`
- [Impact engine](https://github.com/orenh57/test2/blob/main/src/cerebi/intelligence/impact/engine.py): impact evaluation · `src/cerebi/intelligence/impact/engine.py`
- [Recommendations](https://github.com/orenh57/test2/blob/main/src/cerebi/intelligence/recommendation/service.py): recommendation service · `src/cerebi/intelligence/recommendation/service.py`

### Other components

- **MongoDB**: operational system of record · Stores tenant configuration, twins, registry state, and persisted results.

## Connections

- React/Vite SPA → API client: uses
- API client → FastAPI server: HTTP API
- FastAPI server → App composition: starts with
- App composition → Tenant access: composes
- App composition → HTTP routes: registers
- App composition → Mongo provider: constructs
- HTTP routes → Analytics security: enforces
- HTTP routes → Backend workflows: dispatches
- Tenant access → Backend workflows: scopes tenants
- Backend workflows → Twin storage: reads and commands
- Backend workflows → Intelligence bootstrap: requests tasks
- Mongo provider → MongoDB: connects
- Source ingestion → Object mapping: raw records
- Object mapping → Twin storage: normalized twins
- Aurora read adapter → Source ingestion: read-only source
- Twin storage → MongoDB: twin documents
- Intelligence bootstrap → Model/task registry: initializes
- Intelligence bootstrap → Calculation runner: configures
- Model/task registry → Calculation runner: resolves tasks
- Calculation runner → Twin storage: resolves twin inputs
- Weather inputs → Calculation runner: enrichment inputs
- Calculation runner → Capability adapters: invokes
- Calculation runner → Result store: persists
- Calculation runner → Twin result sink: writes outputs
- Calculation runner → Impact engine: evaluates
- Impact engine → Recommendations: informs
- Result store → MongoDB: results
- Twin result sink → Twin storage: twin-facing results
- Model/task registry → MongoDB: registry state