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

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

3.3 KiB Raw Blame History