Phase 0 — Foundation: backend, data model, local auth, frontend, deploy + CI #1

2026-06-06T11:28:42-04:00

justin commented

2026-06-06 11:28:42 -04:00

Phase 0 — Foundation

Stands up the entire Provenance foundation, built in dependency order and verified live on the deployment target end-to-end.

What's included

Backend — FastAPI (async, layered API → service → repository → domain), uv-managed, Postgres + Alembic. Health/readiness probes.
Core data model — 12 tables (User, Tree, TreeMembership, Person, Name, Relationship, Event, Place, PlaceName, Source, Citation, AuditEntry) with UUID keys, timestamps, soft-delete, and uniform tree_id tenant scoping. Qualified relationship edges, dual verbatim/normalized event dates, CHECK constraints. Reversible migration, alembic check clean.
Privacy engine — single read-enforcement point in the service layer (tree role + visibility + per-person override; living-person redaction flagged for Phase 2). Append-only audit log on every write.
Local auth — Argon2id passwords, opaque backend-issued sessions (only hashes stored; Bearer or HttpOnly cookie), email verification + password reset behind pluggable AuthProvider and Mailer interfaces (console mailer in dev, SMTP for operators).
Frontend — Next.js (App Router) + React 19 + TypeScript + Tailwind + shadcn-style UI, with a typed client generated from the backend OpenAPI spec. Auth + tree/person views. Standalone container.
Deploy — one compose stack (Caddy + frontend + backend + Postgres/pgvector + MinIO), twelve-factor .env, Caddy routing /api+/health → backend and / → frontend.
CI — Gitea Actions building backend + frontend images to the registry.

Verification

13 backend tests pass; ruff clean; migrations reversible and model-matched.
Full stack deployed and smoke-tested live: register → verify email (via logged link) → login → create tree → add people, with privacy isolation (private tree → 403 for non-members) and audit entries confirmed.

Notes / follow-ups

Place is tree-scoped in Phase 0 (shared gazetteer deferred) — see ARCHITECTURE §5.
The deploy target currently builds images from synced source; wiring it to pull CI registry images is a small follow-up (prod compose overlay).
CI image push needs REGISTRY_USERNAME / REGISTRY_PASSWORD secrets configured in Gitea.

🤖 Generated with Claude Code

## Phase 0 — Foundation Stands up the entire Provenance foundation, built in dependency order and verified live on the deployment target end-to-end. ### What's included - **Backend** — FastAPI (async, layered API → service → repository → domain), uv-managed, Postgres + Alembic. Health/readiness probes. - **Core data model** — 12 tables (User, Tree, TreeMembership, Person, Name, Relationship, Event, Place, PlaceName, Source, Citation, AuditEntry) with UUID keys, timestamps, soft-delete, and uniform `tree_id` tenant scoping. Qualified relationship edges, dual verbatim/normalized event dates, CHECK constraints. Reversible migration, `alembic check` clean. - **Privacy engine** — single read-enforcement point in the service layer (tree role + visibility + per-person override; living-person redaction flagged for Phase 2). Append-only audit log on every write. - **Local auth** — Argon2id passwords, opaque backend-issued sessions (only hashes stored; Bearer **or** HttpOnly cookie), email verification + password reset behind pluggable `AuthProvider` and `Mailer` interfaces (console mailer in dev, SMTP for operators). - **Frontend** — Next.js (App Router) + React 19 + TypeScript + Tailwind + shadcn-style UI, with a typed client generated from the backend OpenAPI spec. Auth + tree/person views. Standalone container. - **Deploy** — one compose stack (Caddy + frontend + backend + Postgres/pgvector + MinIO), twelve-factor `.env`, Caddy routing `/api`+`/health` → backend and `/` → frontend. - **CI** — Gitea Actions building backend + frontend images to the registry. ### Verification - 13 backend tests pass; ruff clean; migrations reversible and model-matched. - Full stack deployed and smoke-tested live: register → verify email (via logged link) → login → create tree → add people, with privacy isolation (private tree → 403 for non-members) and audit entries confirmed. ### Notes / follow-ups - `Place` is tree-scoped in Phase 0 (shared gazetteer deferred) — see ARCHITECTURE §5. - The deploy target currently builds images from synced source; wiring it to pull CI registry images is a small follow-up (prod compose overlay). - CI image push needs `REGISTRY_USERNAME` / `REGISTRY_PASSWORD` secrets configured in Gitea. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

justin added 16 commits 2026-06-06 11:28:42 -04:00

Scaffold FastAPI backend skeleton with health probes 03aa9a3ca7

Phase 0 foundation. uv-managed FastAPI app (package=false, runs from source via uv run). Layered seams in place: app/api for routers, app/core for config (pydantic-settings, fully env-driven) and the async SQLAlchemy engine; service/repository/domain layers land with the data model.

