Architecture Design Document¶

Version: 1.0  ·  Date: May 2025  ·  Status: Approved

This document defines the technical architecture for the Construo platform — a configurable, multi-tenant construction project management SaaS.

1. Executive Summary¶

The platform is designed to be sold to multiple construction companies, each with different data capture requirements, workflows, and identity providers.

Core priorities:

• Maintainability for a small team starting at 2 engineers
• Security and compliance from day one (ISO 27001, SOC 2, Cyber Essentials)
• Offline-first capability for construction sites with poor connectivity
• Configurability — tenants define their own schemas, modules, and branding
• A clear growth path from 4 tenants at launch to 100+ at scale

Technology decisions at a glance¶

2. System Architecture¶

High-level layers¶

Request flow¶

A typical authenticated API request:

1. User browser or mobile app requests acme.construo.io
2. Route 53 resolves the wildcard subdomain to CloudFront
3. CloudFront applies WAF rules, forwards to ALB
4. ALB routes to ECS Fargate task running FastAPI
5. FastAPI middleware extracts tenant from subdomain, loads tenant context from Redis (fallback to DB)
6. JWT validated against Cognito. Tenant membership and RBAC role attached to request context
7. Business logic executes against the tenant's PostgreSQL schema
8. Response returned. Async side-effects (audit logs, notifications) dispatched to SQS

Why FastAPI over Next.js¶

The original recommendation was Next.js for developer speed. This was revised because the platform commits to Python for V2 AI features (Smart Import, Licence Scanning). Maintaining two backend languages — JavaScript API routes and Python AI services — would create unnecessary complexity. FastAPI is the right single-language choice.

OpenAPI as the contract: FastAPI auto-generates an OpenAPI spec. The frontend uses openapi-typescript to generate TypeScript types from it as a pre-build step. Any breaking API change fails the frontend build immediately — no manual type maintenance.

3. AWS Infrastructure¶

Service map¶

Network architecture¶

Three subnet tiers:

• Public — ALB, NAT Gateway only. Nothing else is directly internet-accessible.
• Private — ECS Fargate tasks, Lambda functions. Outbound via NAT Gateway.
• Data — RDS, ElastiCache. No outbound internet. Accessible only from private subnets.

Multi-region¶

Phase 1 deploys to eu-west-2 (London) only. EU data residency tenants are added to eu-central-1 (Frankfurt) from Phase 2. The tenant registry stores each tenant's home region; the application routes accordingly.

Environments¶

4. Multi-Tenancy and Data Isolation¶

Strategy: schema-per-tenant¶

Each tenant gets a dedicated PostgreSQL schema within the shared RDS instance. All tenant tables live under their schema (e.g. acme.projects, acme.personnel). A shared public schema contains the tenant registry and global configuration.

Tenant registry¶

The public.tenants table is the first lookup on every request:

Tenant provisioning¶

When a new tenant is onboarded:

1. Insert row into public.tenants
2. CREATE SCHEMA {schema_name}
3. Run Alembic migrations targeting the new schema
4. Seed default config (field definitions, module settings, roles)
5. Provision Cognito User Pool App Client
6. Configure Entra ID federation if applicable
7. Create S3 bucket prefix: s3://construo-files-prod/{tenant_id}/
8. Set up CloudWatch log group and metric filters
9. Provision tenant subdomain DNS record via Route 53

5. Authentication and Access Control¶

Architecture¶

AWS Cognito is the central identity broker. All authentication methods produce a consistent JWT regardless of the sign-in method.

RBAC roles¶

Permission enforcement¶

Three layers — defence in depth, required for SOC 2 and ISO 27001:

1. FastAPI dependency injection — every route declares required permissions via Depends(require_permission('sites:write'))
2. Database row-level checks — schema_name is always part of query context. Parameterised queries only.
3. Frontend route guards — React Router guards for UX only; API is the authoritative enforcement point.

JWT custom claims¶

Cognito-issued JWTs contain these custom claims added via a Lambda trigger:

• tenant_id — UUID of the tenant
• tenant_slug — subdomain slug for routing
• platform_roles — list of RBAC roles
• project_access — list of project UUIDs (empty = all within tenant)

6. Offline Sync Architecture¶

Why this is non-trivial¶

Construction sites frequently have no mobile data coverage. Users must be able to record site diary entries, log personnel, capture plant movements, and raise incidents without internet. When connectivity returns, changes must sync reliably without data loss or corruption.

