Software Architecture Documentation

Software Architecture Documentation

Good architecture documentation answers the questions that code cannot: why decisions were made, what the system is supposed to be, and when things changed and why. It serves new joiners, future maintainers, incident responders, and the architects themselves (writing forces clarity).

Why Document Architecture

The four jobs documentation does:

1. Onboarding — A new developer understands the system without reading every file. The first week is productive, not disorienting.
2. Decision memory — When a decision is documented with its rationale, it is not relitigated in every meeting. "We considered MongoDB; see ADR-004."
3. Drift detection — Architecture degrades silently. Comparing docs to code catches drift before it becomes a crisis.
4. Design tool — Writing about an architecture exposes gaps that diagrams hide. If you cannot write it clearly, the design is unclear.

What documentation is not:

• A substitute for good code
• A deliverable produced at the end of a project (write it while you design)
• Something that lives in Confluence and is never updated

Arc42 — Structured Architecture Documentation

Arc42 provides 12 sections. Use all 12 for large systems; use the Lean Core (6 sections) for most projects.

Arc42 Sections
─────────────────────────────────────────────────────────────────
 1. Introduction and Goals
 2. Constraints
 3. System Scope and Context          ← Lean Core
 4. Solution Strategy                 ← Lean Core
 5. Building Block View               ← Lean Core
 6. Runtime View                      ← Lean Core
 7. Deployment View
 8. Cross-cutting Concepts
 9. Architecture Decisions            ← Lean Core (ADR index)
10. Quality Requirements              ← Lean Core
11. Risks and Technical Debt
12. Glossary
─────────────────────────────────────────────────────────────────
Lean Core covers ~80% of what teams need.

Section Descriptions

1. Introduction and Goals

## 1. Introduction and Goals

### System Purpose
The E-Commerce Platform enables customers to browse products,
place orders, and track deliveries. It handles 10,000 orders/day
at peak season.

### Top 3 Quality Goals
| Priority | Quality | Scenario |
|---|---|---|
| 1 | Reliability | Order placement succeeds under 500 concurrent users |
| 2 | Modifiability | Adding a payment provider takes < 2 days |
| 3 | Security | No PII appears in logs or error responses |

### Stakeholders
| Role | Name | Interest |
|---|---|---|
| Product Owner | Ana Costa | Feature roadmap, business rules |
| Lead Developer | João Silva | Technical decisions, implementation |
| DevOps | Maria Santos | Deployment, SLOs, on-call |
| Legal | — | GDPR compliance, data residency |

2. Constraints

• Technical: "Must run on AWS", "PostgreSQL only (DBA team constraint)", "Java 21 LTS"
• Organizational: "Team of 4 developers", "3-month deadline", "No third-party SaaS for PII"
• Regulatory: "LGPD compliance", "PCI-DSS for payment flows"

Constraints limit your design space. Document them so future architects know what they cannot change and why.

3. System Scope and Context C4 Level 1 diagram + table of external interfaces:

## 3. System Scope and Context

[C4 Context diagram here — see c4-model skill]

### External Interfaces
| System | Direction | Protocol | Data | Owner |
|---|---|---|---|---|
| Stripe | Outbound | REST/HTTPS | Payment intent, webhook | Finance |
| SendGrid | Outbound | SMTP/HTTPS | Order emails | Marketing |
| FedEx API | Outbound | REST/HTTPS | Shipping labels, tracking | Logistics |
| ERP System | Inbound | Kafka | Inventory updates | IT Ops |

4. Solution Strategy A short narrative (1-2 pages) explaining the key technical decisions and their rationale:

## 4. Solution Strategy

**Architectural style:** Event-driven microservices decomposed by bounded context (Order, Catalog, Inventory, Notification). Services communicate asynchronously via Kafka for resilience; synchronous REST only for user-facing flows where latency matters.

**Why not a monolith first:** The team is 4 developers, 3 of whom are backend-focused and own separate domains. Domain boundaries are well understood from 2 years of operating the legacy system. A monolith would create merge conflicts on the shared schema daily.

**Database strategy:** Each service owns its database (no shared schema). PostgreSQL for transactional services; Redis for session and catalog cache; no event sourcing in phase 1.

