Architecture

CREATE TABLE _tbl_calcrule_profiles (



    id                  INTEGER PRIMARY KEY,



    slug                TEXT UNIQUE NOT NULL,          -- machine name e.g. tco-dc-cooling



    name                TEXT NOT NULL,                 -- display name



    description         TEXT,



    technology_variants TEXT DEFAULT '[]',             -- JSON array



    domain              TEXT NOT NULL DEFAULT 'tco',  -- bounded context: tco / edr / pfp



    is_active           INTEGER NOT NULL DEFAULT 0,   -- active within domain only



    version             TEXT DEFAULT '1.0.0',



    created_at          DATETIME,



    updated_at          DATETIME



);







CREATE TABLE _tbl_calcrule_rules (



    id             INTEGER PRIMARY KEY,



    profile_id     INTEGER NOT NULL REFERENCES _tbl_calcrule_profiles(id),



    rule_id        TEXT NOT NULL,                -- e.g. infra_001_servers_per_rack



    name           TEXT NOT NULL,



    formula        TEXT NOT NULL,



    output         TEXT,



    rule_type      TEXT,                         -- infrastructure / capex / opex / tco / scoring



    technology     TEXT,                         -- NULL = applies to all technologies



    priority       INTEGER DEFAULT 0,



    enabled        INTEGER NOT NULL DEFAULT 1,



    excel_source   TEXT,



    excel_baseline REAL,



    description    TEXT,



    created_at     DATETIME,



    updated_at     DATETIME,



    UNIQUE (profile_id, rule_id)



);

See Data Model for the full schema including target tables (_tbl_calcrule_rule_audit, _tbl_api_keys) and PFP rule JSON schema.

Browser / Revit Plugin / CLI



  ├── GET  /ui/index.html       (SPA — Calc, Rules, Graph, Inspector tabs)



  ├── GET  /api/profiles/active ──────────────────────────────────────┐



  ├── POST /pfp/clearance                                              │



  ├── POST /pfp/select                                                 │



  ├── POST /api/profiles/{key}/run                                     │



  └── PATCH/DELETE /rules/{id}  (auth-gated write ops)                │



                                                                       │



FastAPI Engine (port 8010 prod / 8012 dev)                            │



  ├── nexus/api/app.py              (22 routes)                     │



  ├── nexus/api/routes_rule_editor.py (7 routes)                   │



  ├── nexus/core/profile_store.py   (SQLite read) ◄──────────────┘



  ├── nexus/core/pfp_pipeline.py    (formula pipeline)



  ├── nexus/core/pfp_table_pipeline.py (table pipeline)



  ├── nexus/core/dynamic_rule_engine.py (TCO/EDR)



  ├── nexus/core/edr_pipeline.py



  ├── nexus/core/ingestion_pipeline.py + datasource.py



  └── ui/index.html  (mounted at /ui/ as StaticFiles)







Flask Admin (port 8011)



  ├── admin/models.py   (Profile, CalculationRule SQLAlchemy models)



  ├── admin/admin.db    (SQLite — shared with FastAPI via filesystem)



  └── admin/seed_pfp.py (PFP profile seeder — import format only)







Dockerised stack (docker-compose.yml)



  ├── nexus-engine  → FastAPI (port 8010)



  └── nexus-admin   → Flask admin (port 8011)

The FastAPI engine reads the SQLite file directly (no Flask context required) via profile_store.py, which uses a plain sqlite3 connection. This avoids a circular dependency between the two services while keeping both pointing at the same DB file.

The SPA (ui/index.html) is a single-file Vanilla JS ES2020 application served as static files. It has no build pipeline. All JS modules (Settings, Profiles, Rules, Calc, Inspector, Graph, Tabs) are IIFE-scoped within the file.

1. Admin panel marks new profile active (flips is_active within domain).
2. Activate route filters by domain: WHERE domain = ? before flipping flags.
3. FastAPI reads the active profile by domain on every request: WHERE domain = ? AND is_active = 1.
4. No server restart required.
5. Old profile remains in DB for rollback.

Nexus is a multi-domain platform. Each domain is a bounded context with its own profile, connectors, entity types, and API execution endpoints. Profile is_active is scoped to domain — activating a PFP profile does not affect the TCO or EDR domains.

Two separate datasource systems exist in Nexus and do not currently interact.

System 1 — Connector Layer

nexus/core/datasource.py + ingestion_pipeline.py. Connects to external systems to extract entity rows for EDR validation. Supports: SQLite, CSV, JSON, Excel, Access (.accdb), PostgreSQL, ODBC, REST API. Configured via YAML files in nexus/config/datasources/. Fed through IngestionPipeline → EDRPipeline. Not rule-aware.

System 2 — Rule Store

nexus/core/profile_store.py. Reads calculation rules from admin/admin.db (_tbl_calcrule_rules). Supplies rules to all execution pipelines (TCO, EDR, PFP). Uses plain sqlite3, not the connector layer.

Immutability Contract

• DataSources supply immutable read snapshots to rule execution — they are never written to during a pipeline run.
• Rule definitions are immutable at execution time — loaded once, applied, then discarded.
• Rule outputs are variant and engine-mediated — they cannot be read from cache as if they were reference data.

Target Architecture

Bridge the two systems. profile_store.py gains a configurable backend; when the NEXUS_RULE_STORE env var points to a remote DB (or DeltaPrism graph engine), rules are sourced from there rather than the local SQLite. No changes to the rule execution engine or API surface required.