Test Fixture (Sample Repo)

• Store
• MemoryStore
• UserHandler
• testdata/fixture/cmd/server/main.go::route:/users

Astrolabe cannot write documentation about documentation alone — it needs a real target repository to prove the pipeline end to end. testdata/fixture is that target: a miniature Go web service called miniapi that is deliberately kept small, idiomatic, and complete. It exercises every part of the Astrolabe Overview pipeline — graph extraction, agent writing, verification, and site rendering — against a codebase whose shape is fully known, so regressions in the tooling are easy to spot. The fixture is also what the fixture-based Graph Model & Providers provider (FixtureProvider) serves when running without a real database.

The sample itself is a textbook layered HTTP service. At the bottom sits the persistence contract, Store, an interface for creating, reading, listing, and deleting users that implementations must keep safe for concurrent use Store. The only production implementation is MemoryStore, an in-memory map guarded by a sync.RWMutex, with IDs generated as u-<seq>; its constructor NewMemoryStore returns an empty, ready-to-use store MemoryStore. Because the domain model is just a User struct with ID, Name, and Email, and errors are a single sentinel ErrNotFound, the whole persistence layer fits in one file.

The HTTP layer lives in UserHandler, which holds nothing but a store.Store injected through NewUserHandler UserHandler. Each method maps one endpoint to one store call and translates the two failure modes — bad input and store.ErrNotFound — into appropriate status codes: CreateUser validates that name and email are non-empty before calling the store, and GetUser/DeleteUser use errors.Is to distinguish a missing user (404) from an internal failure (500). This makes the fixture a good test of whether a generated page correctly describes error-handling flows.

Wiring happens in cmd/server/main.go, which constructs the store, wraps it in a handler, and registers four routes on a standard http.ServeMux:

That single line — log.Fatal(http.ListenAndServe(":8080", mux)) — is the entire lifecycle of the server, which is exactly the level of complexity you want in a fixture.

How it works

A request through the fixture follows a short, fully traceable path. main builds a MemoryStore, hands it to NewUserHandler, and mounts the handler's methods on the mux. When POST /users arrives, the handler decodes the JSON body, validates it, and delegates to Store.Create, which assigns a sequential ID under a write lock. Reads take the read lock and copy the map into a fresh slice for List, so callers never observe the internal map. Everything the agent's pages claim about this flow can be checked against roughly a hundred lines of Go.

Relationships

graph LR
    main[`testdata/fixture/cmd/server/main.go`] -->|constructs| MemoryStore
    main -->|wires| UserHandler
    main -->|serves route| route:/users["POST /users"]
    UserHandler -->|delegates to| Store
    MemoryStore -->|implements| Store

Why it matters to astrolabe

The fixture feeds three distinct consumers. The graph providers index its packages, symbols, and routes the same way they would a real repository, so Graph Model & Providers has realistic nodes (Store, UserHandler, routes like POST /users) to serve. The agent then writes wiki pages — like this one — about the fixture, exercising Agent Core and its tooling from Agent Tools & Budget. Finally, Verification (Checker & Review) checks those pages' citations and mermaid diagrams against the real fixture source, which is why the sample's stability matters: any change to line numbers or symbol names here will ripple through verification fixtures and golden tests. Pages rendered from the fixture also flow through Wiki Bundle & Pages, Wiki Search, and the Astro Theme & Site Rendering pipeline before they end up in the built site.

Reference

Generated by astrolabe from commit ecc180b3 (tag 0.4.0).