Skip to main content

Infrastructure Architecture

Infrastructure deployment documentation covering the Iteration Stack (development) and Production Stack (AWS with CloudFront, Fargate, and Keycloak).


Deployment Environments​

EnvironmentStackPurpose
Local StackDocker Compose + API Docs + API ServerLocal development
Iteration StackLightsail + nginx + Remix + API ServerShared development environment
Production StackCloudFront + ECS Fargate + Aurora + KeycloakProduction deployment

Local Stack​

The Local Stack runs on your development machine using Docker Compose.

Architecture​

Components​

ComponentContainerPortPurpose
API DocsDocusaurus3000Interactive API documentation
API ServerREST API4000Backend API
DatabasePostgreSQL5432Data storage

Running Locally​

# Start all services
docker compose up -d

# View API docs
open http://localhost:3000

# View Scalar API Reference
open http://localhost:3000/scalar

Connecting SDK​

import { OpenAPI } from '@scp/sdk';

// Configure SDK for local development
OpenAPI.BASE = 'http://localhost:4000';

Iteration Stack​

The Iteration Stack is a lightweight shared development environment for internal UAT and feedback, running on AWS Lightsail with a Load Balancer for managed SSL.

Architecture​

Components​

ComponentTechnologyPortPurpose
Load BalancerLightsail LB443SSL termination, routing, health checks
Static Servernginx80Static files (mirrors CloudFront in prod)
Web ServerNestJS3000SSR + API
DatabasePostgreSQL5432Data storage

Cost​

~$38/month ($20 instance + $18 load balancer). Includes free managed SSL certificates.

Connecting to Iteration Stack​

import { OpenAPI } from '@scp/sdk';

// Configure SDK for Iteration Stack
OpenAPI.BASE = 'https://iteration.service-commerce-platform.alvera.ai';

Production Stack​

The Production Stack uses AWS managed services for high availability, security, and scalability.

Architecture​

Component Ownership​

ComponentIaC ToolPurpose
CloudFront DistributionCloudFormationGlobal CDN, edge caching
CloudFront FunctionCloudFormationURL routing logic
S3 Static AssetsCloudFormationStatic files (CSS, JS, images)
Application Load BalancerTerraformOIDC authentication, TLS termination
ECS Fargate (SSR)TerraformRemix server-side rendering
ECS Fargate (API)TerraformREST API server
Aurora PostgreSQLTerraformPrimary database
KMSTerraformEncryption key management
Secrets ManagerTerraformAPI keys, credentials
KeycloakTerraformIdentity provider (OIDC)

Authentication Flow​

ALB Native OIDC Integration​

ALB handles the entire OIDC flow - no custom authentication code required. The application receives validated user claims as HTTP headers.

JWT Claims​

The ALB injects user claims as HTTP headers after OIDC validation:

HeaderContent
x-amzn-oidc-identityUser ID (sub claim)
x-amzn-oidc-dataBase64-encoded JWT with all claims
x-amzn-oidc-accesstokenAccess token for API calls

RBAC Roles​

RoleDescriptionScopes
platform_adminFull platform accessAll tenants, all merchants
merchant_adminMerchant organization adminAll merchants in org
merchant_staffDay-to-day operationsSingle merchant
end_customerCustomer with accountWrite appointment data, own appointments
end_customer_guestGuest customerWrite-only access to current appointment

CloudFront Configuration​

URL Routing​

Cache Policies​

Path PatternOriginCache TTLHeaders Forwarded
/static/*S31 yearNone
/scp/*ALBNo cacheAll (Cookie, Auth)
/api/*ALBNo cacheAll (Cookie, Auth)
/* (default)S31 dayNone

High Availability​

Multi-AZ Deployment​

  • ECS Fargate: Tasks run in multiple availability zones
  • Aurora PostgreSQL: Configured with Multi-AZ failover
  • ALB: Distributes traffic across zones

Auto-Scaling​

  • ECS Fargate: Auto-scales based on CPU/memory metrics (target: 70% CPU)
  • Aurora Serverless v2: Automatically scales ACUs based on load

Security​

Encryption​

LayerMethod
At RestKMS for database, S3, EBS volumes
In TransitTLS 1.3 for all external connections
SecretsSecrets Manager for credentials

Network Isolation​

  • Public Subnets: ALB only
  • Private Subnets (App): ECS tasks
  • Private Subnets (Data): Aurora database
  • Security Groups: Least privilege access

Security Groups​

ResourceInboundOutbound
ALB443 from 0.0.0.0/0ECS SG on 3000, 4000
ECS SSR3000 from ALB SGAPI SG, Internet
ECS API4000 from ALB SG, SSR SGAurora SG, KMS, Internet
Aurora5432 from ECS SGNone

User Synchronization​

The platform syncs local user records with Keycloak using webhooks:

EventWebhookAction
User Createduser.createdCreate local record
User Updateduser.updatedSync email, name, roles
User Deleteduser.deletedSoft delete
Role Changeduser.role_updatedUpdate roles

Design Decisions​

DecisionRationale
CloudFormation for EdgeCloudFront + S3 tightly coupled
Terraform for BackendBetter state management for ECS, ALB, RDS
ALB + Fargate for SSRNo cold starts, native streaming, built-in OIDC
ALB Native OIDCZero custom auth code
ECS Fargate over EC2Serverless, no patching
Aurora Serverless v2Auto-scaling, pay-per-use
Keycloak over IDPFull control, customizable, multi-tenant