Architecture documentation

Based on this meeting transcript (a design review, system deep-dive,
or architectural deep-dive), produce a system design document. Be
technically rigorous. Do not invent design choices that weren't
discussed. Where the meeting was vague, write "To be specified" and
add the question to the open-questions section.

Audience: engineering — current team and engineers joining the system
later.

No emojis. Length 1500–3000 words.

Format:

# SDD: {System / Feature Name}
**Status:** Draft / Under Review / Accepted
**Author:** {Name}
**Reviewers:** {Names}
**Source discussion(s):** {Meeting name(s) — date(s)}
**Created:** {date}
**Last updated:** {date}
**Related:** {ADR numbers, related SDDs, PRDs that motivated this}

## Summary
Two to four sentences. What this design covers and the headline approach.

## Context and motivation
Two to four paragraphs.
- The problem this system addresses
- The current state and its limitations
- The trigger for designing this now
- What this design unlocks

## Goals and non-goals
**Goals:**
- {Specific outcome the design must achieve}

**Non-goals:**
- {What this design explicitly does NOT address — to bound scope}

## High-level architecture
A diagram (Mermaid in-doc, or referenced from a separate tool). For
each major component:

### {Component name}
- **Purpose:** what this component does
- **Responsibility:** what it owns
- **Dependencies:** what it depends on (upstream)
- **Consumers:** what depends on it (downstream)
- **State:** stateful / stateless; if stateful, what state and where

## Data flow
How data moves through the system. Reference a sequence diagram if
the flow is complex.

## Data model
Key entities and their relationships. Link to schema definitions
rather than inlining if schemas are large.

## API surface
External-facing interfaces. Or reference a separate integration doc
(Template D) if substantial.

## Non-functional requirements
- **Performance:** target latency, throughput, scaling
- **Reliability:** SLOs, failure modes, recovery
- **Security:** authentication, authorization, data protection
- **Cost:** infrastructure estimates, optimization considerations
- **Observability:** logging, metrics, tracing requirements
- **Compliance:** any regulatory considerations

## Alternatives considered
For each material alternative discussed:

### Alternative: {name}
- **Approach:** description
- **Pros:** from the discussion
- **Cons:** from the discussion
- **Rejected because:** specific reasoning

## Migration / rollout plan
- Phasing, feature flags, backward compatibility, rollback

## Testing strategy
- Unit, integration, load, manual / exploratory

## Risks
- **Risk:** description — likelihood / impact — mitigation

## Open questions
- {Question} — owner — target resolution

## Decisions deferred
Choices that don't need to be made now but will:
- {Decision} — when it needs to be made — what would trigger it

## Glossary
Terms specific to this design.

## References
- Related ADRs
- Related SDDs
- Code locations
- External references

Based on this meeting transcript where an architectural decision was
made, produce an ADR following the MADR (Markdown ADR) pattern. Be
specific about what was decided, why, and what alternatives were
rejected. Future engineers reading this should understand the
trade-offs the team considered.

Format:

# ADR-{NNNN}: {Short, specific title — verb-led}

**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXXX
**Date:** {decision date}
**Authors:** {names}
**Reviewers / approvers:** {names}
**Source discussion:** {Meeting name — date}
**Related ADRs:** {list}

## Context
What's the situation? Why do we need to make this decision now?

Two to four paragraphs. Specific. Include:
- The forces at play (technical, business, organizational)
- Constraints we're operating within
- What's at stake — what happens if we choose well vs. poorly

## Decision
We will {verb-led decision statement, specific and unambiguous}.

Two to four sentences elaborating: what specifically is being adopted?
How will it be implemented? Scope of the decision?

## Consequences

**Positive:**
- {Specific outcome we expect}

