Skip to main content

Architecture overview

Constellation is a Turborepo monorepo of independent modules (apps) sitting on top of shared platform packages. Each module owns its own database schema and exposes a Zod-validated HTTP API.

apps/
  directory/         → identity, orgs, users, roles   (schema: identity)
  catalog/           → PIM, CPQ, supplier offers      (schema: catalog)
  project-tracker/   → programmes, projects, tasks    (schema: projects)

packages/
  platform/auth/     → JWT, clearance, permissions
  platform/db/       → tenant-scoped Prisma, audit trail
  platform/events/   → outbox event publishing
  platform/audit/    → transactional audit helper
  contracts/         → shared Zod schemas + types
  ui/                → shared React components

Apps never import from other apps. Cross-module communication happens via events (append-only contracts) and typed service contracts exposed by each module.

Core invariants​

  • Single Postgres, schema-per-module. One database (constellation), one schema per module. RLS policies enforce tenant isolation at the database layer.
  • Tenant context is explicit. Every query runs under app.tenant_id, set per request via withTenantAuth middleware.
  • No any. Zod schemas define the wire format; TypeScript types derive via z.infer.
  • Events are append-only. Domain events (organisation.created, task.completed, …) are the public contract between modules.
  • Audit critical writes. Use auditCritical() from @constellation-platform/audit for mutations that must be forensically replayable.

Full specs​

The canonical architecture documents: