fog/docs/adr/README.md

# Architecture Decision Records

This directory contains ADRs for Fog Expedition — durable records of architectural choices, why they were made, and what trade-offs they imply.

## Format

We use [MADR](https://adr.github.io/madr/) (Markdown ADR) format. Each record has:

- **Status** — proposed, accepted, deprecated, or superseded
- **Context and problem statement** — what situation forced a decision
- **Decision drivers** — the factors that mattered
- **Considered options** — what we looked at
- **Decision outcome** — what we chose and why
- **Consequences** — what this means going forward, good and bad

## Index

| # | Title | Status |
|---|-------|--------|
| [0001](./0001-twitch-extension-type.md) | Twitch Video Overlay over Panel extension | Accepted |
| [0002](./0002-nx-monorepo-with-strict-boundaries.md) | Nx monorepo with enforced module boundaries | Accepted |
| [0003](./0003-mixed-test-runners.md) | Vitest in libs and overlay, Jest in API | Accepted |
| [0004](./0004-stateless-seeded-encounter-resolver.md) | Encounter resolver as pure library with seeded PRNG | Accepted |
| [0005](./0005-per-mission-jittered-tick-scheduling.md) | Per-mission jittered tick scheduling | Accepted |
| [0006](./0006-postgres-plus-redis-data-split.md) | PostgreSQL for durable state, Redis for ephemeral | Accepted |
| [0007](./0007-devcontainer-with-host-services.md) | Devcontainer with docker-outside-of-docker, services on host | Accepted |
| [0008](./0008-angular-for-overlay-frontend.md) | Angular for the overlay frontend | Accepted |

## When to write a new ADR

Write one when:

- The decision has plausible alternatives that reasonable people might pick differently
- The reasoning will matter six months from now
- The decision shapes how the codebase evolves

Don't write one for:

- Style or convention (those go in `CLAUDE.md`)
- Decisions with one obvious answer (no real choice was made)
- Implementation details that change frequently (those go in code comments)

## Superseding

If a future decision overrides one here, mark the old one's status as `Superseded by ADR-NNNN` and link forward. Don't delete superseded ADRs — the history is the value.