This document describes the high-level architecture of the Nexus sovereign process orchestration platform: component boundaries, data flows, RBAC model, multi-tenancy, and deployment topologies.
The core UX metaphor is a single canvas navigable at four levels of detail. Each level exposes a different domain of control; keyboard navigation (breadcrumb, Esc to ascend) keeps context visible.
| Node Type | Category | Inputs | Outputs | Status |
|---|---|---|---|---|
| Form | Ingest | Schema ref, RBAC role config, style ref | Entity payload | GAP-02 (ChameleonV2) |
| OCR | Transform | Document reference, document type | Field map | M-NEXUS-BL01 |
| Validate | Transform | Entity payload, rule set ref | Entity + validation result | Nexus engine |
| AI Transform | Transform | Entity payload, prompt template, model config | Transformed entity | M-NEXUS-BL04 |
| Store | Egress | Entity payload, class ref, deltaPrism config | Entity ID | M-NEXUS-E1 |
| Forward | Egress | Entity payload, endpoint config, auth | Response status | M-NEXUS-E2 |
| Human Gate | Control | Entity payload, role required, form variant | Decision + entity | M-NEXUS-E3 |
| Trigger (Webhook) | Ingest | HTTP request | Raw payload | M-NEXUS-BL11 |
| Trigger (Schedule) | Ingest | Cron expression | Tick event | M-NEXUS-BL12 |
| SMS Ingest | Ingest | SMS gateway webhook | Message payload | M-NEXUS-BL02 |
| Voice Ingest + Transcribe | Ingest+Transform | Audio file or webhook | Transcript text | M-NEXUS-BL03 |
| Bank CSV Ingest | Ingest | CSV file path or upload | BankEntry entity list | M-NEXUS-BL07 |
| PDF Generate | Egress | Entity payload, template ref | PDF file | M-NEXUS-BL08 |
All resources are scoped to an Organisation. The hierarchy:
| Level | Model | Key | Notes |
|---|---|---|---|
| 1 | Organisation | org_slug | Top-level tenant. All resources scoped here. |
| 2 | OrgTeam | team | Has RBAC roles. Belongs to one Org. |
| 3 | OrgUser | user → team | Team membership. One user can be in multiple teams. |
| 3 | API Key | SHA-256 hash | Prefixed with org_slug. One-time display on create. |
| 2 | Pipeline | pipeline_id | Pipeline definition graph JSON. Belongs to Org. |
| 3 | NodeType | type registry | Per-org or global. 16 built-in types. |
| 3 | PipelineRun | run history | Status, telemetry, per-node logs. |
Org slugs are validated: lowercase, alphanumeric + hyphen, 3-40 chars. API keys are prefixed with the org slug for routing. Multiple orgs can share a Nexus instance or each run their own (sovereign).
| Role | Scope | ChameleonV2 Form Behaviour | Pipeline Access |
|---|---|---|---|
| Submitter | Entity-level | Submitter variant: personal fields editable, compliance fields read-only | Submit form only |
| Operator | Team-level | Operator variant: all fields visible, can edit non-sensitive | Run pipeline, view run log |
| Reviewer | Team-level | Reviewer variant: decision form, read-only entity view, approve/reject/request-more controls | Resolve Human Gate nodes |
| Admin | Org-level | Admin variant: all fields, plus config overrides | CRUD pipelines, manage users |
| Compliance Officer | Org-level | Audit variant: all fields read-only, full audit trail panel visible | View-only all runs |
| System | Internal | Not rendered | Automated nodes (OCR, Validate, Store, Forward) |
RBAC role config is stored per-field at NANO scale and consumed by ChameleonV2 at form render time.
The pipeline definition includes a role_map: maps user to role for each pipeline run context.
Human Gate nodes require a specific role to resolve; the pipeline run pauses until that role acts.
When ChameleonV2 renders a Form node URL, it calls GET /pipelines/{id}/nodes/{node_id}/schema
on the Nexus API. The response includes the class definition (fields, types, RBAC visibility per field)
and the BDT control map. ChameleonV2 renders the appropriate form variant for the authenticated user's role.
BDT controls are resolved at render-time from the deltaPrism BDT registry
(GET /bdt/{type}). Controls: Currency (locale + exchange rate), Document Reference (upload + OCR auto-fill),
Entity Link (live graph query picker), GeoPoint (map picker), Classification (live enum list from deltaPrism),
Computed (read-only formula expression).
| Milestone | Deliverable | Status |
|---|---|---|
| M-NEXUS-CV-1 | ChameleonV2 pulls schema from Nexus Form node at runtime | Queued |
| M-NEXUS-CV-2 | RBAC layer: per-role field visibility, editability, required override, enum filtering, layout variants | Queued |
| M-NEXUS-CV-3 | deltaPrism BDT controls: Currency, DocumentReference + Atlas OCR auto-fill, EntityLink, GeoPoint, Computed, Classification | Queued |
| M-NEXUS-CV-4 | Flow-level styling: style_ref in pipeline definition drives CSS token override per deployment | Queued |
The Nexus API publishes Server-Sent Events on GET /pipelines/{id}/runs/{run_id}/events.
The canvas subscribes at run start and updates node visual state in real time.
| Event Type | Payload Fields | Canvas Effect |
|---|---|---|
| node_started | node_id, timestamp | Node border pulses blue |
| node_waiting | node_id, waiting_for | Node amber pulse, waiting badge |
| node_awaiting_human | node_id, role_required, form_url | Node purple pulse, role badge, form link shown |
| node_complete | node_id, duration_ms, entity_count, output_ref | Node fill green, data packet animated along outgoing edges |
| node_failed | node_id, error_message, error_code | Node red border, error badge, log panel opens |
| run_complete | run_id, total_duration_ms, entity_count | Topbar run indicator shows completion summary |
python -m uvicorn nexus.main:app --port 8010 + python admin/app.py. deltaPrism and ChameleonV2 run separately on their own ports.docker compose up -d. Suitable for demos and staging.| Router | Base Path | Key Endpoints | Auth |
|---|---|---|---|
| Orgs | /orgs | CRUD orgs, teams, users. POST /orgs/{slug}/api-keys (returns raw key once) | Bearer API key |
| Pipelines | /pipelines | CRUD pipelines, node types. POST /pipelines/{id}/run. GET /pipelines/{id}/runs. GET /pipelines/runs/{run_id} | Bearer API key |
| Execution Events | /pipelines | GET /pipelines/{id}/runs/{run_id}/events (SSE stream) | Bearer API key |
| Schema | /pipelines | GET /pipelines/{id}/nodes/{node_id}/schema. PUT (update class definition) | Bearer API key |
| Rules | /rules | CRUD rules, rule versions. POST /rules/{id}/test | Bearer API key |
| Health | /health | GET /health (live check), GET /health/ready | None |
Replaces the hardcoded _USECASE_META dict in routes_orgs.py and the hardcoded
USE_CASES array in WORMWOOD_APP.html. All app metadata is stored in three new
database tables and served via GET /apps/catalog.
| Table | Purpose | Key Columns |
|---|---|---|
app_catalog | One row per deployed application | slug, display_name, domain, status_code, version, tenant_id, config JSONB |
app_component | Per-app component versions and connections | app_id FK, component_name, component_version, deployment_env, color_hex, connection_config JSONB |
app_action | Buttons rendered on each app card | app_id FK, label, action_type (navigate/pipeline/external), target, sort_order |
| Method | Path | Response | Auth |
|---|---|---|---|
| GET | /apps/catalog | Array of app objects with components[], actions[], pipeline_count | Bearer API key |
| GET | /apps/catalog/{slug} | Single app object | Bearer API key |
Each app card in the Orchestrator and Dashboard renders a visual jigsaw panel from components[]:
color_hex field (default palette: Wormwood=#19E28A, Chameleon=#8B5CF6, deltaPrism=#3B82F6, Admin=#F97316, Omnissiah=#EC4899).deployment_env.The current model (Section 03) scopes resources to an Organisation. O6 introduces a Tenant as a top-level isolation boundary above Organisations, enabling multiple independent clients on a single Nexus instance.
| Column | Type | Notes |
|---|---|---|
| id | INTEGER PK | |
| name | VARCHAR(100) | Display name |
| slug | VARCHAR(50) UNIQUE | URL-safe identifier |
| branding | JSONB | White-label config — logo, colors, app_name (REQ-WL-001) |
| encryption_key_ref | VARCHAR(200) | External key vault reference (REQ-ENC-001) |
| subscription_tier | VARCHAR(20) | free / pro / enterprise (REQ-AFF-001) |
| affiliate_code | VARCHAR(50) | Referral tracking |
| created_at | TIMESTAMP | DEFAULT NOW() |
app_catalog.tenant_id FK references tenant.id. All queries scoped via tenant_id where multi-tenancy is enforced.
Extends the role model in Section 04 with platform-level and tenant-level scopes, plus Nesto-specific roles.
| Role | Scope | Permissions |
|---|---|---|
| platform_admin | Global | All apps, all tenants, config, publishing |
| tenant_admin | Tenant | All apps within tenant, user management |
| app_admin | App | Pipeline CRUD, component config, user assignment |
| app_user | App | Execute pipelines, view dashboards |
| app_viewer | App | Read-only |
| nesto_hr_admin | Nesto app | Full CRUD on worker records, approval authority |
| nesto_reviewer | Nesto app | Review queue, approve/reject, no create |
| nesto_auditor | Nesto app | Read-only, full audit trail |
| nesto_submitter | Nesto app | Create worker records, no approve |
DRAFT → REVIEW → STAGING → PUBLISHED → DEPRECATED
| State | Description | Transition Gate |
|---|---|---|
| DRAFT | Under construction — not visible to tenants | Creator decision |
| REVIEW | Internal review — visible to platform_admin | Creator submits |
| STAGING | UAT in progress — visible to tenant_admin of test tenant | platform_admin approves |
| PUBLISHED | Live — visible to all tenants with subscription | All components healthy, tests pass, RBAC configured |
| DEPRECATED | End-of-life — no new tenants, existing tenants warned | platform_admin sets with migration path |
Versioning: semver (MAJOR.MINOR.PATCH) stored in app_catalog.version. Published apps are
immutable — a new version creates a new app_catalog row. The status_code column
drives visibility rules across all screens.
Affiliate (third-party) app instances require per-tenant data encryption in deltaPrism with external key storage and MFA-gated key release.
| Layer | Component | Detail |
|---|---|---|
| Encryption | AES-256-GCM | Applied at deltaPrism data-at-rest layer per tenant |
| Key storage | External vault | AWS KMS / Azure Key Vault / HashiCorp Vault — reference stored in tenant.encryption_key_ref |
| Key release gate | MFA | Vault will not release key without MFA confirmation from tenant_admin |
| Key rotation | Annual minimum | Rotation event logged in Liber Cogitatus as a Binding Decision |
Per-tenant branding stored in tenant.branding JSONB:
| Key | Type | Effect |
|---|---|---|
| logo_url | string (URL) | Replaces Nexus logo in all screens for this tenant |
| primary_color | hex string | Sets --hub-accent CSS variable |
| app_name | string | Replaces "Nexus" in page titles and headers |
| favicon_url | string (URL) | Browser tab icon |
| footer_text | string | Footer attribution (default: "Powered by Nexus") |
| hide_nexus_branding | boolean | Enterprise only — removes all UV/Nexus references |
Scope: Dashboard and Workspace screens apply tenant branding. Orchestrator always shows Nexus branding (admin tool). Login screen applies tenant branding when accessed via tenant subdomain.
| Tier | Apps | Pipelines | White-label |
|---|---|---|---|
| Free | 1 | 3 | No |
| Pro | 5 | Unlimited | No |
| Enterprise | Unlimited | Unlimited | Yes |
Revenue share tracked per tenant.affiliate_code. Affiliate codes issued by platform_admin.
Each Nexus org supports multiple named deployment environments. Environments are stored in
_tbl_org_environments and exposed via the Environments API. The App Management page
(APP_MGMT.html) provides lifecycle controls per environment.
| Status | Meaning | Allowed Actions |
|---|---|---|
| running | All components responding | stop, restart, backup, upgrade, downgrade |
| stopped | Intentionally offline | start |
| degraded | Partial response — one or more components failing | restart, backup |
| unknown | No health data yet (default after seed) | start, restart |
| Trigger | From | To | URL |
|---|---|---|---|
| Click org card | Hub Dashboard | App Management | APP_MGMT.html?org={slug}&skin={skin} |
| Open App CTA button | App Management | Workspace | NEXUS_APP.html?org={slug}&skin={skin}&base={url} |
| Back to Hub button | App Management | Hub Dashboard | NEXUS_APP.html (session state preserved) |
| Right-click org card | Hub Dashboard | App Management (direct) | APP_MGMT.html?org={slug} |
| Click health dot | Hub Dashboard | App Management (env tab) | APP_MGMT.html?org={slug} |
| Method | Path | Purpose |
|---|---|---|
| GET | /orgs/{slug}/environments | List all environments for org |
| POST | /orgs/{slug}/environments | Create new environment |
| GET | /orgs/{slug}/environments/{env} | Single environment detail |
| POST | /orgs/{slug}/environments/{env}/start | Start stopped environment |
| POST | /orgs/{slug}/environments/{env}/stop | Stop running environment |
| POST | /orgs/{slug}/environments/{env}/restart | Stop then start |
| POST | /orgs/{slug}/environments/{env}/backup | Snapshot data + config |
| POST | /orgs/{slug}/environments/{env}/upgrade | Deploy new version |
| POST | /orgs/{slug}/environments/{env}/downgrade | Roll back to prior version |
| GET | /orgs/{slug}/environments/{env}/backups | List snapshots |