Skip to content

System Overview

The platform is a multi-tenant SaaS for construction project management. Each tenant (a construction company) has isolated data, users, and configuration.

High-level architecture

graph TB
    User[Construction PM] -->|HTTPS| CF[CloudFront + WAF]
    CF -->|Static assets| S3[S3 Frontend Bucket]
    CF -->|API requests| ALB[Application Load Balancer]
    ALB --> ECS[ECS Fargate<br/>FastAPI containers]
    ECS --> RDS[(RDS PostgreSQL<br/>schema-per-tenant)]
    ECS --> Redis[(ElastiCache Redis<br/>cache + sessions)]
    ECS --> S3F[S3 Files<br/>per-tenant prefix]
    ECS --> Cognito[AWS Cognito<br/>+ Entra ID SAML]
    ECS --> SQS[SQS Queue]
    SQS --> Lambda[Lambda Workers<br/>async jobs]
    PS[PowerSync Cloud] --> RDS
    User -.->|Offline sync| PS

Technology layers

Layer Technology Why
Frontend React + TypeScript + Vite Strong typing, fast dev, good talent pool
Offline sync PowerSync Managed sync — building it ourselves would take months
Backend FastAPI (Python 3.12) Async, auto OpenAPI, strong validation, AI-ready
Database PostgreSQL on RDS Mature, supports schemas for isolation, well-known
Cache Redis on ElastiCache Standard for session + cache, low ops overhead
Files S3 Scalable, versioned, lifecycle policies
Identity AWS Cognito Federation with Entra ID, managed token issuance
Container runtime ECS Fargate No servers to patch, autoscaling, AWS-native
Edge CloudFront + WAF DDoS protection, edge caching, managed security rules

Request flow

A typical authenticated API request:

  1. User browser makes request to acme.platform.com
  2. Route 53 resolves wildcard DNS to CloudFront
  3. CloudFront applies WAF rules, forwards to ALB
  4. ALB routes to a healthy ECS Fargate task
  5. FastAPI middleware:
  6. Extracts tenant from Host header
  7. Looks up tenant in Redis (falls back to RDS)
  8. Validates JWT token against Cognito public keys
  9. Sets PostgreSQL search_path to tenant schema
  10. Route handler executes business logic against tenant data
  11. Response returned to user
  12. Audit log dispatched to SQS for async processing

Multi-region strategy

Phase 1: eu-west-2 (London) only. Phase 2+: Add eu-central-1 (Frankfurt) for EU tenants with data residency requirements.

The tenant registry stores each tenant's region. The application layer routes database connections accordingly.

Reading order

If this is your first time, read these next in order:

  1. Multi-Tenancy — the most important architectural concept
  2. Authentication
  3. Data Model
  4. Offline Sync