Architecture Documenter

# ADR-0015: Use PostgreSQL as Primary Database

## Status

Accepted (2025-01-15)

Supersedes: ADR-0003 (Use MongoDB)

## Context

We need a persistent data store for our product catalog and order management
system. The data has strong relational characteristics (products belong to
categories, orders contain line items, users have addresses). We expect:

- 10M+ product records
- 50K+ orders per day
- Complex queries joining 3-5 tables
- Strong consistency requirements for financial data
- Full-text search on product names and descriptions

We evaluated: PostgreSQL, MySQL, MongoDB, and CockroachDB.

# ... (condensed) ...
- If we exceed 1TB of data, we may need to evaluate sharding strategies
  or move to a distributed database. We will re-evaluate at 500GB.

## Follow-Up Actions
- [ ] Set up PostgreSQL 16 in staging environment
- [ ] Create database migration pipeline with Flyway
- [ ] Establish backup and point-in-time recovery procedures
- [ ] Document connection pooling strategy (PgBouncer)

ADR States:
├── Proposed → Under discussion, not yet decided
├── Accepted → Decision made, implementation proceeding
├── Deprecated → No longer applies but was once valid
├── Superseded → Replaced by a newer ADR (link to replacement)
└── Rejected → Considered but not adopted (document why)

File Naming: docs/adr/XXXX-title-with-dashes.md
  Example: docs/adr/0015-use-postgresql-as-primary-database.md

Index File: docs/adr/README.md
  - List all ADRs with status, date, and one-line summary
  - Group by domain (data, infrastructure, frontend, etc.)

Write an ADR when:
├── Choosing a technology (database, framework, cloud provider)
├── Selecting an architecture pattern (microservices, CQRS, event sourcing)
├── Making a trade-off (consistency vs. availability, build vs. buy)
├── Establishing a standard (API style, error format, auth mechanism)
├── Changing a previous decision (must supersede the old ADR)
└── Making a decision that future team members will question

Do NOT write an ADR for:
├── Implementation details that can change without impact
├── Coding style preferences (use a linter config instead)
├── Trivial decisions with obvious answers
└── Temporary decisions (use a TODO or ticket instead)

C4 Model Levels:
Level 1: System Context  → "What is this system and who uses it?"
Level 2: Container        → "What are the major building blocks?"
Level 3: Component         → "What is inside each container?"
Level 4: Code              → "How is a component implemented?" (rarely needed)

Key Principle: Each level zooms in on the previous level.
Audience shifts from business stakeholders (L1) to developers (L4).

System Context Diagram Template (as code using Structurizr DSL):

workspace {
    model {
        customer = person "Customer" "A user who browses and purchases products"
        admin = person "Admin" "Internal staff who manage the product catalog"

        productSystem = softwareSystem "Product Catalog System" "Manages product listings, search, and inventory" {
            tags "Primary"
        }

        paymentGateway = softwareSystem "Payment Gateway" "Processes credit card payments" {
            tags "External"
        }
        emailService = softwareSystem "Email Service" "Sends transactional emails" {
            tags "External"
        }
        analytics = softwareSystem "Analytics Platform" "Tracks user behavior" {
            tags "External"
        }

        customer -> productSystem "Browses products, places orders"
        admin -> productSystem "Manages catalog and inventory"
        productSystem -> paymentGateway "Processes payments" "HTTPS/REST"
        productSystem -> emailService "Sends order confirmations" "SMTP"
        productSystem -> analytics "Sends events" "HTTPS"
    }

    views {
        systemContext productSystem "SystemContext" {
            include *
            autoLayout
        }
    }
}

Container Diagram Elements:

┌───────────────── Product Catalog System ─────────────────┐
│                                                           │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────────┐   │
│  │  Web App  │  │ Mobile   │  │   Admin Dashboard    │   │
│  │  (React)  │  │ App (RN) │  │   (React + Vite)     │   │
│  └────┬─────┘  └────┬─────┘  └──────────┬───────────┘   │
│       │              │                    │               │
│       └──────────────┼────────────────────┘               │
│                      │                                    │
│                      ▼                                    │
│              ┌──────────────┐                             │
│              │  API Gateway │                             │
│              │   (Kong)     │                             │
│              └──────┬───────┘                             │
│                     │                                     │
│         ┌───────────┼───────────┐                        │
│         ▼           ▼           ▼                        │
│  ┌────────────┐ ┌─────────┐ ┌──────────┐               │
│  │  Product   │ │  Order  │ │  User    │               │
│  │  Service   │ │ Service │ │ Service  │               │
# ... (condensed) ...
│  │(products)│  │ (orders) │ │ (users)  │               │
│  └──────────┘  └──────────┘ └──────────┘               │
│                                                          │
│  ┌──────────────┐  ┌──────────────┐                     │
│  │    Redis      │  │  RabbitMQ    │                     │
│  │   (cache)     │  │  (events)    │                     │
│  └──────────────┘  └──────────────┘                     │
└──────────────────────────────────────────────────────────┘

## Order Placement Flow

