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

```python
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.