# 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:
- [x] 02-01-PLAN.md — Core overlay merge (deepMerge + overlay-aware loadConfig + FLYNN_ENV resolution + tests)
- [x] 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

**Plans:** 2 plans in 2 waves

Plans:
- [x] 03-01-PLAN.md — Backend metrics collector, RPC handlers, HTTP /health endpoint
- [x] 03-02-PLAN.md — Dashboard UI with live counters, model metrics, event stream, active requests

| Plan | Wave | Objective | Tasks |
|------|------|-----------|-------|
| 03-01 | 1 | MetricsCollector + RPC handlers + /health endpoint | 2 |
| 03-02 | 2 | Extend vanilla JS dashboard with live ops sections | 2 |

**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 | **complete** | CONF-01..03 (3) — 2 plans, 2 waves |
| 3 — Live Ops Dashboard | **complete** | DASH-01..05 (5) — 2 plans, 2 waves |

**Coverage:** 16/16 v1 requirements mapped ✓

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