Agentic Live Music Calendar

A browsable, consolidated live music calendar for Minneapolis/St. Paul. Scheduled AI agents read each venue's own calendar page once a day, extract the listed shows with a local open-weight model, validate and reconcile them against what is already stored, and a Next.js frontend renders the result.

It is also a learning project: agent orchestration, validation of agentic output, auditability, plus Python and React/Next.js. It is built with Claude Code under Ari's direction, with Ari writing the core logic at selected key points of interest. Focus is on local and indie acts and smaller venues that national listing sites miss.

About the Owner

Ari Koinuma is a software engineering leader based in St. Paul, Minnesota. He spent 15 years delivering software for enterprise clients, most recently as a Director of Software Engineering at a Big 4 consulting firm. He is also a freelance musician on the side and wanted a live music calendar that covers the small rooms and local artists. He defines the requirements, makes the architecture decisions across all layers, sets the accuracy standards and directs Claude Code.

This application is intentionally built robustly: audit trails, accuracy gates and tests that fail loudly. That discipline is the point: it applies enterprise-style delivery practice (audit trails, accuracy gates, tests that fail loudly) to an agentic system. Other metro areas are possible later, once the Twin Cities version works.

License

PolyForm Noncommercial 1.0.0. You may read, run and learn from this code for noncommercial purposes. Commercial use needs Ari's written permission. Reviewing the code as part of a hiring evaluation is welcome.

Status

Building Alpha currently, not yet deployed. Last update: Oct 15, 2026

How it fits together

Piece	Path	Role
Calendar	apps/calendar	Public Next.js app. The only thing the browser talks to. Server Components call the API server-to-server
API	apps/api/app	FastAPI service: reads and writes calendar data, serves /docs
Agent worker	apps/api/agent_worker	Daily fetch → extract → validate → reconcile → commit pipeline (LangGraph)
Postgres	Docker locally, Neon hosted	Canonical calendar data and the append-only audit trail
Shared UI	packages/ui	@repo/ui, shadcn components used by the calendar

The architecture is documented in docs/arch/:

• project-overview.md: the problem, and what the system must do
• requirements-initial.md: each screen, and the agent's rules for extraction, validation and reconciliation
• arch-initial.md: how it is built and why, including hosting, the agent pipeline and the audit trail
• data-model-initial.md: the Postgres schema

The full documentation map, with the implementation logs for each milestone, is in AGENTS.md and docs/dev/.

Running it locally

make setup   # first time only: install deps, start Postgres, migrate, seed
make dev     # Postgres + FastAPI (:8000) + Next.js (:3000) together; Ctrl-C stops them
make check   # everything CI runs — do this before calling something done
make e2e     # just the Playwright end-to-end tests (builds the app, starts its own API and Next on other ports)

make help lists every target. One file isn't created for you: the calendar needs apps/calendar/.env.local (git-ignored) containing

API_BASE_URL=http://localhost:8000

Open http://localhost:3000. The API's own browsable docs are at http://localhost:8000/docs.

Commands you'll use most:

make types            # regenerate apps/calendar/lib/api-types.ts after changing app/schemas.py
make migration m="…"  # autogenerate an Alembic migration
make db-shell         # psql against local Postgres

Don't hand-edit apps/calendar/lib/api-types.ts or apps/calendar/lib/fixtures/. Both are generated from apps/api/app/schemas.py and app/testing/sample_data.py, and make contract-check (part of make check) fails if they are stale.

When something looks wrong

The browser never talks to the API. The Next.js server does (the pages are Server Components that run on it), then sends back finished HTML. So the browser's Network tab shows only the page itself and one ?_rsc= fetch per filter change; the API calls are invisible there. Look in these places instead, in order. The first three need no debugger.

#	Question	Where to look
1	Did Next get the right URL?	The address bar, and the GET /?venue=3 200 in … line in the Next terminal
2	What did Next ask the API for, and what came back?	The Next terminal: one [api] GET /shows?venue_id=3 -> 200 in 41ms line per API call, then a one-line summary of the response, e.g. body (2.0 KB): 6 shows (…); 0 without start_time; 0 with empty lineup; …. Null fields are listed at the end of the summary
3	What does the API itself return?	Skip the UI: curl -s 'localhost:8000/shows?venue_id=3' | jq, or open http://localhost:8000/docs and use "Try it out" for a collapsible JSON tree. The uvicorn terminal has one access-log line per call
4	The data is right but the page is wrong	It's the Next code. Use the debugger (below), or a console.log in a Server Component, which prints in the Next terminal, not the browser

See the full response JSON. The summary is the default so logs stay short and searchable. To log each response body in full, on one line (cut at 4000 characters), add this to apps/calendar/.env.local and restart the Next.js server:

LOG_API_BODIES=1

It is ignored in production builds: hosted logs get summaries only. Remove the line (or set it to 0) to turn it off.

Step through the code. .vscode/launch.json has debug configs for the API, the Next.js server and the browser. Stop make dev first (they use the same ports), then pick Full stack: API + Next.js server in VS Code's Run and Debug panel.

JavaScript and TypeScript tasks (Turborepo)

Turborepo runs the JS/TS side of the repo. The Python API has its own tooling (uv, ruff, mypy, pytest) and sits outside the Turborepo pipeline.

pnpm build                                   # build all JS/TS apps and packages
pnpm exec turbo dev --filter=calendar        # run only the calendar app's dev server
pnpm exec turbo lint                         # lint every JS/TS package

Shared configuration lives in packages/eslint-config and packages/typescript-config. Tooling: TypeScript for type checking, ESLint for linting, Prettier for formatting (pnpm format).

Conventions

Read AGENTS.md. The short version:

• Comments explain why, not just what. Each module opens with a docstring saying what it is.
• Every change ends with make check passing.
• Design decisions are written down in docs/arch/ and docs/dev/notes.md. Check there before proposing an approach.

Not accepting pull requests at this time.

Useful links

• Turborepo: tasks and filtering
• Next.js documentation
• FastAPI documentation