**Negative:**
- {Specific cost or constraint we're accepting}

**Neutral / mixed:**
- {Trade-offs that aren't clearly good or bad}

## Alternatives considered

### {Alternative 1 name}
- **What it was:** one to two sentences
- **Why considered:** the appeal of this option
- **Why rejected:** the specific reasoning that distinguished it from
  the chosen path

### {Alternative 2 name}
[Same structure]

### Doing nothing / status quo
(Always include this one explicitly.)
- **Why considered:** the appeal of not changing
- **Why rejected:** why we needed to act

## Implementation notes
- {Specific implementation guidance}

## Risks and mitigations
- **Risk:** description — **Mitigation:** approach

## Validation
How we'll know if this decision turns out to have been right:
- {Specific signal we'll watch for}
- {Specific metric or behavior}
- **When to revisit:** trigger or timeline

## References
- Code locations where this decision is materialized
- Related ADRs
- External references (docs, papers, prior art)

Based on this meeting transcript (a technical deep-dive, debugging
session, or system explanation), produce a sequence or data flow
document. The goal is to make a specific flow concrete enough that
an engineer unfamiliar with the system could trace it.

Format:

# {Flow Name}: How {X} Happens
**Status:** Current as of {date}
**Last verified:** {date}
**Author:** {name}
**Source discussion:** {Meeting name}
**Related SDD:** {link}

## What this flow does
One to two sentences. The flow's purpose; user-visible outcome if any.

## When this flow runs
- **Trigger:** what initiates it
- **Frequency:** how often it runs
- **Variants:** common variations and when each applies

## Participants
Components / services / systems involved:
- **{Component}:** its role in this flow

## High-level sequence
Mermaid sequence diagram (the model produces this directly from the
discussion):

```mermaid
sequenceDiagram
    participant A as {Component A}
    participant B as {Component B}
    participant C as {Component C}
    A->>B: {request / message}
    B->>C: {lookup / call}
    C-->>B: {response}
    B-->>A: {response}
\```

## Step-by-step detail

### Step 1: {Component A receives X}
- **Input:** what arrives, including format and source
- **What happens:** specific operations
- **Validation:** any checks performed
- **Output:** what gets passed on, to where
- **Failure modes:** what can go wrong, how it's handled

### Step 2: {Next step}
[Same structure]

## Data shapes
The structure of key data at each stage:
- At {stage}: structure or schema reference

## Alternative paths
- If {condition}: how the flow differs
- If {error condition}: error handling and recovery

## Timing characteristics
- Total latency (typical)
- Bottleneck: where time is most spent
- Variability: what affects timing

## Observability
- **Logs:** where to look, what to filter for
- **Metrics:** relevant dashboards or queries
- **Traces:** trace patterns specific to this flow

## Common debugging scenarios
- **Symptom:** observable problem → **Likely cause** → **How to verify**

## Recent changes
| Date | What changed | Why | Author |

Based on this meeting transcript (an integration design discussion
or API design session), produce an integration / API design document.
The document defines the contract between systems; both sides should
be able to implement against it.

Format:

# Integration: {System A} ↔ {System B} — {Purpose}
**Status:** Proposed / Accepted / Deprecated
**Version:** v1.0
**Authors:** {from both teams ideally}
**Reviewers / approvers:** {tech leads from both sides}
**Source discussion:** {Meeting name}

## Purpose
Two to three sentences. What this integration enables.

## Scope
- **In scope:** what this integration covers
- **Out of scope:** what it doesn't

## High-level architecture
- Direction(s) of data flow: A→B, B→A, or bidirectional
- Synchronous or asynchronous (and why)
- Authentication model: how the systems authenticate to each other
- Diagram: reference or inline

## The contract

### {Endpoint / Topic / Method Name}
- **Owner:** which side owns the contract
- **Operation:** HTTP method / queue topic / gRPC method
- **Purpose:** what this operation does
- **Request:** schema or example; required fields; validation rules
- **Response:** schema or example; success cases; error responses with
  codes, structure, and when each occurs
- **Idempotency:** is this operation idempotent? If yes, how?
- **Authentication / authorization:** requirements
- **Rate limits:** if applicable
- **SLOs:** target latency, availability

[Repeat for each endpoint / operation]

## Semantic notes
Anything about the contract that isn't obvious from the schema:
- {Semantic}: clarification

## Versioning and compatibility
- **Versioning scheme:** how versions are identified
- **Breaking changes policy:** what counts as breaking; how handled
- **Deprecation timeline:** how long old versions are supported
- **Backward compatibility commitments:** what's promised

## Error handling
- Retry policy: recommended retries, backoff
- Failure modes: what each side does when the other fails
- Circuit breakers: if applicable

## Observability
- Tracing: trace context propagation
- Logging: what each side logs at the boundary
- Metrics: SLI metrics relevant to the contract

## Security considerations
- Data classification: what data crosses the boundary
- Encryption: in-transit, at-rest
- PII handling: if applicable
- Audit trail: what's logged for compliance

## Operational considerations
- Deployment coordination: how changes are rolled out across both sides
- Incident response: who's responsible when integration breaks
- Onboarding new consumers / producers: process

## Open questions
- {Question requiring resolution before implementation}

## References
- Related contracts
- Implementing services on each side
- Code locations

// See ADR-0042 for the rationale behind this retry behavior