Exposes /health (liveness) and /health/ready (Postgres reachability via SELECT 1, 503 on failure) so the deploy wiring is verifiable before any data model exists. Includes a liveness test and the resolved uv.lock. Ignore pytest/ruff/mypy caches.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Justin Paul <justin@jpaul.me>

Add self-host compose stack (Postgres, MinIO, backend, Caddy) 0b5c3b260a

One env-driven compose stack stands up the whole system per ARCHITECTURE §2/§12. Postgres uses the pgvector image (pgvector + pg_trgm in contrib); MinIO is the S3-compatible store; Caddy reverse-proxies /api/* and /health* to the backend with an env-driven site address (':80' local, a domain for auto-HTTPS, or plain HTTP behind a Cloudflare Tunnel). Healthchecks and depends_on gate startup order.

.env.example documents twelve-factor config (DB, S3, SMTP, Caddy, model keys) with placeholders; no secrets in the repo. Verified end-to-end on the deploy target: all services healthy, /health/ready green against real Postgres.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Justin Paul <justin@jpaul.me>

Add Gitea Actions CI to build the backend image 9e4252ba8f

Builds and pushes the backend container image to the Gitea registry on git.jpaul.io on push to main and version tags, so servers pull to deploy (no build on the host). Registry credentials come from repo secrets (REGISTRY_USERNAME/REGISTRY_PASSWORD); runner label may need adjusting to the configured Gitea runner.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Justin Paul <justin@jpaul.me>

Record Phase 0 repo layout in CLAUDE.md and ARCHITECTURE 03124027fe

Documents the scaffolded tree (/backend, /deploy, /.gitea, pending /frontend), the deploy-first sequencing, and the toolchain choices (uv for backend deps, Alembic for migrations), as CLAUDE.md's layout section requires when code lands.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Justin Paul <justin@jpaul.me>

Add core data model (12 tables) and initial Alembic migration 297cb797d6

All core entities from ARCHITECTURE §5: tenancy (User, Tree, TreeMembership), people (Person, Name, Relationship), facts (Event, Place, PlaceName), provenance (Source, Citation), and the append-only AuditEntry. Cross-cutting mixins give every row a UUID key, timestamps, soft delete, and (where tree-owned) a tree_id for uniform tenant isolation.

Modeling choices: parentage as qualified edges (biological/adoptive/step/foster/donor/guardian) so non-traditional families are first-class; events keep both a verbatim date string and a normalized start/end range; closed sets are PG enums while GEDCOM-extensible vocabularies (event/name/source type) stay strings; CHECK constraints enforce single-subject events and single-target citations. Place is tree-scoped in Phase 0 (see ARCHITECTURE note). The migration is verified reversible (upgrade/downgrade drops tables and enum types) and matches the models (alembic check clean); applied on the deploy target. Dockerfile now ships migrations.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Justin Paul <justin@jpaul.me>

Add layered service/API for tenancy and people with the privacy seam dffd05d303

Wires the data model through repository -> service -> API/v1. The privacy engine (app/services/privacy.py) is the single enforcement point: every read resolves visibility there (tree role, tree visibility, per-person override; living-person redaction is a marked Phase 2 TODO). All writes record an attributable AuditEntry.

Endpoints: POST /users (open dev bootstrap until auth), GET /users/me, POST/GET /trees, GET /trees/{id}, and POST/GET /trees/{id}/persons. Authn is a temporary X-User-Id header shim; authz is membership-based (owner/editor/viewer). Domain errors map to 401/403/404/409. Verified on the deploy target: private tree -> 403 for non-members, missing actor -> 401, audit log populated.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Justin Paul <justin@jpaul.me>

Add core API integration tests 64388b75bf

End-to-end coverage of the tenancy/people flow and the privacy seam (private-tree isolation, public-tree view-but-not-edit, duplicate-email conflict, auth-required). DB-backed tests run against TEST_DATABASE_URL and skip cleanly when it is unset, so the no-DB suite still runs anywhere.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Justin Paul <justin@jpaul.me>

Document core-model decisions in CLAUDE.md and ARCHITECTURE e5a8713293

Records the landed data model and backend layout, the Phase 0 tree-scoping of Place (vs. the eventual shared gazetteer), and the temporary X-User-Id auth shim.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Justin Paul <justin@jpaul.me>

Add auth foundation: sessions/tokens schema, Argon2 hashing, config 5123c85397

Two tables (sessions, user_tokens) + migration; only token *hashes* are stored, so a DB leak yields no usable credential. Argon2id password hashing and token primitives in app/core/security. Config and .env.example gain session/cookie/token TTLs, app base URL, and SMTP settings (twelve-factor). Migration verified reversible (drops the token_purpose enum) and matches the models.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Justin Paul <justin@jpaul.me>

Add local auth: AuthProvider, mailer, sessions, /api/v1/auth 00bfe8bfca

Pluggable AuthProvider interface with a local (email+password) implementation, and a Mailer interface (ConsoleMailer for dev, SMTPMailer for operators). The auth service owns registration, login, opaque session issuance, email verification, and password reset (which revokes prior sessions). Endpoints under /api/v1/auth; sessions are returned as a Bearer token and set as an HttpOnly cookie.

Replaces the temporary X-User-Id shim: get_current_user now resolves a real session (Bearer or cookie). The open user-bootstrap endpoint is gone (registration replaces it). App logging is configured so the ConsoleMailer's verification/reset links are visible to self-hosters. Verified end-to-end on the deploy target, including the email-verification flow.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Justin Paul <justin@jpaul.me>

Test auth flows and switch core tests to session auth 9f8dd960f4

New auth suite covers registration, login (incl. wrong-password), email verification, password reset (old sessions + old password rejected), logout revocation, and no-enumeration on reset. Core tenancy tests now authenticate via real sessions. A capturing mailer makes email flows assertable. 13 tests pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Justin Paul <justin@jpaul.me>

Document landed local auth in CLAUDE.md and ARCHITECTURE e2edd4b2f1

Records the auth model (Argon2, opaque sessions, Bearer/cookie, email verify/reset behind AuthProvider/Mailer), supersedes the interim X-User-Id note, and adds integrations/ to the backend layout.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Justin Paul <justin@jpaul.me>

Scaffold Next.js frontend with generated OpenAPI client and core views a5a79f01a7

Next.js (App Router) + React 19 + TypeScript + Tailwind v4, with shadcn-style UI primitives (Button, Input, Card, Label via cva/tailwind-merge). A typed API client is generated from the backend OpenAPI spec with openapi-typescript + openapi-fetch (npm run gen:api); the committed openapi.json/schema.d.ts are the snapshot.

Views: landing, login, register, tree list + create, and tree detail with person list + create. Auth rides the same-origin HttpOnly session cookie the backend sets (Caddy proxies /api/*), so no token handling in JS. Built as a standalone container. Mobile-first; next build is clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Justin Paul <justin@jpaul.me>

Wire the frontend into the deploy stack and CI fccc81a6cc

Compose gains a frontend service; Caddy now routes / to frontend:3000 (keeping /api/* and /health* on the backend). CI builds and pushes a frontend image alongside the backend. Verified end-to-end on the deploy target: / serves the app, /api and /health still resolve through Caddy.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Justin Paul <justin@jpaul.me>

Mark Phase 0 complete in CLAUDE.md and ARCHITECTURE 6c3a9a89aa

Records the landed frontend scaffold and that Phase 0 (backend, data model, local auth, deploy stack, CI, frontend) is complete and running live; Phase 1 (core tree features) is the new current target.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Justin Paul <justin@jpaul.me>

Mirror drawbar CI/CD: push to LAN registry, pull via public FQDN 4921ce0776

Split the registry endpoints like the drawbar containers. Per-component Gitea Actions workflows (build-backend, build-frontend; runs-on docker, path-filtered) push images to the LAN endpoint 192.168.0.2:1234 over plain HTTP (buildx insecure/http) to bypass Cloudflare's request-body limit, then link each package to the repo via the Gitea API. Auth via the REGISTRY_TOKEN Actions secret (the same token drawbar uses). Tag scheme: test-main / test-sha-<long> / version / latest (v* tags).

The deploy compose now PULLS git.jpaul.io/justin/provenance-{backend,frontend}:${IMAGE_TAG:-test-main} (no host build); docker-compose.dev.yml is a local-build override for dev / pre-CI. Replaces the previous single build.yml. Docs + memory updated.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Justin Paul <justin@jpaul.me>

justin added 1 commit 2026-06-06 11:32:17 -04:00

Add Cloudflare Tunnel connector (profile-gated) to the deploy stack 828445a6b3

A cloudflared service (opt-in via the 'tunnel' compose profile, token from CLOUDFLARE_TUNNEL_TOKEN) connects the lab to Cloudflare. One public hostname -> http://caddy:80 is sufficient because Caddy does the internal path routing. Mirrors the drawbar tunnel setup.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Justin Paul <justin@jpaul.me>

justin merged commit 9e6cf6e5b7 into main

2026-06-06 11:32:31 -04:00

justin referenced this issue from a commit

2026-06-09 12:51:03 -04:00

Fix #215: pluggable LLM + embedding provider abstraction

justin referenced this pull request

2026-06-09 15:44:41 -04:00

Fix #214: ChangeProposal (propose-then-confirm) #236

justin referenced this issue from a commit

2026-06-09 15:44:41 -04:00

Fix #214: ChangeProposal (propose-then-confirm)

Sign in to join this conversation.