Epic: convert cosmic-fastapi into a Copier template

[tomasanchez]

Goal

Turn this repo from a clone-and-rename template (package literally named template) into a proper scaffolding template.

Tooling decision: Copier (recommended over cookiecutter)

The template's value is its evolving standard (14 ADRs, AGENTS.md, coverage matrix). Copier's native copier update lets generated projects re-pull standard improvements via .copier-answers.yml; it supports Jinja in file contents and paths, conditional inclusion via _exclude, and typed/validated YAML questions — vs cookiecutter's JSON + post-gen-hook deletes and no native update story (needs cruft). This choice must be recorded as an ADR in docs/adr/ (ADR 0015) before conversion work starts.

Target layout

• copier.yml + author-facing README/CONTRIBUTING + docs/adr/ at template-repo root
• {{ project_slug }}/ contains the generated project (templated pyproject, src/{{ package_name }}, migrations, CI, etc.)
• Template-repo CI bakes the template across the feature matrix and runs lint+cover inside baked projects

Phases

Phase 0 — fix before templating

• fix: docker compose first-run is broken — no migrations in image, schema never created #7
• fix: requires-python >=3.10 but the code is 3.11-only #8
• fix(security): unsafe defaults — CORS wildcard with credentials, DEBUG=True #9
• chore: remove dead code and empty packages #11
• chore: clean up Makefile, lint config, and .gitignore leftovers #12
• docs: fix README drift and unify identity/version sources #13

Phase 0.5 — quality hardening (can land in parallel)

• chore(docker): harden Dockerfile and refresh .dockerignore #10
• ci: fix workflow triggers, deprecated actions, and missing gates #14
• fix(bootstrap): brittle in-memory SQLite detection breaks StaticPool wiring #15
• fix(service_layer): message bus robustness — unregistered commands and event collection #16
• fix(adapters): aggregates loaded via repository are read-only — no write-back path #17
• test: conftest builds the real production app with real settings #18
• feat(monitor): implement a real readiness probe #19

Phase 1 — conversion

• feat(template): introduce {{ project_slug }} wrapper layout and copier.yml #20
• feat(template): optional feature flags and post-generation tasks #21
• test(template): bake-and-test CI matrix for the template #22
• docs(template): author-facing vs generated-project docs allocation #23

Key risks

• Optional user slice vs the 100% coverage gate — bake-and-test matrix is the guardrail
• uv.lock must be regenerated post-gen, never templated
• GitHub Actions ${{ }} vs Jinja — use {% raw %}

[tomasanchez]

Phase 0 & 0.5 landed via #25 (merged to main, Build CI green on Python 3.13.5: 53 tests, 100% coverage, Pyrefly + Ruff clean). Persistence write-back recorded as ADR 0016. Phase 1 (Copier conversion) starting now; ADR 0015 reserved for the tooling decision.

[tomasanchez]

Phase 1 kickoff merged via #26 (Template CI green on main). The repo is now a working Copier template: copier copy produces a project that passes Ruff + Pyrefly + pytest at 100% coverage, proven by a bake-and-test harness. #20 done. Remaining: #21 (include_user_example false-path), #22 (extend the bake-test into a feature-flag matrix — the harness exists), #23 (author-vs-generated doc split; ADR 0015 currently ships into generated projects).

[tomasanchez]

Merged #28: the template is now async-only with PostgreSQL as the default (asyncpg + pgvector image), SQLite optional via a Copier database choice. Recorded as ADR 0017 (async, supersedes 0006), 0018 (Postgres/pgvector), 0019 (coverage from unit+e2e; integration as a separate CI stage). Offline bake matrix is now database × include_user_example (4 combos), all green at 100%; the real-Postgres integration tier runs in a separate CI job. Template CI green on main.

[tomasanchez]

Merged #29: author-vs-generated doc split. ADR 0015 is now author-facing at root docs/adr/; generated docs read as the scaffolded project; logo is author-facing; root CONTRIBUTING.md added; the bake matrix now runs adr-check across all 4 combos. Phase 1 complete — every tracked item (#7–#23) is merged, plus the async + PostgreSQL/pgvector scope (ADRs 0017–0019). Closing this epic. Remaining nice-to-haves tracked separately: bump deprecated GitHub Actions (Node 20 → 24) and optional branch protection.