**Key trade-off:** Eventual consistency across services. Accepted because order confirmation can tolerate 2-second email delay. Real-time inventory sync is not required by the business (see ADR-003).

5. Building Block View C4 Container diagram (Level 2) + optional Component diagrams (Level 3) for complex containers.

## 5. Building Block View

### Level 2 — Containers
[C4 Container diagram here]

### Level 3 — Order API Components
[C4 Component diagram here — only for Order API; it contains the most complex logic]

### Responsibility Matrix
| Container | Responsibility | Team |
|---|---|---|
| Order API | Order lifecycle, cart, checkout | Backend Team |
| Catalog Service | Products, search, pricing | Backend Team |
| Notification Worker | Emails, push notifications | Backend Team |
| React SPA | Customer storefront | Frontend Team |
| Admin Dashboard | Warehouse UI | Frontend Team |

6. Runtime View Sequence diagrams for the 3-5 most important scenarios:

• Happy path order placement
• Payment failure and retry
• Inventory sync from ERP
• Shipment notification flow

7. Deployment View Infrastructure diagram: AWS regions, AZs, EKS cluster topology, RDS configuration, Kafka cluster.

## 7. Deployment View

### Production Environment (AWS ap-southeast-1)

EKS Cluster (3 node groups, t3.xlarge):
  Namespace: ecommerce-prod
    Deployment: order-api          (3 replicas, HPA: 3-10)
    Deployment: catalog-service    (2 replicas)
    Deployment: notification-worker (2 replicas)
    Deployment: react-spa          (2 replicas, served by nginx)

RDS PostgreSQL 16 (db.r6g.xlarge, Multi-AZ):
  order-api-db (primary + read replica)
  catalog-db   (primary + read replica)

MSK (Managed Kafka, 3 brokers):
  Topics: order.placed, order.shipped, inventory.updated

ElastiCache Redis (cache.r6g.large, cluster mode):
  Session store + catalog cache

CloudFront CDN → S3:
  Static assets, product images

8. Cross-cutting Concepts Decisions that apply uniformly across all containers:

## 8. Cross-cutting Concepts

### Logging
- Format: JSON (structured) — every log entry includes traceId, spanId, serviceName
- Library: SLF4J + Logback → CloudWatch Logs
- PII policy: No email addresses, names, or card data in logs. Use customerId (UUID) only.

### Security
- Authentication: JWT (RS256). Public key distributed via JWKS endpoint.
- Authorization: Role claims in JWT. Services validate locally (no network call per request).
- Secrets: AWS Secrets Manager. Rotated every 90 days. No secrets in environment variables.
- TLS: TLS 1.3 enforced on all inter-service calls. mTLS for Kafka.

### Error Handling
- Client errors (4xx): return RFC 7807 Problem Details JSON.
- Server errors (5xx): log full stack trace with traceId; return minimal detail to client.
- Kafka consumer errors: retry 3x with exponential backoff; send to dead-letter topic after 3 failures.

### Observability
- Metrics: Micrometer → Prometheus → Grafana
- Tracing: OpenTelemetry → AWS X-Ray
- Alerting: Alert on p99 latency > 2s for /orders endpoint; error rate > 1%; Kafka consumer lag > 1000

### Dependency Injection
- Spring dependency injection throughout. No static access to ApplicationContext.
- Domain model (com.example.domain) has zero Spring annotations — pure Java.

9. Architecture Decisions Index of ADRs (see ADR section below).

10. Quality Requirements Quality scenarios as acceptance criteria — testable, not vague.

11. Risks and Technical Debt

## 11. Risks and Technical Debt

### Known Risks
| Risk | Probability | Impact | Mitigation |
|---|---|---|---|
| Kafka cluster single-AZ (MSK) | Low | High | Migrate to multi-AZ MSK in Q3 |
| Order API has 3 God Service classes | High | Medium | Refactor using ADR-008 roadmap |
| No load testing above 500 concurrent users | Medium | High | Load test sprint planned for Q2 |

