Architecture Decision Records (ADRs)¶
This directory records the significant architecture and design decisions for anvil-serving — the context, the options weighed, the decision, and its consequences — so the why survives the people and the chat logs.
Convention¶
- One file per decision:
NNNN-short-kebab-title.md(zero-padded, sequential —0001,0002, …). - Format: Context → Considered options → Decision → Consequences. Start from
template.md. - Status:
Proposed·Accepted·Deferred·Superseded by ADR-NNNN. - Never delete an ADR — supersede it. A reversed decision is itself history; write a new ADR that
supersedes the old one and mark the old one
Superseded. - When to write one: any non-trivial, hard-to-reverse, or cross-cutting decision — a product contract, a routing/auth model, a dependency, a protocol or wire-format choice, a security posture.
- New ADR: copy
template.md→ next number, fill it in, link related ADRs/issues, and add it to the index below.
Index¶
| # | Title | Status |
|---|---|---|
| 0001 | Cloud cost & subscription auth — why anvil should not relay cloud | Accepted |
| 0002 | Model serves are Docker-Compose-defined | Accepted |
| 0003 | Portable-by-default: out-of-box router correctness and a generated bring-up | Accepted |
| 0004 | Router as a service: containerized, network-facing, token-authed | Accepted |
| 0005 | anvil-503 native-failover loop: OpenClaw's fallback walk does not escape a providerOverride |
Accepted |
| 0006 | Multiplexer swaps drain in-flight requests before evicting the resident model | Accepted |
| 0007 | Subscription-auth cloud tier: feasible via claude CLI subprocess — opt-in only, text-only classes, no tool broker |
Accepted |
| 0008 | Heavy tier enables NEXTN speculative decoding (self-speculation, no draft model) | Accepted |
| 0009 | Measured quality-profile write-back loop (offline-batch-first, fingerprint-keyed) | Accepted |
| 0010 | Specialized-engine tier: run any model on any engine (config-first, RelayBackend-served) | Accepted |
| 0011 | Two modes of operation: agentic vs maximum-flexibility (global mode switch) | Accepted |
| 0012 | Serve & router management flows through anvil-serving verbs; deployed router config is a mutable volume promoted via validate→atomic-write→reload→rollback | Accepted |