kirche-einfach/PLAN_NEXT.md

Continuation plan — kirche-einfach next steps (written after Phase 0)

For a future agent restoring this session (e.g. after a container rebuild). Read this file + AGENTS.md + README.md first. All code/comments in English; only user-visible website strings are German.

0. Where we are

Phase 0 (this commit) is done — Docker/devcontainer reproducibility:

• langflow image pinned via ${LANGFLOW_VERSION:-1.12.0} (was :latest with nightly Watchtower drift). Dockerfile.lfx pins lfx~=<same> (ARG LFX_VERSION=1.12.0). Backend test dep pinned lfx~=1.12.0. Reason: official LFX contract — major.minor of Langflow and LFX must match, patches are independent.
• langflow mounts backend/components (LANGFLOW_COMPONENTS_PATH) and backend/flows (LANGFLOW_LOAD_FLOWS_PATH), both :ro. Files stay source of truth; the API watcher (app/flows/sync.py) remains the ONLY sync path — never add a second watcher.
• Backend venv moved to /opt/venv (image-local, UV_PROJECT_ENVIRONMENT), managed Python to /opt/python (UV_PYTHON_INSTALL_DIR), both a+rX. Removed kirche-venv + kirche-node-modules named volumes (they shadowed image content with empty volumes on first start = split-brain). backend/entrypoint.sh uses /opt/venv/bin/*, ensures data/ exists and is vscode-owned. frontend/entrypoint.sh runs npm ci when node_modules/.bin/vite is missing (covers fresh prod checkouts).
• devcontainer.json: opencode session persistence via named volumes kirche-opencode-share → ~/.local/share/opencode (sessions DB) and kirche-opencode-config → ~/.config/opencode; interpreter path is now /opt/venv/bin/python. setup.sh chowns first, then runs uv sync as vscode (was: root uv sync into /root-backed venv → Permission denied for vscode; backend/data root-owned → DB unwritable).
• Stale local backend/.venv/ (bind-mount leftover) can be deleted manually after rebuild: rm -rf backend/.venv. It is gitignored; nothing references it anymore.

Verified in this session: uv run pytest green (after local venv repair, see §5). NOT verifiable here (no node/docker in this sandbox): npm run build, docker compose config, container rebuild. CI covers all three (.forgejo/workflows/). After rebuilding the devcontainer, re-run: uv run pytest (attached api, from backend/), docker compose exec frontend npm run build, docker compose config --quiet.

Still open: nothing from the original list — Phases 1–4 are implemented (see §0.2). Remaining eyeball checks: kirche category in the Langflow palette, RJSF form UX in a browser, magic-link mail with real SMTP.

0.1 Follow-up fixes (commits after Phase 0)

fix: devcontainer build and setup on fresh clones + feat: magic-link auth + the LFX/stack repair commit:

• docker-outside-of-docker needs "moby": false (python:3.12-slim is Debian trixie, no moby-cli in its repos). Removed the manual /var/run/docker.sock bind (breaks Windows, feature handles it).
• setup.sh used su vscode -c (drops env incl. UV_PROJECT_ENVIRONMENT → stray backend/.venv, blind sync). Now sudo -u vscode -E helper. Missing .env is provisioned from .env.example, not fatal.
• Compose env_file is required: false everywhere (fresh clones, CI). Images install curl git ca-certificates; .dockerignore files keep host node_modules/.venv/data out of build contexts.
• settings.database_url default is now a real sqlite:/// URL (bare path crashed create_engine/alembic; api could never boot uncconfigured).
• Dockerfile.lfx CMD dropped the positional /flows: lfx>=1.12.1 exits on an empty flow dir (restart-loop → whole stack unhealthy). lfx service blanks LANGFLOW_API_KEY (server prefers it over LFX_API_KEY, so backend deploys 401'd and /flows stayed empty).
• Both entrypoints run via explicit sh (git tracks them 100644; the bind-mount shadows image perms, breaking Windows checkouts).
• Verified live: full compose up green (api/frontend/langflow/lfx), startup sync deploys backend/flows to LFX, uv run pytest 60 green. Before Reopen in Container: docker compose down any manual stack (same project name → port clash).

0.2 Phases 1–4 (done, with deviations)

• Phase 1 auth as planned (app/auth/*, migration a3f1c9e2b4d7). Additionally fixed: settings.database_url default is a real sqlite:/// URL (bare path crashed create_engine/alembic).
• Phase 2: CustomInputForm has the 10 planned inputs plus one hidden form_values: MessageTextInput (show=False) plumbing input. Without it, submitted web-form values never reached the run (LFX routes run input to entry nodes; scalar fields are not connectable). Fixture flow intake_form.json: ChatInput → form.form_values, form.form_data → ChatOutput; collect() merges the envelope ({"payload": {...}} unwrapped like the other components) over field defaults. Verified live: run with values returns them in the output.
• Phase 2 generator caveat: lfx 1.12.x to_frontend_node() cannot re-instantiate MultiselectInput (emits list, constructor forbids extras — their own builtin SearXNGToolComponent fails identically). kirche_node() therefore replicates the pre-validation dict build and appends the code field by hand. If a future lfx fixes this, simplify back to plain to_frontend_node().
• Phase 3 as planned (input_schema.py, FlowVersion.input_schema, migration b7e2d4a1c9f3, GET input-schema). Deviations: schema is cached in store.create_version (single choke point: sync, import, API all covered); parser skips show: false fields; enum-mismatched defaults omitted; endpoint maps InvalidError → 404 too (get_latest_deployed_version raises it, not NotFoundError).
• Phase 4 as planned (react-router-dom@7, @rjsf/core + @rjsf/validator-ajv8 (v6), English routes, German labels, credentials: include, old tab shell dropped). FlowsTab.tsx deleted; ApprovalsTab/AdminTab reused inside Tasks/Admin pages. Verified: npm run build green, routes + /api proxy return 200, served schema validates under JSON-Schema Draft 7.

0.3 Frontend design pass (Mantine)

Plain-HTML UI replaced with a coherent Mantine v9 design system: @mantine/core + @mantine/hooks + @rjsf/mantine (v6, matches core)

• @tabler/icons-react. src/theme.ts (kirchenblau primary, system fonts only, serif display headings), AppShell header/nav, per-page Card/Table/Alert/Badge via shared StatusBadge, dark mode via localStorage manager + toggle + inline ColorSchemeScript equivalent. RJSF swap was import-only; SSR smoke test proved all 10 intake labels + textarea/password/checkbox/slider widgets render. npm run build green.

0.4 Landing page (conversion structure + screenshot automation)

StartPage rebuilt along the 8-block anatomy (hero with outcome headline, fact bar, 3 benefits, real product screenshot, 3 steps, trust list, FAQ, final CTA, footer mini) — one CTA everywhere (/access), honest copy (no fake testimonials/logos/numbers; pricing section omitted, model open). Centralized hosting in Germany per operator decision (not self-hosted). frontend/scripts/capture.mjs + npm run screenshots (Playwright/Chromium in the frontend container) regenerates public/screenshots/*.png; the workflows shot auto-selects intake_form to show the generated RJSF form. Vite dev server.watch polling enabled (Windows bind-mount events often never reach the Linux watcher → stale modules otherwise).

0.5 Email-first login (POST /api/auth/magic/request)

/login without ?token= shows an email form (+ "Hier anfragen" link). Allowed = approved user row or ADMIN_EMAILS (admin auto-created on first request); anything else → 403 and the frontend forwards to /access?email=… (prefilled). Rate-limited (5/hour), token by mail only, delivery failures never 500 (see §0.4 hardening).

0.6 Polish round (bell-tower favicon, lfx-clean flows, HTML mail)

• Favicon simplified to a stylized bell tower (spire + shaft + bell-arch knockout); PNGs regenerated via npm run icons.
• lfx validate --level 4 now green for ALL canonical flows + regression test (test_lfx_validate.py). Root cause: required form fields have no edge (values arrive via the form_values envelope). Fix: generator writes a single-space sentinel value for required template fields; the form parser treats whitespace-only values as "no default". L3 Message-vs-str warnings are known lfx-validator noise (MessageTextInput accepts Message at runtime).
• New-input authoring docs: backend/components/kirche/README.md.
• Magic-link + access-notification mails are branded multipart (text + HTML): kirchenblau header, serif headline, real button link, German copy, email-safe tables/inline styles, no external assets.

1. Locked decisions (do not re-ask)

• Auth: SMTP magic-link, 15-min single-use tokens (secrets.token_urlsafe, store sha256, used_at set before session creation), session = opaque id in DB table, cookie HttpOnly; Secure; SameSite=Lax; Path=/. SMTP creds already in .env (SMTP_HOST/PORT/USERNAME/PASSWORD, MAIL_FROM, CONTACT_TO); dev fallback logs the link when SMTP unset.
• FileInput is a stub for now (string reference only); real upload later.
• Frontend: react-router-dom + RJSF (@rjsf/core + @rjsf/validator-ajv8). RJSF renders backend-supplied {json_schema, ui_schema}; server re-validates (client validation is UX only).
• Routes are pure English (user correction — no German slugs anywhere, including URLs): /, /access (was once sketched as /zugang — do NOT use), /login?token=, /app/workflows, /app/tasks, /app/admin. Visible labels/nav are German (Start, Zugang, Workflows, Aufgaben, Verwaltung); code, props, comments, routes English.
• Langflow preload + mount (done in Phase 0). Custom-component lib in backend/components/kirche/ must stay GUI-editable: category folder + __init__.py + Component subclasses using lfx.io inputs only (stdlib + lfx, so the LFX runtime can execute them).
• Watchtower: langflow label removed (pinned images must not auto-update). Version bumps = deliberate LANGFLOW_VERSION + LFX_VERSION change, then lfx upgrade --upgrade-flow=safe check over backend/flows/*.json.

2. Phase 1 — Backend auth (magic-link + RBAC)

Files: backend/app/models/user.py (User, AccessRequest, MagicLinkToken, Session), backend/app/auth/{schemas,service,mail,api, deps}.py, wire router in app/main.py, settings in app/settings.py (frontend_url, admin_emails, contact_to, mail_from, smtp_*), ONE new Alembic revision (never edit applied migrations).

Endpoints:

• POST /api/access/requests public, rate-limited: {name,email,reason} → row pending + notify CONTACT_TO.
• POST /api/access/requests/{id}/approve|reject admin: approve → upsert User + emit magic-link + SMTP send.
• POST /api/auth/magic/consume {token} → session cookie; GET /api/auth/me; POST /api/auth/logout (delete session row).
• POST /api/auth/admin-bootstrap: only when user table empty AND email in ADMIN_EMAILS.
• Tenant from session (user.tenant_id); keep old tenant_id body param as deprecated fallback. require_admin dependency; keep API handlers thin (DB only via app/flows/store.py + new app/auth/* service funcs).

Tests (all in backend/tests/): request→approve→consume→me→logout happy path; token expiry boundary (15 min); token reuse → 400; admin-only → 403; bootstrap-once; cookie flags (HttpOnly, SameSite, Path); assert no token/secret in logs.

3. Phase 2 — CustomInput* library (GUI-editable)

• backend/components/kirche/__init__.py + backend/components/kirche/form_inputs.py: class CustomInputForm(Component) with inputs StrInput, MultilineInput, SecretStrInput, IntInput, FloatInput, BoolInput, DropdownInput, MultiselectInput, SliderInput, FileInput (stub) + Output. Category dir kirche/ = appears in Langflow GUI.
• Regenerate/add fixture flow using it via backend/scripts/make_flow_fixtures.py; keep simple_rule.json as the textarea-fallback case. Commit flow JSON (source of truth).

4. Phase 3 — Dynamic-form parsing (no second watcher)

• New backend/app/flows/input_schema.py: extract_form_schema(langflow_json) -> {json_schema, ui_schema}. Find nodes with type/display_name starting CustomInput; iterate template minus code; map _input_type → JSON Schema type/widget (StrInput/MessageTextInput→string, MultilineInput→string+textarea, SecretStrInput→string+password, IntInput→integer, FloatInput→number, BoolInput→boolean, DropdownInput→string+enum, MultiselectInput→array+enum, SliderInput→number+range, FileInput→string stub); display_name/info/value/options/required/ advanced → title/description/default/enum/required/uiSchema. No such node → {fallback: "textarea"}.
• Called from existing sync_from_directory (cache per version in new nullable input_schema JSON column via Alembic) + new GET /api/flows/{id}/input-schema → {flow_id, version_no, json_schema, ui_schema} (latest deployed version; 404 when none).
• Tests: per-type mapping table, fallback, sync persistence, endpoint 404.

5. Phase 4 — Frontend (router + RJSF, German UI, English routes)

Deps: react-router-dom, @rjsf/core, @rjsf/validator-ajv8. Routes (English, see §1): /, /access, /login, /app/workflows (flow select → GET input-schema → RJSF <Form> → POST run), /app/tasks (own runs + approval states), /app/admin (admin-only: access-request queue, ALL tasks incl. open human-intervention with approve/reject + note, import/sync/deploy). fetch with credentials: "include". Refactor FlowsTab/ApprovalsTab/AdminTab into route components; drop old tab shell. Verify with npm run build.

6. Operational notes for the next agent

• Commands: backend from backend/: uv run pytest, uv run alembic upgrade head, uv run python scripts/sync_flows.py --sync; frontend via docker compose exec frontend npm run build.
• Local venv repair (this sandbox had a root-backed broken .venv): rm -rf backend/.venv && uv sync (network needed for uv python install). In rebuilt containers this is unnecessary (/opt/venv).
• .env (gitignored) still lacks FRONTEND_URL/ADMIN_EMAILS from the .env.example diff — copy them over locally when starting Phase 1. Never commit .env.
• Flow JSON that fails LFX after a version bump: run lfx upgrade --upgrade-flow=safe on the file, review diff, commit.
• Definition of done per AGENTS.md: new behavior has tests, uv run pytest green, npm run build green when frontend changed, schema changes as new Alembic revisions.