Building a reliable sync engine from scratch is a multi-month engineering effort with subtle failure modes. PowerSync is a managed service that solves this problem.

PowerSync integration¶

Sync scope¶

Not all data syncs to all clients:

• Site Foreman: assigned sites, site diary entries (last 90 days), personnel list, plant register, pending forms
• Project Manager: all sites within assigned projects, aggregated view data
• Large binaries (documents, images) — fetched on-demand from S3 via signed URLs, cached by service worker

Conflict resolution¶

V1 uses last-write-wins with server authority. Each record has updated_at. When a client syncs, conflicts resolve in favour of the most recent server timestamp. Client changes are queued in a local SQLite upload queue and replayed in order when connectivity returns.

7. Core Data Model¶

Design principles¶

• Core fields — fixed columns for universally required attributes (IDs, timestamps, relationships)
• Custom fields — a JSONB custom_fields column on each entity stores tenant-defined attributes
• Audit trail — every table has a corresponding _audit table capturing before/after state, user, and timestamp

Universal columns (all tables)¶

Core entities¶

Key entities: projects, sites, site_diary_entries, personnel, site_attendance, plant_equipment, incidents, documents, deliveries, subcontractors, inductions, field_definitions.

Full column-level schemas are documented in Data Model and will be expanded as each module is built.

8. Configurability Engine¶

Three levels¶

1. Field Schema — tenants add custom fields to any entity
2. Module Configuration — tenants enable/disable platform modules
3. White-Label — branding, subdomain, theme colours

Field definitions table¶

Field definitions are Redis-cached (5-minute TTL), invalidated when a tenant admin saves changes.

V1 Modules¶

9. Integration Architecture¶

Generic ERP integration layer¶

Rather than building bespoke connectors for each ERP system, the integration model uses a Transform Pipeline approach:

1. Platform API — versioned REST API, all data accessible via authenticated API key
2. Transform service — a small Python Lambda per ERP integration containing the field mapping logic
3. ERP API / file — REST (Procore, Autodesk), file export (Sage, Viewpoint), webhook (Oracle)
4. Scheduler — EventBridge triggers the transform Lambda on a defined cadence

Platform API principles¶

• Versioned from day one: /api/v1/. Never break existing consumers.
• Cursor-based pagination on all list endpoints
• Webhook support: tenants register URLs for entity events
• Rate limiting: per API key, enforced at ALB via WAF (1,000 req/min default)
• Idempotency keys on write operations

V2 — Smart Import¶

1. Upload CSV/XLSX → S3 → SQS queue
2. Lambda parses headers and sample rows
3. Claude API interprets columns, proposes field mapping JSON
4. User confirms/adjusts the mapping
5. FastAPI validates and bulk-inserts with error report on partial failures

V2 — Licence Scanning¶

1. Mobile camera → upload to S3 via presigned URL
2. Lambda invokes AWS Textract
3. Claude API interprets raw Textract output → name, licence number, expiry, categories
4. User confirms before saving to personnel.licences JSONB

10. Security and Compliance¶

Target frameworks¶

Key controls¶

GDPR¶

• UK tenants: eu-west-2. EU tenants: eu-central-1. No transfer outside UK/EU.
• Tenant data export: JSON export of all data for a named person (right of access)
• Tenant data deletion: right to erasure — triggers anonymisation workflow
• Data retention: configurable per tenant; nightly Lambda applies retention policies
• DPA: Data Processing Agreement template, signed before any tenant goes live

11. Phased Delivery Plan (Summary)¶

For the full sprint-by-sprint breakdown, see Project Plan.

12. Monorepo Structure¶

platform/
├── apps/
│   ├── api/                  # FastAPI backend
│   │   ├── src/
│   │   │   ├── core/         # Auth, tenant context, db, audit
│   │   │   ├── modules/      # Sites, personnel, plant, etc.
│   │   │   └── main.py
│   │   ├── tests/
│   │   ├── alembic/
│   │   └── Dockerfile
│   └── web/                  # React frontend
│       ├── src/
│       │   ├── core/
│       │   └── modules/
│       └── vite.config.ts
├── packages/
│   ├── types/                # Auto-generated TypeScript from OpenAPI spec
│   ├── db/                   # SQLAlchemy models, Alembic migrations
│   └── shared/               # Constants, enums
├── infra/
│   └── terraform/            # All AWS infrastructure
│       ├── modules/
│       └── environments/     # dev, staging, prod
├── .github/
│   └── workflows/            # CI/CD pipelines
└── docs/                     # This documentation site

13. Key Risks¶