flynn/.planning/ROADMAP.md

Roadmap: Flynn Operator DX

Created: 2026-02-09 Depth: Quick (3 phases) Core Value: Make Flynn easier to reason about, configure, and monitor

Overview

Three phases, each delivering one complete capability. Phase 1 decomposes the monolithic daemon wiring file into focused modules — this must happen first because Phases 2 and 3 both touch daemon internals. Phase 2 adds multi-environment config overlays. Phase 3 builds the live ops dashboard with real-time metrics.

Phases

Phase 1: Daemon Decomposition

Goal: daemon/index.ts is a thin composition root; each concern lives in its own module with the same public interface.

Dependencies: None (first phase)

Requirements: DECO-01, DECO-02, DECO-03, DECO-04, DECO-05, DECO-06, DECO-07, DECO-08

Plans: 3 plans in 2 waves

Plan	Wave	Objective	Tasks
01-01	1	Extract models.ts, memory.ts, tools.ts	3
01-02	1	Extract channels.ts, agents.ts, routing.ts	3
01-03	2	Finalize thin composition root	2

Success Criteria:

1. Running pnpm test:run passes 1077+ tests with zero regressions
2. daemon/index.ts is under 200 lines and contains only imports, wiring, and lifecycle — no business logic
3. Each extracted module (models, channels, agents, memory, tools, routing) can be understood in isolation — reading one file tells you everything about that concern
4. Adding a new model provider or channel adapter requires editing the relevant module file, not daemon/index.ts

Phase 2: Config Overlays

Goal: Operator can manage dev/docker/production configs with a base file plus lightweight overlay files, selected by environment variable.

Dependencies: Phase 1 (daemon is decomposed; config loading changes are lower risk)

Requirements: CONF-01, CONF-02, CONF-03

Plans: 2 plans in 2 waves

Plans:

• 02-01-PLAN.md — Core overlay merge (deepMerge + overlay-aware loadConfig + FLYNN_ENV resolution + tests)
• 02-02-PLAN.md — Doctor overlay validation (checkOverlayExists check)

Plan	Wave	Objective	Tasks
02-01	1	Core overlay merge logic + FLYNN_ENV resolution + tests	2
02-02	2	Doctor overlay validation check	1

Success Criteria:

1. Setting FLYNN_ENV=docker and starting Flynn loads config/docker.yaml merged on top of the base config — operator sees docker-specific settings active
2. Starting Flynn without FLYNN_ENV works exactly as before — existing config files unchanged, zero breakage
3. Running flynn doctor with FLYNN_ENV=staging (no staging.yaml) reports a clear error identifying the missing overlay file

Phase 3: Live Ops Dashboard

Goal: Operator can open the web dashboard and see real-time system health — counters, model performance, event stream, and active requests — without tailing logs.

Dependencies: Phase 1 (metrics hooks need to be wired into decomposed modules, not the god file)

Requirements: DASH-01, DASH-02, DASH-03, DASH-04, DASH-05

Success Criteria:

1. Opening the dashboard shows live-updating counters for messages processed, active sessions, queue depth, and uptime — values change in real time as messages flow
2. After sending a message through any channel, the model call appears in the dashboard with latency, tokens/sec, and provider name within seconds
3. Triggering an error (e.g., bad model config) shows the error in the dashboard event stream with timestamp and context — no need to check terminal output
4. Hitting GET /health returns JSON with daemon status, uptime, and component readiness — usable for Docker HEALTHCHECK or monitoring

Progress

Phase	Status	Requirements
1 — Daemon Decomposition	complete	DECO-01..08 (8) — 3 plans, 2 waves
2 — Config Overlays	in_progress	CONF-01..03 (3) — 2 plans, 2 waves
3 — Live Ops Dashboard	not_started	DASH-01..05 (5)

Coverage: 16/16 v1 requirements mapped ✓

---

Roadmap created: 2026-02-09 Last updated: 2026-02-09