CONSTELLATION — System Architecture Specification
Document Version: 1.1 — Architecture Concept Date: 26 February 2026 (revised April 2026) Classification: Internal — For Technical Review Status: Approved — Open questions resolved March 2026. Implementation may proceed. Section 12 updated April 2026 (Stella merger). Companion to: Constellation General Specification v0.3
This page is the entry point for the engineering-facing architecture spec. The original document was a 1,200-line single file; it has been split into the deep-linkable pages below so an agent or PR review can cite a specific section by URL. Sections 1 and 2 are reproduced inline because they're short and frame everything else.
Spec table of contents
| § | Section | Page |
|---|---|---|
| 1 | Purpose and Scope | (below) |
| 2 | Architectural Drivers | (below) |
| 3 | Module Rationalisation: From 13 to 7 | Module map |
| 4 | Monorepo Structure | Structure & packages |
| 5 | Shared Platform Packages | Structure & packages |
| 6 | Database Architecture | Database & tenancy |
| 7 | Identity, Tenancy and Access Control | Database & tenancy |
| 8 | Event-Driven Integration | Events & deployment |
| 9 | Deployment Strategy and Enterprise Readiness | Events & deployment |
| 10 | AI-Assisted Development Model | AI development |
| 11 | Existing Project-Tracker: Migration Strategy | Migration strategies |
| 12 | Relationship to Stella Catalog | Migration strategies |
| 13 | Patterns Adopted from Open Mercato | Patterns & roadmap |
| 14 | Execution Roadmap | Patterns & roadmap |
| 15 | Risk Register | Risks & decisions |
| 16 | Resolved Architecture Decisions | Risks & decisions |
1. Purpose and Scope
This document defines the system architecture for the Constellation platform. It translates the functional specification (Constellation General Specification v0.3) into a concrete technical design that accounts for:
- A small team (1-2 humans + AI coding agents) building the entire platform
- The need for each module to deliver standalone value while sharing cross-cutting infrastructure
- A migration path from SaaS prototype to enterprise-grade sovereign deployment
- 100% AI-assisted development, which imposes specific constraints on code organisation, context management, and testing strategy
This is a concept document for review. No implementation should begin until the architecture has been discussed, challenged, and approved.
What This Document Decides
- Repository structure and build system
- Module boundaries and what gets merged or deferred
- Shared vs. module-specific code boundaries
- Database isolation strategy
- Identity and access control architecture
- Inter-module communication pattern
- Build order and execution sequence
- AI agent development rules
What This Document Does NOT Decide
- Detailed data models for individual modules (each module will have its own design phase)
- UI/UX design system details (beyond establishing that
packages/uiexists) - Specific API endpoint designs
- Pricing, licensing, or commercialisation strategy
2. Architectural Drivers
These constraints, derived from the specification and practical reality, drive every architectural decision in this document.
D1: Modular Independence with Shared Infrastructure
"Organisations will be able to adopt Constellation module by module." — Spec Section 2
Each module must be deployable and usable independently. However, duplicating authentication, tenancy, event handling, and UI components across 7 modules is unsustainable for a small team. The architecture must provide shared infrastructure without creating tight coupling.
D2: Multi-Tenancy as a First-Class Concept
"Multi-tenancy... is a first-class architectural concept, not an afterthought." — Spec Section 5
Every data row, every API request, and every UI view operates within a tenant context. The database enforces isolation via Row-Level Security. The application layer cannot bypass it.
D3: Enterprise-Grade Security (Progressive)
"Security is not a layer applied on top — it is embedded in every component." — Spec Section 5
The specification requires hybrid RBAC/ABAC, data classification enforcement, per-tenant encryption keys, HSM support, FIPS 140-2 compliance, and air-gapped deployment support. These cannot all be built on day one, but the architecture must not make them impossible.
D4: Deployment Flexibility
"The platform's architecture must support [on-premises] deployment without modification to the application logic." — Spec Section 7
The current prototype uses Supabase (hosted auth + DB), Vercel (hosting), and S3-compatible storage. The production platform must support self-hosted PostgreSQL, Keycloak (or equivalent), MinIO, and containerised deployment. Every infrastructure dependency must be behind a provider abstraction.
D5: AI-Optimised Development
The entire codebase will be developed and maintained by AI coding agents supervised by 1-2 humans. This imposes specific constraints:
- Context window limits: Each module must fit within an AI agent's context window (~150 files)
- Isolation: An AI agent working on one module must not be able to accidentally break another
- Discoverability: Conventions, schemas, and contracts must be machine-readable
- Reproducibility: Module scaffolding must be templated so new modules start consistently
D6: Small Team Reality
With 1-2 humans and AI agents, the architecture must minimise operational overhead:
- Single repository (not 7+ repos to manage)
- Single database instance (not 7 databases to operate)
- Shared CI/CD pipeline (not per-module deployment infrastructure)
- Minimal runtime dependencies (not a Kubernetes cluster with 30 services)