Architecture / AS-0

Wormwood — Tech Stack & Topology

Wormwood is a standalone pipeline orchestration engine. It is independently deployed, independently hosted, and independently operated. This document defines its deployment topology, tech stack, and integration contracts with the products that consume it.

AS-0 Mandate

Wormwood cannot run on a Nexus instance. Wormwood cannot share a container or process with any UI product. It is independently hosted on its own compute with its own database and its own port bindings. Any architecture that embeds Wormwood inside another product's deployment is a violation of this mandate.

Deployment Topology

Three independently hosted systems. Connections are HTTP API calls only — no shared file systems, no shared processes, no shared databases.

Wormwood Host

FastAPI Engine

wormwood.api.app — port 8010

Flask Admin

admin.app — port 8011

SQLite / PostgreSQL

org, team, user, pipeline, run data

Rule Store

rules/ JSON files — loaded at startup

GPU Runtime

runtimes/delta_prism_gpu/ — optional

HTTP

port 8010
API calls

↔

NeXus Hub — port 8020

nexus_ui (FastAPI + Jinja2)

Standalone Python web app — hub dashboard + workspace shell

WORMWOOD_APP.html

Orchestrator canvas SPA — browser (separate, unchanged)

Docker / ECS

Production host for nexus_ui container

Session + API Key

Server-side session (itsdangerous) — keys never in browser

HTTP

port 15000
graph ops

↔

deltaPrism Host

deltaPrism API

Graph DB + GPU engine — port 15000

BDT Registry

Business Data Type definitions

cuGraph / NetworkX

GPU-accelerated graph ops

Optional. Wormwood functions fully without deltaPrism. Graph nodes fall back to local storage.

Wormwood Tech Stack

Runtime

LanguagePython 3.11+

API frameworkFastAPI + Starlette

ASGI serveruvicorn

Admin panelFlask + Flask-Admin

ORMSQLAlchemy

Storage

Dev databaseSQLite (embedded)

Prod databasePostgreSQL 15+

Rule storeJSON files (rules/)

Graph storedeltaPrism (optional)

Networking

API port8010 (canonical)

Admin port8011

AuthX-API-Key header

Rate limitingslowapi (per-key)

CORSconfigured in app.py

Optional Modules

GPU runtimeCUDA + cuGraph

DatabricksNotebook runtime

SnowflakeUDF runtime (WIP)

LambdaAWS serverless shim

Wormwood API Contract (consumed by Nexus)

Nexus SPAs authenticate with X-API-Key and call these endpoints. All endpoints live at the Wormwood host — Nexus has no backend of its own.

Endpoint	Method	Consumer	Purpose
`/api/orgs/login-list`	GET	NEXUS_APP.html	Public org list for login screen
`/api/orgs/authenticate`	POST	NEXUS_APP.html	User authentication against org
`/api/orgs/user-hub`	GET	NEXUS_APP.html	All orgs and roles for a user
`/api/orgs/{slug}`	GET	NEXUS_APP.html	Org detail and pipeline list
`/api/orgs/apps/catalog`	GET	NEXUS_APP.html	Use-case catalog for org cards
`/api/pipelines/{id}/run`	POST	WORMWOOD_APP.html	Execute a pipeline
`/api/pipelines/{id}/graph`	GET	WORMWOOD_APP.html	Fetch pipeline graph JSON
`/api/pipelines/{id}/graph`	PUT	WORMWOOD_APP.html	Save edited pipeline graph
`/api/pipelines/runs/{id}/status`	GET	NEXUS_APP.html	Poll run status and result
`/api/pipelines/runs/stream/{id}`	GET (SSE)	NEXUS_APP.html	Streaming run log
`/health`	GET	NEXUS_APP.html	Engine health check (hub bar)

Wormwood Deployment Options

All options run Wormwood independently. Nexus SPAs are always served separately.

Option	Wormwood host	Nexus SPA host	Status
Local dev	`localhost:8010` (uvicorn direct)	Served by Wormwood at `/nexus-ui/` (dev convenience only)	Active
Docker local	`localhost:8010` (docker-compose.yml)	Served by Wormwood `/nexus-ui/` or separate nginx	Active
AWS ECS	ECS task, port 8010 via ALB	CloudFront + S3 static hosting	Planned (ISSUE-008)
Self-hosted server	Any Linux host, port 8010, Caddy/nginx as reverse proxy	nginx static or CDN	Supported
Standalone (no Nexus)	Any host, port 8010 + 8011 admin	None — access via admin panel or direct API	Fully supported

Architecture Violations — Forbidden Patterns

Wormwood container image that includes Nexus SPA HTML files at build time
Nexus docker-compose that starts Wormwood as a named service dependency
Wormwood described as "the Nexus backend" in any document (it is a standalone product that Nexus uses)
Any Python import in Wormwood that references Nexus2 files or modules
Deploying both Wormwood and Nexus SPAs on the same application server under a single process
Wormwood started on any port other than 8010 for the API (8012 or others are bugs)
start_ui.ps1 or any dev script targeting a non-canonical port

RBAC — Nexus Inherits from Wormwood

Nexus does not have its own authentication or user management. All identity is stored in Wormwood.

Concept	Lives in	Nexus role
Organisation	Wormwood DB (`Org` model)	Reads via `/api/orgs/`
Team	Wormwood DB (`Team` model)	Reads via `/api/orgs/{slug}/teams`
User	Wormwood DB (`OrgUser` model)	Authenticates via `/api/orgs/authenticate`
API Key	Wormwood DB (`ApiKey` model)	Passes in `X-API-Key` header
Pipeline	Wormwood DB (`Pipeline` model)	Reads and runs via pipeline routes
Roles	Wormwood (`OrgUser.role` field)	Controls visibility in hub cards and forms

Canonical Startup Commands

Wormwood standalone

# Start API engine (port 8010)
Set-Location Wormwood
.\.venv\Scripts\python.exe -m uvicorn wormwood.api.app:app --host 0.0.0.0 --port 8010

# Start admin panel in separate terminal (port 8011)
.\.venv\Scripts\python.exe -m flask --app admin.app run --host 0.0.0.0 --port 8011

Open Nexus SPAs (browser, separate from Wormwood)

# Hub dashboard
http://localhost:8010/nexus-ui/NEXUS_APP.html

# Orchestrator canvas
http://localhost:8010/nexus-ui/WORMWOOD_APP.html

# (Development shortcut: Wormwood serves the HTML files under /nexus-ui/,
#  but this is not an architectural coupling. In production, SPAs are on CDN.)

Reference Documents

Document	Repo	Authority	Subject
WORMWOOD_PROJECT_MANDATE.md	Wormwood root	AS-0	Standalone mandate (this doc's source)
NEXUS_HLD.html	Nexus2 docs	AS-1	Nexus product high-level design
NEXUS_LLD.html	Nexus2 docs	AS-2	Nexus LLD — function signatures, API routes
NEXUS_DEPLOYMENT_MATRIX.html	Nexus2 docs	AS-2	Layer contracts and deployment targets
NEXUS_COMPONENT_STATUS.html	Nexus2 docs	AS-3	Implementation status of all components