Family Todo App

A family task-management app with an unusual split:

• Parents administer everything by talking to an AI agent (Claude, ChatGPT, …) through an MCP server — there is no traditional admin UI.
• Children only ever check off their own tasks in a deliberately locked-down kiosk view on a shared tablet — no login, no settings, no distractions.

See app-description.md for the full product rationale.

This is an npm-workspaces monorepo. Two runtime services share a single SQLite database file:

AI agent ──OAuth2/JSON-RPC──▶ mcp ──┐
                                     ├─▶ @family-todo/db ──▶ app.db (SQLite, WAL)
browser ──▶ oauth2-proxy ──▶ frontend ┘
            (ZITADEL OIDC)

Authentication

• The frontend runs behind an oauth2-proxy gatekeeper (OIDC via ZITADEL). The proxy injects a trusted X-Forwarded-Email header; the Astro middleware trusts it and upserts the user into SQLite. There is no in-app password handling.
• The MCP server is its own OAuth 2.0 authorization server for AI clients (dynamic client registration, PKCE, JWT access tokens signed RS256).

Data — a single SQLite file (DB_PATH, default ./data/app.db) in WAL mode, shared by the frontend and the MCP server on one volume.

packages/
  db/        # @family-todo/db   — SQLite data layer: migrations/ + raw-SQL modules
  frontend/  # @family-todo/frontend — Astro SSR (kiosk + admin)
  mcp/       # @family-todo/mcp   — MCP server (Express, OAuth2/JWT)
  docs/      # @family-todo/docs  — documentation site (Shipyard)
deploy/      # Kubernetes (Kustomize) production overlay, deployed by Flux
.github/workflows/ci.yml  # test every workspace; build & push frontend/mcp images

• Node.js 22+
• npm 10+ (workspaces)

No database server to install — SQLite is embedded via better-sqlite3.

git clone https://github.com/levino/todo-app
cd todo-app
npm install

npm run dev

This starts the frontend (http://localhost:4321) and the MCP server (http://localhost:3001) together, both pointed at a local SQLite file at ./data/app.db.

You can also run a single workspace:

npm run dev -w @family-todo/frontend
npm run dev -w @family-todo/mcp
npm run dev -w @family-todo/docs

Note on auth in local dev: the frontend expects an oauth2-proxy in front of it that injects an X-Forwarded-Email header. Without one, protected pages redirect to /login. For UI work, put a proxy in front (see deploy/overlays/production for the real config) or send the header yourself. The MCP server can be called directly during development with a ?token=<userId> query parameter — see packages/mcp.

All tests run in-process against in-memory SQLite — no Docker, no external services.

npm test                       # every workspace (matches CI)
npm run test:db                # @family-todo/db
npm run test:mcp               # @family-todo/mcp
npm run test:frontend          # @family-todo/frontend

Test-Driven Development is required — see .claude/CLAUDE.md.

Playwright E2E specs live in packages/frontend/tests/e2e but currently assume the old setup and are not run in CI; they need rewiring to the SQLite/oauth2-proxy stack before use.

The schema lives in packages/db/migrations as numbered NNN_description.sql files, applied in order on first connection and tracked in a schema_migrations table.

To change the schema, add a new migration file and cover it with a test in packages/db/src/*.test.ts. Never edit a migration that has already been applied. Following the project's "one page → one SQL view" rule, page-specific read models (e.g. tasks_page_view) are defined as SQL views inside these migrations.

packages/db/scripts/migrate-from-pocketbase.ts is a one-off importer kept for history — the app no longer uses PocketBase.

npm run build   # builds @family-todo/db, then frontend and mcp

Production runs on Kubernetes; manifests are in deploy/overlays/production (Kustomize) and are applied by Flux. A single pod runs oauth2-proxy + frontend + mcp sharing one SQLite PVC. Because better-sqlite3 needs a single writer, the deployment uses one replica with a Recreate strategy.

CI (.github/workflows/ci.yml) tests every workspace, then on pushes to main builds and pushes ghcr.io/levino/todo-app-frontend and ghcr.io/levino/todo-app-mcp (native arm64). Flux pulls :latest and rolls out.

MIT