Skip to content

[v0.2.0] One-page architecture doc #72

Description

@neverDefined

Problem

A drive-by contributor opening anvil.go (760+ lines, all public API + lifecycle + builder) has no map of how the pieces fit. CLAUDE.md captures conventions but doesn't explain what's where.

Proposal

Add docs/architecture.md — one page, no fluff. Sections:

  1. One-paragraph mental model — anvil is a subprocess; we own its lifecycle and expose a Go-typed RPC client.
  2. Lifecycle diagram (ASCII): Build()Start()[ready]Stop()/Close(). Where the cancel context lives. Where sync.Once kicks in.
  3. File map — what each .go file is responsible for (mirror the table in CLAUDE.md but with one-sentence summaries).
  4. RPC method anatomy — annotated copy of the canonical wrapper showing rpcCalls.Add, CallContext, error wrap, log.
  5. Test strategy — shared-anvil pattern, when to use setupTestAnvil instead, the unit-test httptest pattern.
  6. Where to add new things — RPC wrapper → anvil.go + tests; new builder option → builder section + validate(); new helper → helpers.go.

Acceptance criteria

  • One page, scannable in 60 seconds.
  • Linked from CONTRIBUTING.md and CLAUDE.md.
  • No diagrams that need rendering — ASCII or none.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:docsREADME, godoc, examples, contributingtype:choreHousekeeping, no user-visible change

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions