hatch-surf/docs/engineering/hatch-architecture.md

Hatch Architecture

Living document. The CTO sketches the component map; the engineer owns the details as the code lands.

One-sentence summary

Hatch is a single Go binary that serves a server-rendered HTML UI and captures, inspects, and mocks HTTP requests against per-endpoint URLs, persisting everything in a single SQLite file.

High-level component map

                        ┌─────────────────────────────────────┐
                        │  Browser (Hatch UI)                │
                        │  GET /e/{id}  +  EventSource /events│
                        └──────────────┬──────────────────────┘
                                       │ HTTP / SSE
                                       ▼
┌──────────────────────────────────────────────────────────────┐
│                     hatch (Go binary)                         │
│                                                              │
│  ┌──────────────┐   ┌────────────────┐   ┌───────────────┐   │
│  │  http.ServeMux│──▶│ handler layer  │──▶│  store layer  │   │
│  │  (stdlib)    │   │ (internal/     │   │  (internal/   │   │
│  │              │   │  handler/)     │   │   store/)     │   │
│  └──────────────┘   └────────────────┘   └───────┬───────┘   │
│         │                                        │           │
│         │             ┌────────────────┐          │           │
│         └────────────▶│  SSE hub       │◀─────────┘           │
│                       │  (broadcast    │                      │
│                       │   new requests)│                      │
│                       └────────┬───────┘                      │
│                                │                              │
│                       ┌────────▼───────┐                      │
│                       │ html/template  │                      │
│                       │ (server-render)│                      │
│                       └────────────────┘                      │
└──────────────────────────────┬───────────────────────────────┘
                               │ modernc.org/sqlite (pure Go)
                               ▼
                        ┌──────────────┐
                        │  hatch.db    │
                        │  (SQLite)    │
                        └──────────────┘

Layer responsibilities

cmd/hatch/main.go — process entrypoint

• Reads configuration (env: PORT).
• Wires the http.ServeMux to the handler layer.
• Starts http.ListenAndServe. Logs to stdout. Crashes on bind failure.

internal/handler/ — HTTP layer

• One file per route group: capture.go, inspect.go, mock.go, sse.go, health.go.
• Handlers take a store.Repository (interface) — never a concrete type — so tests can swap in :memory: SQLite or a fake.
• Handlers translate HTTP ↔ store calls. They do not contain business logic.
• Server-rendered HTML lives next to the handler that renders it. Templates are //go:embed-ed at build time.

internal/store/ — persistence layer

• schema.sql is the canonical DDL. Applied idempotently on first start by migrate.go.
• models.go defines the Go structs (Endpoint, Request).
• repository.go defines the Repository interface. The HTTP layer depends on this interface, not on the SQLite implementation.
• sqlite_repo.go is the concrete implementation. Uses modernc.org/sqlite (pure Go, no CGO).
• db.go opens the database file (or :memory: for tests), configures pragmas, returns a *sql.DB.

SSE hub (in internal/handler/sse.go)

• A goroutine per connected browser, holding an http.Flusher.
• A chan store.Request that capture handlers publish to.
• The hub fans out new requests to all subscribers for the relevant endpoint.
• No external broker. No Redis. No pubsub library. A chan and a map[endpointID][]chan is the entire implementation for v0.1.

Request lifecycle

1. Capture — a webhook hits /{endpoint-id} (any method). The capture handler:
   • Reads method, path, query, headers, body.
   • Calls store.AppendRequest(ctx, request).
   • Publishes the new request to the SSE hub.
   • Looks up the endpoint's mock response and returns it.
2. Inspect — a browser hits GET /e/{endpoint-id}. The inspect handler:
   • Calls store.ListRequests(ctx, endpointID, limit=100).
   • Renders an HTML page with the request list (newest first).
   • The page includes a small vanilla-JS EventSource client that subscribes to /e/{endpoint-id}/events.
3. Live update — the SSE handler holds the connection open, flushes each new request as a data: frame, and the browser appends it to the list.
4. Mock — PUT /e/{endpoint-id}/mock accepts {status, headers, body} and updates the endpoint. Subsequent captures to that endpoint return the configured response.

Data model

Two tables. That's it for v0.1.

endpoints
  id           TEXT PRIMARY KEY      -- URL-safe random ID, e.g. "h7c2k"
  created_at   INTEGER NOT NULL      -- Unix epoch seconds, UTC
  mock_status  INTEGER               -- nullable; 200/201/204/etc.
  mock_headers TEXT                  -- JSON object, nullable
  mock_body    BLOB                  -- nullable

requests
  id           INTEGER PRIMARY KEY AUTOINCREMENT
  endpoint_id  TEXT NOT NULL REFERENCES endpoints(id)
  received_at  INTEGER NOT NULL      -- Unix epoch seconds, UTC
  method       TEXT NOT NULL
  path         TEXT NOT NULL         -- request path within the endpoint
  query        TEXT NOT NULL         -- raw query string
  headers      TEXT NOT NULL         -- JSON object
  body         BLOB                  -- nullable
  remote_addr  TEXT                  -- for debugging
  FOREIGN KEY (endpoint_id) REFERENCES endpoints(id) ON DELETE CASCADE

Index on requests(endpoint_id, received_at DESC) for the list page query.

Boundaries

• No authentication. v0.1 is single-user, self-hosted. If you can reach the port, you can read and write. See v0.1-scope.md.
• No multi-tenancy. One SQLite file, one process, one operator. Cloud is v0.2+.
• No external services. No Redis, no Postgres, no S3. If the binary needs to phone home, the design is wrong.
• No client-side framework. The browser gets HTML and a 50-line events.js. Anything more is out of scope for v0.1.

Performance budget

v0.1 is sized for a single developer self-hosting on a $5 VPS:

• Cold start: under 100 ms (Go binary + SQLite open).
• Capture latency: under 5 ms p99 on the happy path (no auth, no remote calls).
• SSE fan-out: one goroutine per connected browser, no message broker.
• Database size: comfortable to 100k requests per endpoint. Retention policy is out of scope for v0.1.

If a real workload breaks these, we measure first, then add complexity.

Future seams (do not build now)

These are deliberate extension points, not planned features. The v0.1 implementation should not block them but also should not build them.

• Pluggable storage — the Repository interface is the seam. A Postgres or S3-backed implementation would slot in without handler changes.
• Pluggable auth — a middleware in front of the mux. The v0.1 mux is exposed without auth, which is the right v0.1 default.
• Replay / forwarding — the Request struct has the full request. Replay is "read from store, write back out." Forwarding is the same plus a destination.
• Multi-tenant cloud — partitioning by endpoint_id is already first-class. A tenant_id column is a v0.2 change.

When the v0.1 design cannot accommodate one of these without a rewrite, we have under-designed. When the v0.1 design has built one of these speculatively, we have over-designed.