# How I work

A short map of the setup behind this repo, because the process says as much
as the code.

## The environment

Everything was built over SSH from a laptop (I was house-sitting for most
of it) against my home server, a Debian box that runs my self-hosted
infrastructure. The server carries the whole toolchain: uv and node for
fast local feedback, Docker for the deliverable, and the deployment stack
below. No cloud dev environment involved.

## Source control and CI

- Origin is my self-hosted Forgejo instance, with a push mirror to GitHub;
  the repo you are reading is the mirror and shows the same history and
  the same green CI.
- CI runs on every push: ruff, mypy and pytest for the backend; typecheck,
  lint, build and vitest for the frontend. It has been green since the
  first commit.

## Deployment

- The hosted instance is a single container on the same server, built from
  this repo's Dockerfile and managed with Komodo (a self-hosted container
  control plane). It is rebuilt from main as the build advances.
- Routing and TLS come from caddy-docker-proxy: the container carries its
  route as labels, Caddy picks them up. The streaming endpoint needed one
  deliberate setting there (no response buffering), verified through the
  public URL.
- HTTP basic auth sits at the edge because the instance runs against my
  personal Spotify account.

## AI-assisted building

I work with coding agents, and this project was built that way end to end:

- One orchestrating session (Claude Code harness) holds the plan and the
  state. It briefs implementation agents (codex CLI, Opus 5 subagents) that
  build scoped tracks in their own git worktrees, in parallel.
- Contracts come first: the API schemas and the event protocol were frozen
  before frontend and backend lanes ran in parallel against them.
- Parallel lanes buy time where it matters. While I was working on the
  backend, a separate lane generated a ready-to-implement UI (design
  tokens, component structure, copy) against the frozen event protocol, so
  frontend implementation started from a settled design instead of a blank
  page.
- Everything that lands is reviewed by me, commit by commit, in my editor
  before it goes in. Voice-carrying text (this file, the README, the
  logboek) I write or rewrite myself.
- Verification against the real APIs is deliberate and budgeted: the
  Spotify development quota is a daily account-level budget, so live test
  runs are planned, sequential and measured rather than sprayed.
- Review also runs as a tool: adversarial review passes over the diffs
  produced findings that became fix batches; the useful findings and the
  rejected ones are both traceable in the logboek.

The result is that implementation is cheap and parallel, while design,
review and verification stay serial and human. The logboek
([logboek.md](logboek.md)) records that rhythm as it happened, including
what was dropped under time pressure.
