103 lines
4.7 KiB
Markdown
103 lines
4.7 KiB
Markdown
# 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`.
|