# Deployment Architecture

# Deployment Architecture

> **Project:** {{PROJECT_NAME}}
> **Version:** {{VERSION}}
> **Date:** {{DATE}}
> **Author:** {{AUTHOR}}
> **Status:** Draft | In Review | Approved
> **Reviewers:** {{REVIEWERS}}

## Document History
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 0.1     | {{DATE}} | {{AUTHOR}} | Initial draft |

---

## 1. Overview

<!-- GUIDANCE: Describe the overall deployment architecture in 2-4 sentences. Reference the system it supports and the key architectural decisions made. -->

**System:** {{PROJECT_NAME}}
**Cloud Provider:** {{CLOUD_PROVIDER}} <!-- AWS / Azure / GCP / Hetzner / Multi-cloud -->
**Provider Rationale:** {{RATIONALE}} <!-- Why this provider was chosen: cost, compliance, team expertise, existing contracts -->
**Architecture Pattern:** {{PATTERN}} <!-- Microservices / Monolith / Serverless / Hybrid -->

---

## 2. Infrastructure Topology

<!-- GUIDANCE: Replace the placeholder below with your actual Mermaid diagram. Show all major components, zones, and traffic flows. -->

```mermaid
graph TB
    subgraph Internet
        USER[End Users]
        CDN[CDN / CloudFront]
    end

    subgraph Public Subnet
        ALB[Application Load Balancer]
        BASTION[Bastion Host]
    end

    subgraph Private Subnet - App
        APP1[App Server 1]
        APP2[App Server 2]
    end

    subgraph Private Subnet - Data
        DB_PRIMARY[(Primary DB)]
        DB_REPLICA[(Read Replica)]
        CACHE[Redis Cache]
    end

    subgraph Isolated Subnet
        SECRETS[Secrets Manager]
        BACKUP[Backup Storage]
    end

    USER --> CDN
    CDN --> ALB
    ALB --> APP1
    ALB --> APP2
    APP1 --> DB_PRIMARY
    APP2 --> DB_PRIMARY
    APP1 --> CACHE
    DB_PRIMARY --> DB_REPLICA
    APP1 --> SECRETS
```

---

## 3. Networking Architecture

### 3.1 VPC / VNET Design

<!-- GUIDANCE: Document CIDR ranges, peering, and network segmentation decisions. -->

| Network | CIDR | Purpose |
|---------|------|---------|
| VPC / VNET | {{CIDR_VPC}} | Main network boundary |
| Public Subnet A | {{CIDR_PUB_A}} | Load balancers, NAT gateways |
| Public Subnet B | {{CIDR_PUB_B}} | Load balancers, NAT gateways (AZ-B) |
| Private Subnet A | {{CIDR_PRIV_A}} | Application servers |
| Private Subnet B | {{CIDR_PRIV_B}} | Application servers (AZ-B) |
| Isolated Subnet A | {{CIDR_ISO_A}} | Databases, secrets |
| Isolated Subnet B | {{CIDR_ISO_B}} | Databases, secrets (AZ-B) |

### 3.2 Load Balancer Configuration

<!-- GUIDANCE: Document load balancer type, listener rules, health checks, and SSL termination. -->

| Parameter | Value |
|-----------|-------|
| Type | {{LB_TYPE}} <!-- ALB / NLB / nginx / HAProxy --> |
| Protocol | HTTPS (TLS 1.2+) |
| SSL Termination | At load balancer |
| Health Check Path | {{HEALTH_CHECK_PATH}} |
| Health Check Interval | {{INTERVAL}}s |
| Unhealthy Threshold | {{THRESHOLD}} consecutive failures |
| Idle Timeout | {{TIMEOUT}}s |
| Stickiness | {{STICKINESS}} <!-- Enabled/Disabled --> |

### 3.3 DNS Architecture

<!-- GUIDANCE: Document DNS provider, record types, TTLs, and failover configuration. -->

| Record | Type | Value | TTL |
|--------|------|-------|-----|
| {{DOMAIN}} | A / ALIAS | Load Balancer | {{TTL}} |
| api.{{DOMAIN}} | CNAME | API Load Balancer | {{TTL}} |
| cdn.{{DOMAIN}} | CNAME | CDN Distribution | {{TTL}} |

**DNS Provider:** {{DNS_PROVIDER}}
**Failover Strategy:** {{FAILOVER_STRATEGY}} <!-- Route 53 health checks / Cloudflare failover / Manual -->

### 3.4 CDN Configuration

<!-- GUIDANCE: Document CDN provider, cache behaviors, origin configuration, and edge locations. -->

