jonas/kirche-einfach
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
kirche-einfach/AGENTS.md

4.9 KiB
Raw Blame History

Agents

Kirche Einfach — AI-assisted church administration. FastAPI backend (backend/, Python 3.12, SQLModel, SQLite) + React 19/Vite frontend (frontend/). Flow definitions live as JSON files in backend/flows/ (source of truth); the DB is derived by the sync engine.

Commands

Backend (run from backend/):

  • uv sync — install dependencies
  • uv run pytest — full test suite (throwaway SQLite file, no external DB needed)
  • uv run alembic upgrade head — migrate the dev database (backend/data/, gitignored)
  • uv run python scripts/sync_flows.py --sync — reconcile backend/flows/ into DB + LFX
  • uv run uvicorn app.main:app --port 8000 — run the API (paths resolve from repo root, CWD-independent)

Frontend (run from frontend/): npm install, npm run dev, npm run build (typecheck + build).

Multi-container ops

One docker-compose.yml at the repo root for dev and prod. Dev specifics live in .devcontainer/devcontainer.json only — never add dev-only services, profiles, or override files. Containers: api (FastAPI :8000, attached), frontend (Vite :3000), langflow (:7860), lfx (:6004), watchtower (prod only, not in runServices).

  • Backend suite (attached container, from backend/): uv run pytest.
  • Frontend build (node lives in frontend, reach it via exec from the repo root): docker compose exec frontend npm run build. Fallback without a docker socket: VS Code "Attach to Running Container" → frontend.
  • Logs/restart: docker compose logs -f <service>, docker compose restart api.
  • If exec misses the project, find it via docker compose ls.
  • CI runs on Forgejo (.forgejo/workflows/): backend pytest, frontend build, compose validation. Needs a Runner with the docker label online.
  • Prod: own .env with secrets + FRONTEND_MODE=preview; code updates via git pull + restart, image rebuilds only for dependency changes (docker compose up -d --build).
  • Git in the container uses HTTPS with GCM (credential.helper=manager, installed by .devcontainer/setup.sh together with libicu76 runtime). Remote URL has no embedded token. First push/pull triggers a device-code prompt (open URL on host). Rotate GitLab tokens in GitLab UI before switching credentials.

Definition of done

  • New behavior has tests; uv run pytest is green before reporting completion.
  • npm run build is green when frontend code changed.
  • Schema changes ship as a new Alembic revision — never edit an applied migration.

Architecture rules

  • backend/flows/*.json is the source of truth (one Langflow export per file). Never write flow JSON anywhere else.
  • Only backend/app/flows/sync.py reconciles files into the DB. CLI, POST /api/flows/sync, and the embedded watcher must call it — never duplicate its logic.
  • All DB access goes through backend/app/flows/store.py. Keep API handlers thin.
  • Talk to LFX only via LfxClient, to Langflow only via LangflowClient.
  • Flow JSON must stay a valid Langflow export (store requires data.nodes/data.edges).
from app.flows.sync import sync_from_directory
report = await sync_from_directory(session, lfx, settings.flows_dir)

Boundaries

  • Never commit secrets. .env is gitignored; only .env.example is tracked.
  • Never edit backend/data/* (runtime SQLite files) or __pycache__.
  • Never add a second file-watcher or a second sync path.
  • Deleting backend/flows/<name>.json deletes the flow including its runs from the DB (by design).

Git

When committing: git add -A && git commit -m "<message>" (conventional commits: feat:, fix:, chore:, docs:). When pushing: git push (branch is tracking origin/main).

Versioning

  • VERSION (repo root) is canonical — currently 0.1.0.
  • Backend: backend/pyproject.toml version; Frontend: frontend/package.json version — bump both together with VERSION on every release.
  • SemVer: feat → minor (X.Y+1.0), fix → patch (X.Y.Z+1), breaking → major (X+1.0.0). Tag vX.Y.Z at release merge.
  • Changelog: every user-visible change gets an [Unreleased] entry (Keep a Changelog categories) before commit; at release move it into [X.Y.Z] - YYYY-MM-DD.

Git workflow

  • New work branches from main: feat/<short> for features, fix/<short> for fixes.
  • Push branch, open MR, merge --no-ff on green CI, delete branch.
  • Never push directly to main for features or fixes.

Web-dev digest

  • Small batches: PR diff ≤ ~200 lines ideal; trunk-based with short-lived branches (above).
  • Tests green before merge (definition of done); npm run build green for frontend.
  • Docs in same PR as feature (README, AGENTS, CHANGELOG).
  • Deprecate in minor, remove in next major; document Removed/Deprecated in CHANGELOG.
  • Lockfiles (uv.lock, package-lock.json, compose pins) — don't drift without reason.
  • Future implementation ideas → ROADMAP.md (authoritative); CHANGELOG.md is historical only.