### Accepted Technical Debt
| Item | Accepted By | Repayment Plan |
|---|---|---|
| JPA entities and domain model are same classes | Lead Dev | Separate in Order API v2 (Q4) |
| No integration tests for Kafka consumer | Tech Lead | Add in next sprint |
| Hardcoded Stripe API version | Backend Team | Extract to config in ADR-012 scope |

12. Glossary Define the ubiquitous language — the terms used consistently in code, docs, and conversation:

## 12. Glossary

| Term | Definition |
|---|---|
| Order | A customer's request to purchase one or more products. Has a lifecycle from PENDING to DELIVERED. |
| Line Item | A single product+quantity within an Order. |
| Cart | A transient collection of items before an Order is placed. Not persisted in the Order database. |
| Fulfillment | The warehouse process of picking, packing, and shipping an Order. |
| SKU | Stock Keeping Unit. Unique identifier for a product variant (size, color, etc.). |
| Bounded Context | A DDD concept. Each service owns exactly one bounded context and its terms. |

ADR — Architecture Decision Records

An ADR documents a significant architectural decision: what was decided, why, and what the consequences are. The goal is never to justify a bad decision retroactively — it is to capture the reasoning while it is fresh.

When to write an ADR

Write an ADR when:

• The decision is hard or expensive to reverse
• Significant trade-offs exist between options
• Team members disagreed on the right approach
• The decision will surprise a future developer
• The decision violates a common pattern for a specific reason

Do NOT write an ADR for:

• Trivial library version choices
• Implementation details within a single class
• Decisions that follow obvious best practices

ADR File Naming and Storage

docs/
  adr/
    ADR-001-use-postgresql-over-mongodb.md
    ADR-002-event-driven-inter-service-communication.md
    ADR-003-eventual-consistency-for-inventory.md
    ADR-004-jwt-for-authentication.md
    ...

ADR Template

# ADR-NNN: [Short imperative title]

Date: YYYY-MM-DD
Status: Proposed | Accepted | Deprecated | Superseded by ADR-NNN

## Context

[Describe the situation that requires a decision. What problem are we solving?
What are the constraints? What options did we consider? Keep this factual — no judgments yet.]

## Decision

[State the decision clearly in the first sentence. Then explain the reasoning.
Why this option over the others?]

## Consequences

### Positive
- [Benefit 1]
- [Benefit 2]

### Negative / Trade-offs
- [Cost 1]
- [Cost 2]

### Neutral
- [Observable change that is neither good nor bad]

ADR Example — Full

# ADR-001: Use PostgreSQL over MongoDB for Order Storage

Date: 2025-06-17
Status: Accepted

## Context

We need to persist order data. Orders have complex relationships:
one Order has many LineItems, each LineItem references a Product,
and every Order has a shipping Address. Orders require ACID
transactions: reserving inventory and creating the order record
must succeed or fail together.

We evaluated:
- PostgreSQL 16 (relational, ACID, strong typing)
- MongoDB 7 (document store, flexible schema, horizontal write scaling)

The team has 3 developers with 4+ years of PostgreSQL experience each.
No developer has production MongoDB experience. Expected load is
10,000 orders/day at peak (Black Friday). Write throughput does not
require horizontal scaling in year 1.

## Decision

Use PostgreSQL 16 as the primary store for the Order bounded context.
Use JSONB columns for order metadata fields that may vary by product
category (e.g., digital vs. physical product-specific attributes).

## Consequences

### Positive
- ACID transactions across Order and LineItem entities, eliminating
  a whole class of consistency bugs.
