Infrastructure Architecture
Infrastructure deployment documentation covering the Iteration Stack (development) and Production Stack (AWS with CloudFront, Fargate, and Keycloak).
Deployment Environments
| Environment | Stack | Purpose |
|---|
| Local Stack | Docker Compose + API Docs + API Server | Local development |
| Iteration Stack | Lightsail + nginx + Remix + API Server | Shared development environment |
| Production Stack | CloudFront + ECS Fargate + Aurora + Keycloak | Production deployment |
Local Stack
The Local Stack runs on your development machine using Docker Compose.
Architecture
Components
| Component | Container | Port | Purpose |
|---|
| API Docs | Docusaurus | 3000 | Interactive API documentation |
| API Server | REST API | 4000 | Backend API |
| Database | PostgreSQL | 5432 | Data storage |
Running Locally
docker compose up -d
open http://localhost:3000
open http://localhost:3000/scalar
Connecting SDK
import { OpenAPI } from '@scp/sdk';
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
| Component | Technology | Port | Purpose |
|---|
| Load Balancer | Lightsail LB | 443 | SSL termination, routing, health checks |
| Static Server | nginx | 80 | Static files (mirrors CloudFront in prod) |
| Web Server | NestJS | 3000 | SSR + API |
| Database | PostgreSQL | 5432 | Data storage |
Cost
~$38/month ($20 instance + $18 load balancer). Includes free managed SSL certificates.
Connecting to Iteration Stack
import { OpenAPI } from '@scp/sdk';
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
| Component | IaC Tool | Purpose |
|---|
| CloudFront Distribution | CloudFormation | Global CDN, edge caching |
| CloudFront Function | CloudFormation | URL routing logic |
| S3 Static Assets | CloudFormation | Static files (CSS, JS, images) |
| Application Load Balancer | Terraform | OIDC authentication, TLS termination |
| ECS Fargate (SSR) | Terraform | Remix server-side rendering |
| ECS Fargate (API) | Terraform | REST API server |
| Aurora PostgreSQL | Terraform | Primary database |
| KMS | Terraform | Encryption key management |
| Secrets Manager | Terraform | API keys, credentials |
| Keycloak | Terraform | Identity 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:
| Header | Content |
|---|
x-amzn-oidc-identity | User ID (sub claim) |
x-amzn-oidc-data | Base64-encoded JWT with all claims |
x-amzn-oidc-accesstoken | Access token for API calls |
RBAC Roles
| Role | Description | Scopes |
|---|
platform_admin | Full platform access | All tenants, all merchants |
merchant_admin | Merchant organization admin | All merchants in org |
merchant_staff | Day-to-day operations | Single merchant |
end_customer | Customer with account | Write appointment data, own appointments |
end_customer_guest | Guest customer | Write-only access to current appointment |
CloudFront Configuration
URL Routing
Cache Policies
| Path Pattern | Origin | Cache TTL | Headers Forwarded |
|---|
/static/* | S3 | 1 year | None |
/scp/* | ALB | No cache | All (Cookie, Auth) |
/api/* | ALB | No cache | All (Cookie, Auth) |
/* (default) | S3 | 1 day | None |
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
| Layer | Method |
|---|
| At Rest | KMS for database, S3, EBS volumes |
| In Transit | TLS 1.3 for all external connections |
| Secrets | Secrets 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
| Resource | Inbound | Outbound |
|---|
| ALB | 443 from 0.0.0.0/0 | ECS SG on 3000, 4000 |
| ECS SSR | 3000 from ALB SG | API SG, Internet |
| ECS API | 4000 from ALB SG, SSR SG | Aurora SG, KMS, Internet |
| Aurora | 5432 from ECS SG | None |
User Synchronization
The platform syncs local user records with Keycloak using webhooks:
| Event | Webhook | Action |
|---|
| User Created | user.created | Create local record |
| User Updated | user.updated | Sync email, name, roles |
| User Deleted | user.deleted | Soft delete |
| Role Changed | user.role_updated | Update roles |
Design Decisions
| Decision | Rationale |
|---|
| CloudFormation for Edge | CloudFront + S3 tightly coupled |
| Terraform for Backend | Better state management for ECS, ALB, RDS |
| ALB + Fargate for SSR | No cold starts, native streaming, built-in OIDC |
| ALB Native OIDC | Zero custom auth code |
| ECS Fargate over EC2 | Serverless, no patching |
| Aurora Serverless v2 | Auto-scaling, pay-per-use |
| Keycloak over IDP | Full control, customizable, multi-tenant |