Architecture and dependency maps - the documentation foundation

A clear architecture document is the foundation for operations. This lesson covers what to document and how to maintain it.

What to document

For each service:

• Purpose: what it does and why.
• Components: the parts (processes, databases, caches).
• Dependencies: what it needs (databases, services, DNS).
• Endpoints: what it exposes (URLs, ports, IPs).
• Owners: who is responsible.
• Runbooks: how to operate.
• SLAs: the targets.

Architecture diagram

A good architecture diagram shows:

• Components and their relationships.
• Data flow.
• Dependencies (databases, caches, services).
• External integrations.

Tools:

• Mermaid: text-based, version-controlled, easy to maintain.
• draw.io: free, graphical, library of shapes.
• PlantUML: text-based, integrates with docs.

Mermaid example:

graph LR
  A[Web] --> B[API]
  B --> C[(PostgreSQL)]
  B --> D[(Redis)]
  C --> E[S3 Backups]
  D --> E

A text-based diagram is version-controlled and easy to update. A graphical diagram is more readable but harder to maintain.

Dependency map

A dependency map shows:

• What depends on what.
• The order of failure (if X fails, Y fails).
• The recovery order.

Web Service depends on:
  - PostgreSQL (required)
  - Redis cache (required)
  - S3 (required for backups)
  - DNS (required)
  - NTP (required for time sync)

Failure order:
  - DNS down → service unreachable
  - PostgreSQL down → service degraded
  - Redis down → service degraded
  - S3 down → backups fail

Recovery order:
  - DNS, NTP first
  - PostgreSQL second
  - Redis third
  - S3 last

The dependency map guides incident response.

Architecture review

The architecture is reviewed periodically:

• Quarterly: review the architecture for changes.
• After major incidents: update the architecture based on findings.
• Before major changes: validate the architecture.

The discipline: the architecture document is alive, not a one-time artifact.

Knowledge check