- Complex queries (e.g., "all orders for customer X in date range,
  sorted by total") are efficient with B-tree indexes.
- Team hits the ground running — no learning curve.
- pg_logical replication to read replicas is battle-tested.

### Negative / Trade-offs
- Schema changes require migrations (Flyway). Adding a new field
  means a migration script. MongoDB would not.
- Horizontal write scaling requires Citus, which adds operational
  complexity. Acceptable given projected load.
- JSONB queries for metadata fields are slower than top-level columns
  and less type-safe.

### Neutral
- This decision is scoped to the Order service. Catalog service may
  choose a different database in its own ADR.

ADR — More Examples

# ADR-002: Asynchronous Inter-Service Communication via Kafka

Date: 2025-06-17
Status: Accepted

## Context
Order API, Inventory Service, and Notification Worker need to share
state changes. We evaluated synchronous REST calls vs. asynchronous
messaging via Kafka.

REST: simple to implement, but creates temporal coupling. If
Notification Worker is down, Order API's HTTP call fails, and the
order might not be placed. Requires circuit breakers and retry logic
in every producer.

Kafka: decoupled, resilient. Producer does not wait for consumer.
Events are persisted and replayed if a consumer restarts.
Adds operational overhead: Kafka cluster management.

## Decision
Services communicate state changes via Kafka domain events.
Synchronous REST is used only for customer-facing request/response
flows where the customer is waiting for a response.

Event naming convention: `{context}.{entity}.{past-tense-verb}`
Examples: `order.order.placed`, `inventory.stock.reserved`

## Consequences

### Positive
- Services are independently deployable and scalable.
- Notification Worker downtime does not affect order placement.
- Event log provides an audit trail.
- New consumers can replay historical events.

### Negative / Trade-offs
- Eventual consistency: inventory count in the Order API is stale
  until the Kafka event is consumed. Acceptable per business rules
  (see ADR-003).
- Operational overhead: Kafka cluster must be monitored, backed up.
  Mitigated by using AWS MSK (managed).
- Debugging asynchronous flows is harder than synchronous chains.
  Mitigated by distributed tracing (OpenTelemetry).

ADR Tools

# adr-tools (bash CLI): https://github.com/npryce/adr-tools
brew install adr-tools        # macOS
adr init docs/adr             # initialize ADR directory
adr new "Use PostgreSQL over MongoDB"    # creates ADR-001-...md
adr new -s 1 "Migrate to CockroachDB"   # supersedes ADR-001

# Log4brains: renders ADRs as a browsable HTML site
npx log4brains init
npx log4brains adr new "Use event sourcing for audit log"
npx log4brains preview        # local HTML view
npx log4brains build          # static site for deployment

Fitness Functions — Living Architecture

Fitness functions are executable tests that encode architecture rules. They run in CI on every PR. Architecture violations become build failures, not yearly audit findings.

The Problem They Solve

Without fitness functions:

Day 1:  "Domain classes must not depend on Spring."
Day 90: Developers add @Transactional to a domain class.
Day 180: The rule is forgotten.
Day 365: Architecture review finds 30 violations.

With fitness functions:

Day 90: Developer adds @Transactional to a domain class.
        CI fails. PR is blocked. Violation fixed before merge.

ArchUnit (Java / Kotlin)

// src/test/java/ArchitectureTests.java

@AnalyzeClasses(packages = "com.example")
public class ArchitectureTests {

    // Domain layer must not depend on Spring
    @ArchTest
    static final ArchRule domainMustNotDependOnSpring =
        noClasses()
            .that().resideInAPackage("..domain..")
            .should().dependOnClassesThat()
            .resideInAPackage("org.springframework..")
            .because("Domain model must be framework-independent for testability");

    // Application layer must not depend on Infrastructure layer
    @ArchTest
    static final ArchRule applicationMustNotDependOnInfrastructure =
        noClasses()
            .that().resideInAPackage("..application..")
            .should().dependOnClassesThat()
            .resideInAPackage("..infrastructure..")
            .because("Application layer depends on ports (interfaces), not adapters");

    // Controllers must only call Use Cases, not Repositories directly
    @ArchTest
    static final ArchRule controllersMustNotCallRepositories =
        noClasses()
            .that().resideInAPackage("..interfaces..")
            .should().dependOnClassesThat()
            .resideInAPackage("..infrastructure.persistence..")
            .because("Controllers talk to use cases, not persistence adapters directly");

    // Use Cases must not depend on HTTP-specific classes
    @ArchTest
    static final ArchRule useCasesMustNotDependOnHttp =
        noClasses()
            .that().resideInAPackage("..application..")
            .should().dependOnClassesThat()
            .resideInAPackage("javax.servlet..")
            .orShould().dependOnClassesThat()
            .resideInAPackage("org.springframework.web..");

    // Detect cyclic dependencies between packages
    @ArchTest
    static final ArchRule noCyclicDependencies =
        slices().matching("com.example.(*)..").should().beFreeOfCycles();
}

Dependency Cruiser (JavaScript / TypeScript)

// .dependency-cruiser.js
module.exports = {
  forbidden: [
    {
      name: "no-circular",
      severity: "error",
      comment: "Circular dependencies make refactoring impossible",
      from: {},
      to: { circular: true }
    },
    {
      name: "domain-no-infrastructure",
      severity: "error",
      comment: "Domain must not import from infrastructure",
      from: { path: "^src/domain" },
      to: { path: "^src/infrastructure" }
    },
    {
      name: "no-node-modules-in-domain",
      severity: "error",
      comment: "Domain layer must be framework-free",
      from: { path: "^src/domain" },
      to: { dependencyTypes: ["npm"] }
    }
  ],
  options: {
    doNotFollow: { path: "node_modules" },
    tsConfig: { fileName: "tsconfig.json" }
  }
};

# Run in CI
npx depcruise --validate .dependency-cruiser.js src

Python — Custom Import Checker

# tests/test_architecture.py
import ast
import os
import pytest

def get_imports(filepath):
    with open(filepath) as f:
        tree = ast.parse(f.read())
    imports = []
    for node in ast.walk(tree):
        if isinstance(node, ast.Import):
            imports.extend(alias.name for alias in node.names)
        elif isinstance(node, ast.ImportFrom):
            if node.module:
                imports.append(node.module)
    return imports

def find_python_files(directory):
    for root, _, files in os.walk(directory):
        for file in files:
            if file.endswith('.py'):
                yield os.path.join(root, file)

def test_domain_has_no_infrastructure_imports():
    """Domain layer must not import from infrastructure."""
    violations = []
    for filepath in find_python_files('src/domain'):
        imports = get_imports(filepath)
        for imp in imports:
            if 'infrastructure' in imp or 'sqlalchemy' in imp or 'redis' in imp:
                violations.append(f"{filepath}: imports {imp}")
    assert not violations, f"Domain layer has infrastructure imports:\n" + "\n".join(violations)

def test_no_circular_imports():
    """No circular imports between modules."""
    # Use import-linter or pydeps for production use
    pass

CI Integration

# .github/workflows/architecture.yml
name: Architecture Tests

on: [pull_request]

jobs:
  arch-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          java-version: '21'
      - name: Run ArchUnit tests
        run: ./mvnw test -pl order-api -Dtest=ArchitectureTests
      - name: Run Dependency Cruiser
        run: npx depcruise --validate .dependency-cruiser.js src

Documentation as Code

The principle: docs live in the same repository as the code they describe. They are versioned, reviewed in PRs, and updated when the code changes.

Directory Structure

project-root/
  docs/
    architecture/
      arc42.md                    ← Arc42 main document
      diagrams/
        context.puml              ← PlantUML source
        context.png               ← Generated in CI
        containers.puml
        containers.png
        order-api-components.puml
        order-api-components.png
      workspace.dsl               ← Structurizr DSL (generates all views)
    adr/
      ADR-001-use-postgresql.md
      ADR-002-kafka-events.md
      ADR-003-eventual-consistency.md
      README.md                   ← ADR index
    runbooks/
      incident-response.md
      deployment-checklist.md

CI: Generate Diagrams from Source

# .github/workflows/docs.yml
name: Generate Architecture Diagrams

on:
  push:
    paths:
      - 'docs/architecture/diagrams/**/*.puml'

jobs:
  generate-diagrams:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate PlantUML diagrams
        uses: cloudbees/plantuml-github-action@master
        with:
          args: -tpng docs/architecture/diagrams/*.puml
      - name: Commit generated PNGs
        run: |
          git config user.email "ci@example.com"
          git config user.name "CI Bot"
          git add docs/architecture/diagrams/*.png
          git diff --staged --quiet || git commit -m "ci: regenerate architecture diagrams"
          git push

Structurizr CI Push

# Publish to Structurizr cloud on every merge to main
structurizr-cli push \
  --id $STRUCTURIZR_WORKSPACE_ID \
  --key $STRUCTURIZR_API_KEY \
  --secret $STRUCTURIZR_API_SECRET \
  --workspace docs/architecture/workspace.dsl

Quality Attribute Scenarios (ISO 25010)

Vague quality goals are untestable. Quality scenarios make them concrete and actionable.

Template:

Given [stimulus source] sends [stimulus]
to [artifact] under [environment conditions],
the system responds with [response]
measured by [response measure].

Scenario Examples

Performance (Efficiency)

Stimulus source: 500 concurrent customers
Stimulus:        POST /orders (checkout)
Artifact:        Order API
Environment:     Normal operating conditions, Black Friday peak
Response:        Order is created and confirmation returned
Measure:         95th percentile response time ≤ 2 seconds;
                 0 order data loss

Availability

Stimulus source: AWS us-east-1 AZ failure
Stimulus:        AZ-A becomes unavailable
Artifact:        Production EKS cluster
Environment:     Peak traffic (500 req/sec)
Response:        System continues serving requests from AZ-B and AZ-C
Measure:         < 30 seconds of elevated errors during failover;
                 0 data loss; RTO ≤ 30 minutes for full recovery

Modifiability

Stimulus source: Business decision
Stimulus:        Add PayPal as a payment provider
Artifact:        Order API (payment integration)
Environment:     Normal development, full test coverage required
Response:        New payment provider is available in production
Measure:         ≤ 2 developer days; ≤ 5 files modified;
                 no changes required to Order domain model

Security

Stimulus source: Malicious external actor
Stimulus:        Requests /api/orders/12345 without auth token
Artifact:        Order API
Environment:     Production
Response:        Request is rejected; no order data returned
Measure:         HTTP 401 returned in < 100ms;
                 no stack trace or internal paths in response body;
                 failed attempt logged with IP and timestamp

Testability

Stimulus source: Developer
Stimulus:        Runs unit test suite for Order domain
Artifact:        com.example.domain package
Environment:     Local machine, no database, no Kafka, no network
Response:        All domain tests pass
Measure:         Test suite completes in < 5 seconds;
                 0 test infrastructure dependencies

Quality Tree

Quality Goals for E-Commerce Platform
│
├── Reliability (Priority 1)
│   ├── Availability: 99.9% uptime; RTO < 30 min
│   ├── Fault tolerance: Single service failure does not cascade
│   └── Data integrity: No order data loss under any failure scenario
│
├── Performance (Priority 2)
│   ├── Throughput: 500 concurrent checkouts
│   ├── Latency: p95 < 2s for order placement
│   └── Scalability: HPA scales Order API 3→10 replicas under load
│
├── Modifiability (Priority 3)
│   ├── Payment provider: < 2 days to add new provider
│   ├── Bounded context isolation: services deployable independently
│   └── Domain purity: domain model has no framework dependencies
│
├── Security (Priority 4)
│   ├── No PII in logs or error responses
│   ├── All inter-service traffic TLS 1.3
│   └── Secrets rotated every 90 days via AWS Secrets Manager
│
└── Observability (Priority 5)
    ├── Every request traceable end-to-end via traceId
    ├── Alert on p99 latency > 2s within 1 minute
    └── Dead-letter queue monitored; alert on > 0 messages

Anti-Patterns

Documentation Sprint Checklist

For a new system or major component, produce the Lean Core Arc42 in this order:

• Arc42 §1: Introduction — purpose, top 3 quality goals, stakeholder table
• Arc42 §3: System context — C4 Level 1 diagram + external interfaces table
• Arc42 §4: Solution strategy — 1-2 page narrative of key decisions and trade-offs
• Arc42 §5: Building block view — C4 Level 2 diagram; Level 3 for complex containers
• Arc42 §6: Runtime view — sequence diagrams for 3 key scenarios
• Arc42 §9: ADR index — at least 3 ADRs for the most significant decisions
• Arc42 §10: Quality requirements — quality tree + 5 testable scenarios
• Fitness functions — ArchUnit or equivalent encoding top 3 architecture rules
• Glossary — define 10-15 ubiquitous language terms

Time budget for Lean Core on a medium system: 2-3 developer days. Return: saves 2-3 weeks per year in re-explaining decisions, onboarding, and rework from architecture drift.