| Parameter | Value |
|-----------|-------|
| Provider | {{CDN_PROVIDER}} <!-- CloudFront / Cloudflare / Fastly --> |
| Origin | {{CDN_ORIGIN}} |
| Cache Behaviors | Static assets: 1yr, API: no-cache, HTML: 5min |
| HTTPS Only | Yes |
| WAF Integration | {{WAF_INTEGRATION}} |

---

## 4. Compute

### 4.1 Container Orchestration

<!-- GUIDANCE: Document the orchestration platform, cluster configuration, and workload management. -->

**Platform:** {{ORCHESTRATION}} <!-- Kubernetes / ECS / Nomad / None -->

| Component | Configuration | Notes |
|-----------|---------------|-------|
| Cluster | {{CLUSTER_SPEC}} | |
| Node Groups | {{NODE_GROUPS}} | |
| Min Nodes | {{MIN_NODES}} | |
| Max Nodes | {{MAX_NODES}} | |
| Node Size | {{NODE_SIZE}} | |
| Container Registry | {{REGISTRY}} | |

### 4.2 Serverless Functions

<!-- GUIDANCE: List all serverless functions, their triggers, and resource allocations. -->

| Function | Trigger | Memory | Timeout | Purpose |
|----------|---------|--------|---------|---------|
| {{FUNCTION_1}} | {{TRIGGER}} | {{MEMORY}}MB | {{TIMEOUT}}s | {{PURPOSE}} |

<!-- TODO: Add all serverless functions -->

### 4.3 Instance Sizing & Auto-Scaling

<!-- GUIDANCE: Document instance types, auto-scaling policies, and scaling triggers. -->

| Service | Instance Type | Min | Max | Scale Trigger |
|---------|--------------|-----|-----|---------------|
| {{SERVICE}} | {{INSTANCE}} | {{MIN}} | {{MAX}} | CPU > {{CPU}}% for {{DURATION}}min |

**Scale-Out Policy:** {{SCALE_OUT}} <!-- e.g., CPU > 70% for 2 min → add 2 instances -->
**Scale-In Policy:** {{SCALE_IN}} <!-- e.g., CPU < 30% for 10 min → remove 1 instance -->
**Scale-In Cooldown:** {{COOLDOWN}}min

---

## 5. Storage

### 5.1 Database Hosting

<!-- GUIDANCE: Document all databases, hosting type, versions, and connection configuration. -->

| Database | Engine | Version | Hosting | Instance | Storage | HA |
|----------|--------|---------|---------|----------|---------|-----|
| {{DB_NAME}} | {{ENGINE}} | {{VERSION}} | {{HOSTING}} | {{INSTANCE}} | {{STORAGE}}GB | {{HA}} |

**Connection Pooling:** {{POOL_TOOL}} <!-- PgBouncer / RDS Proxy / Application-level -->
**Max Connections:** {{MAX_CONN}}
**Connection String:** Stored in {{SECRET_LOCATION}} (never hardcoded)

### 5.2 Object Storage

<!-- GUIDANCE: Document S3/Blob/GCS buckets, their purposes, access policies, and lifecycle rules. -->

| Bucket / Container | Purpose | Access | Lifecycle | Encryption |
|-------------------|---------|--------|-----------|------------|
| {{BUCKET_NAME}} | {{PURPOSE}} | {{ACCESS}} | {{LIFECYCLE}} | AES-256 |

### 5.3 File Storage

<!-- GUIDANCE: Document any shared file systems (EFS, NFS, Azure Files) and their mount configurations. -->

| Storage | Type | Mount Point | Purpose | Size |
|---------|------|-------------|---------|------|
| {{STORAGE_NAME}} | {{TYPE}} | {{MOUNT}} | {{PURPOSE}} | {{SIZE}}GB |

---

## 6. Security

### 6.1 Network Security Groups / Firewall Rules

<!-- GUIDANCE: Document inbound/outbound rules for each security group. Follow least privilege. -->

| Security Group | Direction | Port | Protocol | Source / Destination | Purpose |
|---------------|-----------|------|----------|---------------------|---------|
| sg-alb | Inbound | 443 | TCP | 0.0.0.0/0 | HTTPS from internet |
| sg-alb | Outbound | {{APP_PORT}} | TCP | sg-app | Forward to app |
| sg-app | Inbound | {{APP_PORT}} | TCP | sg-alb | From load balancer |
| sg-app | Outbound | {{DB_PORT}} | TCP | sg-db | Database access |
| sg-db | Inbound | {{DB_PORT}} | TCP | sg-app | From application only |

### 6.2 WAF Configuration

<!-- GUIDANCE: Document WAF rules, managed rule groups, and custom rules. -->

