William Valentin
97 lines
4.5 KiB
Markdown
97 lines
4.5 KiB
Markdown
# 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*
|