kirche-einfach/AGENTS.md

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).

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).