Flow: Operational tooling for longitudinal behavioral interventions

A production-shaped prototype for HCI research combining a multi-bot conversation engine built on LangChain primitives, React PWA frontend, passkey-first authentication (via h4ckath0n), SSE-based real-time chat, and vendor-neutral Web Push notifications.

The engine uses a Router + specialist architecture:

• Router — Routes each turn to the correct specialist, validates all patch proposals, and owns the only commit path to UserProfile (Store A) and Memory (Store B).
• Intake Bot — Onboarding and profile setup. Can propose updates to onboarding fields.
• Feedback Bot — Habit tracking and barrier analysis. Can propose rolling coaching field updates and memory items.
• Coach Bot — Normal conversation and encouragement. Can propose candidates only (higher confidence threshold).

All bots use LangChain agents and tools. Proposals are validated against a permission matrix with confidence thresholds and evidence span requirements. See docs/current-architecture.md for full details.

The recommended way to run a production-like stack locally:

# Build the frontend artifact
bash scripts/ci/package_frontend.sh web
cp frontend.tar.xz web/frontend.tar.xz

# Build local images
docker build -t flow-web:local web/
docker build -t flow:local api/

# Start the stack
FLOW_WEB_IMAGE=flow-web:local FLOW_IMAGE=flow:local docker compose up

The stack runs at http://localhost:${PORT:-8080}. Caddy serves the frontend and reverse proxies /api/* to the backend (stripping the /api prefix).

