Architecture Overview

DocuStack is a HIPAA-compliant document processing platform built on AWS with a focus on security, cost optimization, and operational simplicity.

System Components

┌─────────────────────────────────────────────────────────────────┐
│                        DocuStack Platform                        │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │   Web App   │  │  Slack Bot  │  │    Temporal Workflows   │  │
│  │  (Next.js)  │  │ (ECS/Farg.) │  │     (ECS/Fargate)       │  │
│  └──────┬──────┘  └──────┬──────┘  └───────────┬─────────────┘  │
│         │                │                     │                 │
│         └────────────────┼─────────────────────┘                 │
│                          │                                       │
│  ┌───────────────────────┴───────────────────────────────────┐  │
│  │                    VPC (HIPAA-Compliant)                   │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐    │  │
│  │  │   Public    │  │   Private   │  │    Database     │    │  │
│  │  │   Subnets   │  │   Subnets   │  │    Subnets      │    │  │
│  │  │  (ALB/NLB)  │  │ (ECS Tasks) │  │  (RDS/Aurora)   │    │  │
│  │  └─────────────┘  └─────────────┘  └─────────────────┘    │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Repository Structure

DocuStack follows the Gruntwork two-repository pattern:

Repository	Purpose
docustack-mono	Application code (frontend, backend, Lambdas)
docustack-infrastructure-modules	Reusable Terraform modules
docustack-infrastructure-live	Environment-specific configurations

Why This Pattern?

1. Separation of concerns: Infrastructure modules are versioned independently
2. Reusability: Modules can be used across environments with different configs
3. Safety: Changes to modules don't automatically affect production
4. Auditability: Clear version history for infrastructure changes

Key Architectural Decisions

Lambda Code Location

Lambda function code lives in docustack-mono/services/lambdas/, not in the infrastructure modules. This follows the principle:

• Modules define HOW to deploy (Terraform resources)
• Application code defines WHAT to deploy (Lambda function code)

See Lambda Code Location for the full ADR.

Cost Optimization

• Fargate Spot: 70% cost reduction for non-critical workloads
• Nightly Scheduler: Automatic stop/start of dev resources
• On-demand Bastion: No always-on bastion hosts

HIPAA Compliance

All infrastructure is designed for HIPAA compliance:

• Encryption at rest and in transit
• VPC endpoints for AWS services (no public internet)
• Audit logging via CloudTrail
• AWS Config conformance pack

Infrastructure Layers

Deployment follows a strict dependency order:

Layer	Components	Dependencies
0	Bootstrap (S3, DynamoDB)	None
1	VPC, GitHub OIDC	Bootstrap
2	ECR, ECS Cluster, RDS	VPC
3	Bastion, IP Whitelist, Nightly Scheduler	VPC, ECS
4	DB Init Lambda, Temporal	RDS, ECS
5	Slack Bot, Orchestrators	All above

Architecture Documentation

Document	Description
Lambda Code Location	ADR: Why Lambda code lives in the monorepo
Multi-Account Strategy	AWS Organizations structure and SCPs
Terraform State Strategy	Per-account state storage for security

Related

• Compliance Overview - HIPAA, SOC 2, and security requirements
• Technical Controls - AWS Config, encryption, network security