1. Core Principle: Tech-Stack Independence
Nexus components communicate through layer contracts, not direct API calls. A Controller does not know whether its Model is PostgreSQL or Snowflake. A View does not know whether its Controller is a Python FastAPI service or an AWS Lambda function. Each layer implements a contract that defines input/output formats and determinism guarantees.
Why Tech-Stack Independence?
Enterprise clients have existing infrastructure investments. A bank running mainframe COBOL cannot adopt a product that requires Kubernetes. A startup on AWS Serverless will not install on-premises Docker. Tech-stack independence means the same business logic (rulesets, flows, data model, RBAC) deploys to any infrastructure without modification. The NSD describes what to deploy; the Deployment Matrix describes where it can go.
The practical consequence: a Nesto implementation running on AWS Lambda + Snowflake + React uses the same NSD as a Nesto implementation running on Power Platform + SharePoint + PowerApps. The rulesets are identical. The data model is identical. The RBAC is identical. Only the deployment targets change.
2. Layer Contracts
2.1 Controller Contract C-1.0
| Aspect | Requirement |
|---|---|
| Input | JSON payload: { "entity_class": "...", "record": {...}, "ruleset_id": "..." } |
| Output | JSON payload: { "result": {...}, "rules_applied": [...], "execution_ms": N } |
| Determinism | Same input + same ruleset = same output. No randomness. No external state dependency. |
| Formula Language | Must parse and evaluate the complete Wormwood formula syntax. |
| BDT Validation | Must validate all fields against their BDT constraints before rule execution. |
| Error Handling | Must return structured error objects, never crash with unhandled exceptions. |
2.2 Model Contract M-1.0
| Aspect | Requirement |
|---|---|
| Input | Entity operations: { "operation": "create|read|update|delete", "entity_class": "...", "data": {...} } |
| Output | Operation result: { "success": bool, "record": {...}, "version": N } |
| Lifecycle | Must enforce lifecycle class restrictions (IMMUTABLE_IDENTITY fields cannot be updated). |
| RBAC | Must enforce field-level RBAC: masked fields return ****, hidden fields omitted. |
| Audit | Must record who changed what and when. Append-only audit log. |
2.3 View Contract V-1.0
| Aspect | Requirement |
|---|---|
| Input | Entity schema from NSD data_model + style tokens from NSD style section. |
| Output | Rendered form / table / dashboard that the user interacts with. |
| RBAC | Must respect field-level RBAC: read-only fields are not editable, hidden fields are not rendered. |
| Style | Must apply global_tokens and per-flow style overrides. |
| Validation | Must validate BDT constraints client-side before submission. |
2.4 Orchestration Contract O-1.0
| Aspect | Requirement |
|---|---|
| Input | Flow graph definition from NSD flows section + trigger event. |
| Output | Flow run record: { "run_id": "...", "status": "...", "node_results": [...] } |
| Graph Execution | Execute nodes in topological order. Respect ConditionBranch routing. |
| Human Gates | Pause flow at ApprovalGate nodes, resume on human decision. |
| Determinism | Same graph + same input + same gate decisions = same execution path. |
Why Contract-Based MVC?
Traditional MVC frameworks bind all three layers to one technology (Rails: Ruby everywhere, Django: Python everywhere). Nexus MVC contracts decouple the layers so that a React View can consume data from a Snowflake Model via a Lambda Controller. The contract is the interface boundary. This is analogous to how HTTP APIs decouple client and server — but applied at the architectural layer level with determinism and RBAC guarantees that HTTP alone does not provide.
3. Deployment Target Matrix
3.1 Controller Implementations
| target_stack | Implementation | Formula Engine | Conformance |
|---|---|---|---|
python-fastapi | Wormwood Python + FastAPI | Native Python eval | CL-3 |
aws-lambda | Wormwood Python on Lambda | Native Python eval | CL-3 |
azure-functions | Wormwood Python on Azure Functions | Native Python eval | CL-2 |
snowflake-snowpark | Wormwood Snowpark UDFs | SQL CASE translation | CL-2 |
databricks-pyspark | Wormwood PySpark pipelines | Spark expression eval | CL-2 |
ms-office-vba | Wormwood VBA macro library | VBA formula transpiler | CL-1 |
power-platform | Wormwood PowerFx component | PowerFx formula transpiler | CL-1 |
docker-onprem | Wormwood Docker container | Native Python eval | CL-3 |
bare-metal-onprem | Wormwood systemd service | Native Python eval | CL-3 |
mainframe-zos | Wormwood COBOL copybooks | COBOL evaluation logic | CL-1 |
3.2 Model Implementations
| target_stack | Implementation | Lifecycle Enforcement | Conformance |
|---|---|---|---|
delta-prism-python | deltaPrism graph + FastAPI | Native graph constraints | CL-3 |
postgresql | PostgreSQL + triggers | CHECK constraints + triggers | CL-3 |
snowflake | Snowflake tables + streams | Stream policies + UDFs | CL-2 |
databricks-delta-lake | Delta Lake + Unity Catalog | Column constraints | CL-2 |
azure-cosmos-db | Cosmos DB + stored procedures | SP-based enforcement | CL-2 |
aws-neptune | Neptune graph + Gremlin | Property constraints | CL-2 |
sharepoint-lists | SharePoint Online lists | Column validation formulas | CL-1 |
ms-access | Access database + forms | Input masks + validation rules | CL-1 |
excel-worksheets | Excel named tables | Data validation + protection | CL-1 |
db2-mainframe | DB2 on z/OS | CHECK constraints + triggers | CL-1 |
3.3 View Implementations
| target_stack | Implementation | Style Support | Conformance |
|---|---|---|---|
chameleonv2-react | ChameleonV2 React SPA | Full CSS custom properties | CL-3 |
chameleonv2-umd | ChameleonV2 UMD bundle | Full CSS custom properties | CL-3 |
power-apps | PowerApps Canvas App | Theme variables | CL-1 |
sharepoint-spfx | SPFx web parts | Fluent UI theming | CL-2 |
excel-forms | Excel input forms + VBA | Cell formatting | CL-1 |
cli-terminal | Terminal / console interface | ANSI colors | CL-1 |
pdf-static | Static PDF reports (ReportLab) | Typography + colors | CL-1 |
3.4 Orchestration Implementations
| target_stack | Implementation | Gate Support | Conformance |
|---|---|---|---|
nexus-runtime-python | Nexus Python runtime | Full (webhook + polling) | CL-3 |
aws-step-functions | AWS Step Functions ASL | Callback tasks | CL-3 |
azure-logic-apps | Azure Logic Apps | Approval connectors | CL-2 |
power-automate | Power Automate flows | Approval actions | CL-1 |
airflow-prefect | Airflow / Prefect DAGs | Manual triggers | CL-2 |
databricks-workflows | Databricks Workflows | Task dependencies | CL-2 |
jcl-mainframe | JCL job streams | Manual step (WTOR) | CL-1 |
4. Mix-and-Match Deployment Examples
Cloud-Native SaaS
For SaaS vendors deploying multi-tenant applications on AWS.
Microsoft Enterprise
For organisations standardised on Microsoft 365 with Power Platform licensing.
Data Lake Analytics
For data engineering teams running compliance scoring on large datasets.
On-Premises Docker
For security-conscious organisations that require all data on-site.
Spreadsheet Prototype
For rapid prototyping or small teams without IT infrastructure.
Mainframe Integration
For legacy financial institutions running core systems on IBM z/OS.
Azure Cosmos Graph
For Azure-first organisations with complex entity relationships.
Databricks Lakehouse
For data teams using Databricks for ETL, ML, and operational analytics.
Hybrid Cloud + On-Prem
Controller in the cloud for scalability, data stays on-premises for compliance.
PDF Report Pipeline
Batch processing with static output for audit and compliance reporting.
Why Mix-and-Match?
No single technology stack is optimal for all deployment scenarios. A bank needs mainframe compatibility. A startup needs serverless cost efficiency. A government agency needs on-premises data residency with cloud-based computation. The mix-and-match model means Nexus is not a product that requires adoption of a specific technology — it is a product that adapts to whatever technology the client already has. The NSD carries the business logic; the Deployment Matrix determines where each layer runs.
5. Conformance Testing
Every target stack implementation must pass a suite of conformance tests to validate that it correctly implements the layer contract. Tests are grouped into categories with pass/fail verdicts.
| Category | Code | Description |
|---|---|---|
| Rule Determinism | CT-RULE | Same input + same rules = same output (100 random seeds) |
| Formula Coverage | CT-FORM | All Wormwood formula constructs evaluate correctly |
| BDT Validation | CT-BDT | All BDT constraint types enforced (min, max, regex, enum) |
| Lifecycle Enforcement | CT-LIFE | IMMUTABLE_IDENTITY blocks updates, OPERATIONAL_EVENT blocks deletes |
| RBAC Enforcement | CT-RBAC | Hidden fields not returned, masked fields show **** |
| Audit Trail | CT-AUDIT | Every mutation produces an audit record with who/what/when |
| Flow Execution | CT-FLOW | DAG execution follows topological order, gates pause correctly |
| Style Tokens | CT-STYLE | View renders with correct colours, fonts, border-radius |
| Error Handling | CT-ERR | Invalid input returns structured error, never crashes |
| Performance | CT-PERF | Rule evaluation completes within SLA for batch sizes |
5.1 Conformance Levels
| Level | Requirement | Suitable For |
|---|---|---|
| CL-1 | CT-RULE + CT-FORM + CT-BDT pass. Core rule evaluation works. | Prototyping, internal tools, non-regulated use cases |
| CL-2 | CL-1 + CT-LIFE + CT-RBAC + CT-ERR pass. Data integrity and access control guaranteed. | Production workloads, departmental apps, moderate compliance |
| CL-3 | All 10 test categories pass. Full platform capabilities. | Regulated industries, SaaS, multi-tenant, audit-sensitive |
Why Tiered Conformance?
Not every deployment needs full audit trails. An Excel prototype for a startup does not need the same conformance guarantees as a bank's production compliance engine. Tiered conformance allows Nexus to be deployed on constrained platforms (Excel, Access, SharePoint) at CL-1, while reserving CL-3 for enterprise production. Clients see exactly what each platform supports and can make informed infrastructure decisions.
6. Component Versioning
Each Nexus component follows SemVer (MAJOR.MINOR.PATCH). Contract versions change only on MAJOR bumps.
| Component | Version | Contract | Status |
|---|---|---|---|
| Wormwood Engine | 0.2.0 | C-1.0 | Active |
| deltaPrism | 0.1.0 | M-1.0 | Active |
| ChameleonV2 | 1.2.2 | V-1.0 | Active |
| Nexus Runtime | 0.1.0 | O-1.0 | Active |
| Wormwood Admin | 0.2.0 | n/a | Active |
| Atlas OCR | 0.1.0 | n/a | Declared |
7. Compatibility Matrix
Specifies which component versions are compatible with each other. A deployment is valid only if all component versions appear in the same compatibility set.
| Compatibility Set | Wormwood | deltaPrism | ChameleonV2 | Runtime |
|---|---|---|---|---|
| CS-1 (current) | 0.2.x | 0.1.x | 1.2.x | 0.1.x |
8. Batch and Parallel Execution
The Controller contract supports batch mode: submitting an array of records for evaluation in a single request. Target stacks with native parallelism (Snowpark, PySpark, Step Functions) can evaluate records concurrently. Target stacks without parallelism (VBA, Access) evaluate sequentially. The contract guarantees identical results regardless of execution mode.
Why Batch as a Contract Feature?
Enterprise use cases involve thousands or millions of records per run (end-of-month compliance checks, bulk invoice validation). A Controller that only handles one record at a time requires the Orchestration layer to loop — adding latency and complexity. By making batch a first-class contract feature, the Controller implementation can optimise internally (PySpark broadcasts rules across executors, Snowpark runs UDFs in parallel) while the caller always sends the same payload shape.
9. Component Capability Catalogue
Each layer declares its capabilities as a structured set. The NSD references capability codes to determine which features are available on the selected target stack.
9.1 Controller Capabilities (C-CAP)
| Code | Capability | Description |
|---|---|---|
| C-CAP-01 | Rule Execution | Execute rulesets against entity records |
| C-CAP-02 | Formula Evaluation | Parse and evaluate Wormwood formulas |
| C-CAP-03 | BDT Validation | Validate fields against BDT constraints |
| C-CAP-04 | Batch Processing | Process arrays of records in one request |
| C-CAP-05 | Priority Ordering | Execute rules in priority order |
| C-CAP-06 | Technology Scoping | Filter rules by technology scope tag |
| C-CAP-07 | Dependency Chains | Execute dependent rules in correct order |
| C-CAP-08 | Scoring | Generate compliance/risk scores |
| C-CAP-09 | Hot Reload | Reload rulesets without restart |
| C-CAP-10 | Rule Versioning | Track rule version per execution |
| C-CAP-11 | Explain Mode | Return step-by-step formula evaluation trace |
| C-CAP-12 | Dry Run | Evaluate rules without writing results |
| C-CAP-13 | Parallel Eval | Evaluate independent rules concurrently |
| C-CAP-14 | EDR Profiling | Generate entity-driven requirement profiles |
| C-CAP-15 | Lua Rules | Execute Lua-based enrichment rules |
| C-CAP-16 | API Key Auth | Authenticate via API key headers |
| C-CAP-17 | Health Check | Report service health and version |
9.2 Model Capabilities (M-CAP)
| Code | Capability | Description |
|---|---|---|
| M-CAP-01 | Entity CRUD | Create, read, update, delete entity records |
| M-CAP-02 | Lifecycle Enforcement | Block operations violating lifecycle class |
| M-CAP-03 | RBAC Filtering | Apply field-level RBAC on read |
| M-CAP-04 | Audit Trail | Append-only mutation log |
| M-CAP-05 | Graph Relationships | Store and traverse entity relationships |
| M-CAP-06 | Version History | Track all record versions |
| M-CAP-07 | Bulk Import | Import thousands of records in one operation |
| M-CAP-08 | Schema Migration | Migrate data model on NSD update |
| M-CAP-09 | Encryption at Rest | Encrypt masked/sensitive fields |
| M-CAP-10 | Backup Export | Export all data as NSD-compatible snapshot |
| M-CAP-11 | Search Index | Full-text search across entity fields |
9.3 View Capabilities (V-CAP)
| Code | Capability | Description |
|---|---|---|
| V-CAP-01 | Dynamic Forms | Render forms from entity class schema |
| V-CAP-02 | RBAC Rendering | Show/hide/mask fields per role |
| V-CAP-03 | Client Validation | Validate BDT constraints before submit |
| V-CAP-04 | Style Tokens | Apply global theme from NSD style section |
| V-CAP-05 | Table Views | Tabular listing with sort/filter/pagination |
| V-CAP-06 | Flow Dashboard | Show pipeline run status and history |
| V-CAP-07 | Gate UI | Render approval forms for ApprovalGate nodes |
| V-CAP-08 | File Upload | Upload documents for OCR/IngestNode processing |
| V-CAP-09 | Responsive Layout | Adapts to mobile, tablet, desktop |
| V-CAP-10 | Accessibility | WCAG 2.1 AA compliance |
| V-CAP-11 | Localisation | Multi-language support via NSD string tables |
| V-CAP-12 | Offline Mode | Queue submissions when offline, sync on reconnect |
9.4 Orchestration Capabilities (O-CAP)
| Code | Capability | Description |
|---|---|---|
| O-CAP-01 | DAG Execution | Execute flow graphs in topological order |
| O-CAP-02 | Human Gates | Pause at ApprovalGate, resume on decision |
| O-CAP-03 | Conditional Routing | Branch on ConditionBranch node expressions |
| O-CAP-04 | Retry Logic | Automatic retry with backoff on node failure |
| O-CAP-05 | Timeout Control | Per-node and per-flow timeout limits |
| O-CAP-06 | Run History | Persistent record of all flow executions |
| O-CAP-07 | Webhook Triggers | Start flows from external webhook events |
| O-CAP-08 | Scheduled Triggers | Cron-based flow scheduling |
| O-CAP-09 | Parallel Nodes | Execute independent branches concurrently |
| O-CAP-10 | Sub-Flow Calls | One flow triggers another as a node |
Why a Capability Catalogue?
When the NSD specifies a deployment target, the DevOps Service checks whether the target stack supports all capabilities required by the NSD's flows and data model. If a flow uses OCRNode but the selected Controller does not implement C-CAP-15 (Lua Rules for OCR preprocessing), the deployment plan fails with a clear error: "Target ms-office-vba does not support C-CAP-15 (Lua Rules)." This is a compile-time check for deployments — catching incompatible combinations before they reach production.
Architecture Summary
| Design Decision | Problem Addressed | Mechanism |
|---|---|---|
| Layer contracts | Technology lock-in | I/O format + determinism contracts, not API bindings |
| 34 target stacks | Infrastructure diversity across clients | 10 Controller + 10 Model + 7 View + 7 Orchestration targets |
| Mix-and-match | No single stack fits all clients | Any C + M + V + O combination if contracts match |
| Conformance levels | Constrained platforms cannot pass all tests | CL-1 / CL-2 / CL-3 tiered certification |
| Capability catalogue | Unclear feature support per platform | Enumerated capabilities checked at deploy time |
| SemVer + compat sets | Version incompatibilities in production | Compatibility sets define valid version combinations |
| Batch as contract | Slow one-record-at-a-time processing | Array input in contract, parallel eval in implementation |
| Formula portability | Rules locked to Python runtime | Constrained expression language compilable to any target |
11. Versioned Document References
| Document | Version | Authority | Relationship |
|---|---|---|---|
| System Descriptor (NSD) | NSD-1.0 | Tier 1 | Parent specification |
| Rule Registry | RR-1.0 | Tier 3 | Rules deployed to targets |
| Node Registry | NR-1.0 | Tier 3 | Executors per target stack |
| BDT Registry | BDT-1.0 | Tier 3 | Type contracts enforced per layer |
| Component Status | CS-1.0 | Tier 3 | Implementation readiness per target |
| Validation Registry | VR-1.0 | Tier 3 | Conformance test bundles |
| AWS Deployment Plan | ADP-1.0 | Tier 3 | AWS target architecture and sprint plan (NX-S18..S20) |
| Roadmap | RM-1.6 | Tier 2 | Target expansion timeline |
| Use Case Register | UC-1.0 | Tier 2 | Deployments per use case |