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

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