Cloudflare Tunnel (terminates TLS)
  └─→ flow-web :${PORT:-8080} (Caddy, HTTP-only)
        ├─ /          → static frontend files
        └─ /api/*     → flow :8000 (prefix stripped)

• flow-web is HTTP-only — TLS is terminated by Cloudflare Tunnel (or any upstream TLS terminator).
• The backend has no /api prefix on its routes. Caddy's handle_path strips it before proxying.

FLOW_WEB_IMAGE=flow-web:local FLOW_IMAGE=flow:local \
  H4CKATH0N_DATABASE_URL=postgresql+asyncpg://flow:flow@postgres:5432/flow \
  docker compose --profile postgres up

cd api
uv sync
# Copy .env.example to .env and configure
cp ../.env.example ../.env
uv run uvicorn app.main:app --reload

cd web
npm install
npm run dev

The frontend dev server runs at http://localhost:5173 and proxies API requests to the backend.

To run real LLM responses instead of stub mode, set OPENAI_API_KEY (or H4CKATH0N_OPENAI_API_KEY) in your root .env before starting the backend. Keep this value secret and never commit it.

• Missing OPENAI_API_KEY / H4CKATH0N_OPENAI_API_KEY → chat runs in stub mode.
• Missing VAPID_PUBLIC_KEY or VAPID_PRIVATE_KEY → push notifications are disabled.

Flow uses standard Web Push VAPID keys for push subscription and delivery.

Required environment variables:

• VAPID_PUBLIC_KEY
• VAPID_PRIVATE_KEY

Generate keys (example using Python py_vapid):

python -m pip install py-vapid
python -m py_vapid --gen

Copy the generated public/private keys into .env.

Flow/
├── api/                          # FastAPI backend
│   ├── app/
│   │   ├── main.py               # App entry point (h4ckath0n create_app)
│   │   ├── routes.py             # API route handlers
│   │   ├── models.py             # SQLAlchemy 2.x models (incl. UserProfile, Memory, AuditLog)
│   │   ├── config.py             # Configuration (env vars, settings)
│   │   ├── db.py                 # Database session management
│   │   ├── middleware.py         # CSP and other middleware
│   │   ├── id_utils.py           # Custom ID generation (p... / u...)
│   │   ├── agents/               # Multi-bot LangChain agents
│   │   │   ├── engine.py         # Turn engine: Router + specialist pipeline
│   │   │   ├── intake.py         # Intake specialist agent
│   │   │   ├── feedback.py       # Feedback specialist agent
│   │   │   ├── coach.py          # Coach specialist agent
│   │   │   ├── runner.py         # Agent runner (LangChain invoke wrapper + tool trace)
│   │   │   └── tool_trace.py     # Tool call tracing callback
│   │   ├── schemas/              # Pydantic models
│   │   │   ├── router.py         # RouteDecision (INTAKE/FEEDBACK/COACH)
│   │   │   ├── patches.py        # Proposals, evidence, permissions, profile/memory schemas
│   │   │   └── tool_schemas.py   # Tool argument schemas
│   │   ├── services/             # Business logic layer
│   │   │   ├── profile_service.py    # Profile/memory persistence, validation, audit
│   │   │   ├── event_service.py      # SSE event persistence + replay
│   │   │   ├── notification_engine.py # Scheduling, dedupe, lease, push delivery
│   │   │   ├── randomization.py      # Deterministic 4-day block condition assignment
│   │   │   ├── intervention_config.py # Static A/B nudge templates
│   │   │   ├── feedback_script.py    # Deterministic A/B feedback state machine
│   │   │   ├── condition_filters.py  # Condition-C framing regex filter
│   │   │   ├── eod_summarizer.py     # End-of-day sterilized memory summaries
│   │   │   └── prompt_context.py     # Prompt template context builder
│   │   ├── tools/                # LangChain tools
│   │   │   ├── proposal_tools.py     # propose_profile_patch, propose_memory_patch
│   │   │   └── scheduler_tools.py    # Scheduling LangChain tools
│   │   └── worker/               # Scheduled-task / notification worker
│   ├── Dockerfile                # Backend container image
│   ├── prompts/                  # System prompt templates
│   ├── tests/                    # Backend test suite
│   └── pyproject.toml
├── web/                          # React PWA frontend
│   ├── Caddyfile                 # Caddy reverse proxy config (HTTP-only, :8080 default)
│   ├── Dockerfile                # flow-web container image (Caddy + static assets)
│   ├── public/
│   │   ├── manifest.json         # PWA web app manifest
│   │   └── sw.js                 # Service worker (push + notificationclick)
│   ├── src/
│   │   ├── App.tsx               # Route definitions
│   │   ├── pages/                # Page components
│   │   │   ├── Dashboard.tsx     # Project thread list
│   │   │   ├── Activation.tsx    # Join project via invite link
│   │   │   ├── ChatThread.tsx    # Real-time chat with SSE
│   │   │   ├── Notifications.tsx # Push notification management
│   │   │   ├── Landing.tsx       # Public landing page
│   │   │   ├── Login.tsx         # Passkey login
│   │   │   ├── Register.tsx      # Passkey registration
│   │   │   └── Settings.tsx      # User settings
│   │   ├── auth/                 # Passkey auth (from h4ckath0n scaffold)
│   │   ├── api/                  # API client, types, and generated OpenAPI (openapi.ts)
│   │   └── components/           # Shared UI components
│   └── package.json
├── docker-compose.yml            # Production-like local stack (flow-web + flow + postgres)
├── docs/
│   ├── README.md                 # Documentation index
│   ├── current-architecture.md   # Conversation engine, experiment, EOD firewall
│   └── release-process.md        # CI/CD, versioning, image signing
├── .env.example
└── AGENTS.md                     # Agent behavior rules

All project-scoped endpoints require passkey authentication.

This table is auto-verified by CI. See Drift prevention.

Run the standard local quality gate before every push:

bash scripts/ci/pre_push_quality_gate.sh

This runs backend and frontend static/test checks plus docs drift checks, and fails fast if any step is out of sync.

Optional browser-dependent gates can be enabled when your environment supports them:

RUN_PLAYWRIGHT=1 RUN_COMPOSE_E2E=1 bash scripts/ci/pre_push_quality_gate.sh

The engine implements the architecture defined in docs/current-architecture.md.

1. Persist user message
2. Load UserProfile (Store A) + Memory (Store B) + recent chat history
3. Router decides which specialist to run (INTAKE, FEEDBACK, or COACH)
4. Invoke specialist agent (LangChain tool-calling agent)
5. Collect patch proposals made during the agent run
6. Router validates proposals (permissions, confidence, evidence) and commits approved ones
7. Persist assistant message
8. Emit SSE events for UI update

Specialist bots propose changes via propose_profile_patch and propose_memory_patch tools. The Router validates each proposal against:

• Permission matrix: Intake → onboarding fields, Feedback → coaching fields, Coach → candidates only
• Confidence thresholds: INTAKE/FEEDBACK ≥ 0.5, COACH ≥ 0.8
• Evidence spans: Must reference recent message IDs
• Memory rules: Items ≤ 500 chars with source pointers

All proposals and decisions are logged in the patch_audit_log table.

• Web App Manifest — web/public/manifest.json enables "Add to Home Screen"
• Service Worker (web/public/sw.js):
  • Handles push events → shows system notifications
  • Handles notificationclick → deep-links to the relevant project chat (/p/{project_id}/chat)
• Subscription flow: explicit user action → request permission → subscribe with VAPID public key from backend → store subscription server-side
• iOS: "Add to Home Screen" guidance is shown before enabling notifications

cd api && uv run pytest tests/ -v --tb=short

Key test areas (api/tests/):

• Engine + Router: test_engine_integration.py, test_new_architecture.py, test_langchain_agents.py, test_langchain_tools.py, test_tool_trace.py
• 4-condition experiment: test_four_condition_experiment.py, test_prompt_context.py
• EOD memory firewall: test_eod_summarizer.py
• Notification worker / scheduling: test_notification_engine.py, test_notification_worker.py, test_notifications_routes.py, test_admin_push_perf.py
• API + contracts: test_api.py, test_api_schema_contracts.py, test_timezone_endpoint.py
• Infrastructure: test_config.py, test_logging_middleware.py, test_migrations.py, test_id_utils.py, test_prompts.py, test_milestone2.py

cd web && npm test         # Unit tests (Vitest)
cd web && npm run test:e2e # E2E tests (Playwright)

• LLM — without OPENAI_API_KEY (or H4CKATH0N_OPENAI_API_KEY), specialist agents run in stub mode with deterministic responses. With a key set, the engine uses ChatOpenAI via LangChain.
• Web Push — delivery is implemented via pywebpush in app/worker/notification_worker.py. Without both VAPID keys, push delivery is disabled and the rest of the stack still functions.

Configure in .env at the repository root (see .env.example):

When the Sheets source is configured, API startup schedules a non-blocking remote warmup. It does not delay readiness. A successful remote fetch logs Spark library loaded from remote Google Sheets; a failed fetch logs the reason and falls back to the bundled library. The first A/B request awaits an in-progress warmup rather than starting a duplicate remote request. Startup, cold-start, and stale-cache refreshes all share one task per API process: cold requests await it, while stale requests continue serving their immutable last- good snapshot. Application shutdown cancels and joins that task. Multiple API replicas maintain independent read-only caches and may each refresh their own snapshot.

Every A/B /spark/generate response reports the actual cached dataset source at prompt_version.source: google-sheets after a validated remote fetch, or bundled-file when the fallback is serving. This is authoritative even when the two datasets have identical content hashes.

Documentation parity is enforced by CI. The docs check script validates:

1. API endpoint drift — the route table in this README matches the current OpenAPI schema.
2. Environment variable drift — the env var table matches what api/app/config.py reads and what .env.example provides.
3. Link hygiene — all relative markdown links in README and docs/ resolve to existing files.

Run locally:

python3 scripts/docs/check_docs.py

The CI job docs-check runs this on every PR and push to main.

See LICENSE.