\```mermaid
sequenceDiagram
    actor Customer
    participant Web as Web App
    participant API as API Gateway
    participant Order as Order Service
    participant Product as Product Service
    participant Payment as Payment Gateway
    participant Email as Email Service

    Customer->>Web: Click "Place Order"
    Web->>API: POST /orders
    API->>Order: Create order
    Order->>Product: Check inventory
    Product-->>Order: Inventory confirmed

    Order->>Payment: Charge card
    Payment-->>Order: Payment successful

    Order->>Product: Decrement inventory
    Order->>Email: Send confirmation
    Email-->>Customer: Order confirmation email

    Order-->>API: Order created (201)
    API-->>Web: Order response
    Web-->>Customer: Show confirmation page
\```

Use sequence diagrams for:
├── Multi-service request flows (API calls across microservices)
├── Authentication/authorization flows (OAuth, JWT refresh)
├── Error handling flows (what happens when service X fails?)
├── Async workflows (event-driven processes)
└── Third-party integration flows (payment, shipping, etc.)

Keep diagrams focused:
├── Maximum 6-8 participants per diagram
├── Maximum 15-20 interactions per diagram
├── Split complex flows into sub-diagrams
└── Name the diagram after the scenario, not the system

## Deployment Architecture

### Production Environment

\```
┌─────────────────── AWS us-east-1 ───────────────────────┐
│                                                          │
│  ┌─── VPC 10.0.0.0/16 ────────────────────────────┐    │
│  │                                                  │    │
│  │  ┌─── Public Subnet ──────┐                     │    │
│  │  │  ALB (Application       │                     │    │
│  │  │  Load Balancer)         │                     │    │
│  │  │  ├── HTTPS:443          │                     │    │
│  │  │  └── WAF attached       │                     │    │
│  │  └─────────┬───────────────┘                     │    │
│  │            │                                      │    │
│  │  ┌─── Private Subnet ─────────────────────────┐  │    │
│  │  │                                             │  │    │
│  │  │  ECS Fargate Cluster                        │  │    │
│  │  │  ├── Product Service (3 tasks, 512MB)       │  │    │
│  │  │  ├── Order Service (3 tasks, 1GB)           │  │    │
│  │  │  └── User Service (2 tasks, 512MB)          │  │    │
# ... (condensed) ...
| Aspect | Development | Staging | Production |
|--------|------------|---------|------------|
| Compute | Docker Compose | ECS (1 task each) | ECS (2-5 tasks each) |
| Database | PostgreSQL 16 (local) | RDS db.t3.medium | RDS db.r6g.xlarge (Multi-AZ) |
| Cache | Redis (local) | ElastiCache (1 node) | ElastiCache (3 nodes) |
| CDN | None | CloudFront | CloudFront |
| Monitoring | Console logs | CloudWatch | CloudWatch + Datadog |
| Cost | $0 | ~$500/mo | ~$3,500/mo |

# Technology Radar - Q1 2025

## Adopt (Use in production with confidence)

| Technology | Category | Notes |
|-----------|----------|-------|
| TypeScript 5.x | Language | Standard for all new services |
| PostgreSQL 16 | Database | Primary relational store |
| React 19 | Frontend | Web application framework |
| GitHub Actions | CI/CD | All pipelines migrated |
| Terraform | Infrastructure | IaC standard |

## Trial (Use in non-critical projects to gain experience)

| Technology | Category | Notes |
|-----------|----------|-------|
| Bun | Runtime | Evaluate for build tooling |
| Drizzle ORM | Database | Evaluate vs. Prisma |
| htmx | Frontend | Evaluate for admin tools |
| OpenTelemetry | Observability | Pilot in one service |

## Assess (Research and prototype, not production yet)
# ... (condensed) ...
## Hold (Do not start new projects with these)

| Technology | Category | Notes |
|-----------|----------|-------|
| MongoDB | Database | Migrating away; poor fit for relational data |
| Express.js | Framework | Replaced by Fastify for new services |
| Jenkins | CI/CD | Fully replaced by GitHub Actions |
| Webpack | Bundler | Replaced by Vite |

# Architectural Fitness Functions

Automated checks that verify the system conforms to architectural decisions.

## Dependency Rules

**Rule**: Domain layer must not depend on infrastructure layer.

\```python
# ArchUnit-style test (Python with import-linter)
# .importlinter config
[importlinter:contract:domain-independence]
name = Domain must not import from infrastructure
type = forbidden
source_modules =
    app.domain
forbidden_modules =
    app.infrastructure
    sqlalchemy
    redis
    httpx
\```
# ... (condensed) ...

**Rule**: Frontend bundle must be under 250KB gzipped.

\```javascript
// webpack-bundle-analyzer or vite-plugin-inspect
// CI check:
// gzip -c dist/assets/*.js | wc -c must be < 256000
\```

docs/
├── adr/
│   ├── README.md              # ADR index
│   ├── 0001-use-typescript.md
│   ├── 0002-microservices.md
│   └── template.md
├── architecture/
│   ├── overview.md            # C4 Level 1 + Level 2
│   ├── data-model.md          # ER diagrams, schema docs
│   ├── deployment.md          # Deployment diagrams
│   └── security.md            # Threat model, auth flows
├── api/
│   └── openapi.yaml           # API specification
├── runbooks/
│   ├── incident-response.md
│   └── database-failover.md
├── onboarding/
│   ├── getting-started.md
│   └── architecture-overview.md
└── diagrams/
    ├── workspace.dsl          # Structurizr workspace
    └── generated/             # Generated diagram images

# .github/workflows/docs.yml
name: Documentation
on:
  push:
    paths: ['docs/**']

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lint Markdown
        run: npx markdownlint-cli docs/**/*.md
      - name: Check links
        run: npx markdown-link-check docs/**/*.md
      - name: Generate diagrams
        run: |
          docker run --rm -v $(pwd):/usr/local/structurizr \
            structurizr/cli export -w docs/diagrams/workspace.dsl -f mermaid
      - name: Build docs site
        run: npx docusaurus build
      - name: Deploy
        if: github.ref == 'refs/heads/main'
        run: npx docusaurus deploy