# Kirche Einfach

AI-assisted administration platform for church organizations.

Staff describe a request in plain words. The platform guides them through the
process, checks the rules automatically, and asks a human only when something
needs judgment. Every step is documented and traceable.

## Features

- **Visual flow authoring** — design decision flows in Langflow, then bring
  them into the platform.
- **Flows as files** — each flow lives as one JSON file under
  `backend/flows/`. The directory is the source of truth: committed to git,
  reviewable, diffable.
- **Automatic sync** — the API watches `backend/flows/` and reconciles every
  change into the database and the runtime: new files become flows, edits
  become new versions, deleted files remove the flow (including its runs).
  Same on every startup; also triggerable via `POST /api/flows/sync` or
  `uv run python scripts/sync_flows.py --sync`.
- **Versioned runtime** — every change creates an immutable version; versions
  deploy to the lightweight LFX runtime and can run synchronously or streamed.
- **Approvals** — a flow can pause and ask a human for a decision. Approving
  can automatically start a follow-up ("continuation") flow.
- **Web UI** — three tabs: *Vorgänge* (flows and runs), *Freigaben*
  (approvals), *Administration* (import, sync, deploy).

## Infrastructure

```mermaid
flowchart LR
    subgraph Repo["Git repo — source of truth"]
        FLOWS["backend/flows/*.json<br/>one Langflow export per flow"]
    end
    subgraph Stack["Compose stack (dev + prod)"]
        UI["frontend — React UI (3000)"]
        API["app — FastAPI (8000)<br/>+ embedded flow-watcher"]
        DB[("app.db — SQLite file")]
        LF["langflow — authoring UI (7860)<br/>langflow.db — SQLite file"]
        LFX["lfx — flow runtime (6004)"]
        WT["watchtower — nightly image updates"]
    end
    UI --> API
    FLOWS -->|watch + sync| API
    API -->|definitions · versions · runs · approvals| DB
    API -->|pull / export| LF
    API -->|upload · run · unregister| LFX
    LFX -->|approval callbacks| API
    WT -.->|updates :latest images| LF
```

| Service        | Purpose                              | URL                        |
| -------------- | ------------------------------------ | -------------------------- |
| React frontend | Web UI (Vite)                        | http://localhost:3000      |
| FastAPI backend| API + flow orchestration             | http://localhost:8000      |
| API docs       | Swagger UI                           | http://localhost:8000/api/docs |
| Langflow       | Visual flow authoring                | http://localhost:7860      |
| LFX            | Flow runtime (internal, no direct UI)| localhost:6004             |
| SQLite files   | `backend/data/kirche.db` (app), Langflow keeps its own file | — |

Why SQLite: a flow run needs only a handful of single-row statements, and
Langflow itself runs on SQLite by default — so the whole stack works without
a database server. Postgres can return later by changing `DATABASE_URL`
(migrations stay portable).

## Getting Started

1. Copy `.env.example` to `.env` and fill in the secrets.
2. Open the repo in VS Code → "Reopen in Container". Setup installs
   dependencies, migrates the database, and syncs `backend/flows/`.
3. Run the backend from `backend/`: `uv run uvicorn app.main:app --port 8000`.
   Run the frontend from `frontend/`: `npm run dev`.

Production (self-hosted, internal use — no TLS/reverse proxy included):

```sh
docker compose -f compose.prod.yml up -d --build
```

## Development

Backend (from `backend/`):

- `uv run pytest` — full test suite (throwaway SQLite file, no external DB).
- `uv run alembic upgrade head` — migrate the dev database.
- `uv run python scripts/sync_flows.py --sync` — reconcile `backend/flows/`.
- `uv run python scripts/sync_flows.py --pull` — export all Langflow flows
  into `backend/flows/` first.
- `uv run python scripts/deploy_flow.py --langflow-id <uuid>` — import one
  Langflow flow via the API.
- `uv run python scripts/make_flow_fixtures.py` — regenerate the bundled
  flows (writes test fixtures and `backend/flows/`).
- `uv run python scripts/smoke_e2e.py` — manual end-to-end smoke.

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

Flow workflow: design in Langflow → export into `backend/flows/<name>.json`
(`--pull`, or UI download) → commit → the watcher deploys it automatically.
Deleting a file removes the flow including its runs (git keeps the JSON).

Container updates: registry images (`langflowai/langflow:latest`)
auto-update nightly via Watchtower (`nickfedor/watchtower`). Locally built
images (`app`, `lfx`, `frontend`) update with `docker compose build --pull`.