Architecture #

platform4 uses domain documents in *.ddd/ directories as the product source of truth. Its compiler produces PostgreSQL schemas, OpenAPI services, row-level security policies, reference contracts, and TypeScript clients. Module-specific behavior lives in *.hooks.ts files and declared custom operations.

Union-master + projection #

Modules that fold external standards (notably Ed-Fi) keep a union-master write model and derived projections for reads that must match a wire shape. Commands land in the master; projections are rebuilt or updated transactionally so list/get doors stay consistent with the DDD contract.

Tenancy (RLS) #

Every tenant-scoped table is protected with PostgreSQL row-level security. Runtime services connect as a non-owner app role (DATABASE_URL per module). Table owners bypass ENABLE RLS, so the owner role is reserved for schema-install / migration tasks only.

Auth model #

  • Issuer: Cognito user pool (M2M client-credentials in v1).
  • Wire: Authorization: Bearer <jwt>.
  • Claims: pre-token Lambda injects tenantId, roles, and audience.
  • Config: Services receive their token issuer, audience, and signing-key configuration at deployment.

Deploy shape #

  • One VPC and one Aurora Serverless v2 database, with a separate schema for each API module.
  • One ECS Fargate service per API module, plus this static documentation service, sits behind one internet-facing load balancer.
  • Routing is host-based. <module>.platform4.alphaschool.dev selects a module, while platform4.alphaschool.dev serves these docs. Unknown hosts receive a fixed 404.

Generated OpenAPI #

Each API reference is built from the same OpenAPI contract used to generate its service and TypeScript client. The published contract is available through the openapi.json link in the reference top bar.