kirche-einfach/README.md

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

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

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.