**WAF Provider:** {{WAF_PROVIDER}}

| Rule Group | Purpose | Action |
|------------|---------|--------|
| AWSManagedRulesCommonRuleSet | OWASP Top 10 | Block |
| AWSManagedRulesSQLiRuleSet | SQL injection | Block |
| AWSManagedRulesKnownBadInputsRuleSet | Known bad inputs | Block |
| Rate limiting | {{RATE_LIMIT}} req/5min per IP | Count → Block |

### 6.3 Secrets Management

<!-- GUIDANCE: Document where secrets are stored, rotation schedules, and access patterns. -->

**Secret Store:** {{SECRET_STORE}} <!-- AWS Secrets Manager / Vault / Azure Key Vault -->

| Secret | Rotation Schedule | Access |
|--------|------------------|--------|
| Database credentials | 90 days | App role only |
| API keys (third-party) | On compromise | App role only |
| TLS certificates | 60 days before expiry | Deploy role only |
| JWT signing key | 365 days | Auth service only |

### 6.4 IAM Roles & Policies

<!-- GUIDANCE: Document IAM roles, their trust relationships, and key permissions. Follow least privilege. -->

| Role | Trusted By | Key Permissions | Purpose |
|------|------------|-----------------|---------|
| {{APP_ROLE}} | EC2 / ECS Task | SecretsManager:GetSecret, S3:GetObject | Application runtime |
| {{DEPLOY_ROLE}} | CI/CD | ECR:PushImage, ECS:UpdateService | Deployments |
| {{BACKUP_ROLE}} | Lambda / Cron | RDS:CreateSnapshot, S3:PutObject | Backups |

---

## 7. Cost Estimation

<!-- GUIDANCE: Provide monthly cost estimates per component. Use current cloud pricing for your region. -->

| Component | Service | Spec | Est. Monthly Cost |
|-----------|---------|------|-------------------|
| Compute | {{SERVICE}} | {{SPEC}} | ${{COST}} |
| Database | {{SERVICE}} | {{SPEC}} | ${{COST}} |
| Load Balancer | {{SERVICE}} | {{SPEC}} | ${{COST}} |
| CDN | {{SERVICE}} | {{TRAFFIC}}GB transfer | ${{COST}} |
| Storage | {{SERVICE}} | {{CAPACITY}}GB | ${{COST}} |
| Monitoring | {{SERVICE}} | {{METRICS}} metrics | ${{COST}} |
| **Total** | | | **${{TOTAL}}** |

**Cost Optimization Notes:**
- <!-- TODO: List any reserved instances, savings plans, or spot instance usage -->
- <!-- TODO: Note any unused resources scheduled for cleanup -->

---

## 8. High Availability Design

<!-- GUIDANCE: Document HA configuration, failover mechanisms, and recovery targets. -->

| Component | HA Strategy | Failover Time | Notes |
|-----------|-------------|--------------|-------|
| Application | Multi-AZ, N+1 instances | Immediate (ELB health check) | |
| Database | Multi-AZ with auto-failover | 60-120 seconds | DNS propagation |
| Cache | Cluster mode / Replication | 30 seconds | Redis Sentinel |
| CDN | Global edge network | Transparent | Provider HA |

**RTO Target:** {{RTO}} minutes
**RPO Target:** {{RPO}} minutes

---

## 9. Multi-Region Considerations

<!-- GUIDANCE: Document if/how multi-region is implemented. If single-region, document the decision rationale. -->

**Current:** {{REGION_STRATEGY}} <!-- Single-region / Active-Active / Active-Passive -->
**Primary Region:** {{PRIMARY_REGION}}
**Secondary Region:** {{SECONDARY_REGION}} <!-- or "N/A — single region" -->

**Rationale:** {{MULTI_REGION_RATIONALE}}
<!-- e.g., "Single region — GDPR data residency requirement, cost-benefit analysis favors backup-based recovery" -->

**Data Replication:** {{REPLICATION_STRATEGY}} <!-- Cross-region replication / None -->
**Failover Procedure:** See [disaster-recovery-plan.md](./disaster-recovery-plan.md)

---

## 10. Related Documents

- [CI/CD Pipeline](./cicd-pipeline.md)
- [Environment Configuration](./environment-configuration.md)
- [Infrastructure as Code](./infrastructure-as-code.md)
- [Monitoring & Observability](./monitoring-observability.md)
- [Disaster Recovery Plan](./disaster-recovery-plan.md)

---

## Approval
| Role | Name | Date | Signature |
|------|------|------|-----------|
| Author | | | |
| Reviewer | | | |
| Approver | | | |