Stage 0: Research Brief — Feed-Hub Flow Architecture

Stage 0: Research Brief — Feed-Hub Flow Architecture

Generated: 2026-03-07
Method: Evolution³ Stage 0 — Pure Fact-Gathering
Topic: Feed-Hub flow architecture evolution

---

What Exists Today

### Scale
- 71 Python files, 28,134 lines of code
- 64 Prefect flows, 7 standalone scripts/libs
- 35 deployments via single `serve()` call in `deploy_feed_flows.py`
- 29 Supabase tables accessed across all flows
- 5 embedded Prometheus servers (:9122, :9125, :9126, :9127, :9128)

### Flow Domains (8 groups)
| Domain | Flows | Lines |
|--------|-------|-------|
| Infrastructure/Monitoring | 12 | ~5,500 |
| Serenity Soother (ss_*) | 19 | ~6,200 |
| Memory/Knowledge | 6 | ~2,700 |
| Noosphere/Dream/Creative | 9 | ~2,500 |
| Intelligence/Analysis | 6 | ~3,400 |
| Operational/Reporting | 6 | ~1,800 |
| Design Pipeline | 4 | ~1,300 |
| FirstDate App | 2 | ~520 |
| Shared libs + CLI tools | 7 | ~2,900 |

### Deployment Architecture
- Mac1: Primary host, runs Prefect via LaunchAgent
- Cloud VM: Prefect server at :4200 (systemd service), but broken — `cross_pollination_crawler.py` crashes import chain
- Mac5: Only `command_executor.py` (polls Supabase `command_queue`)
- Scheduling: 2min→monthly range. 35 Prefect deployments, all `serve()` pattern (single process)

### External Dependencies (12+ services)
Supabase (primary), Discord webhooks (9 channels), Gemini API, Prefect, Apify, Prometheus, YouTube API/Analytics, NUMU FARE (:8500), Noosphere MCP, EvoFlow TIE, GCS, Orbit, ab-browser

### State Management
- 14 dot-state JSON files (`.*.json`) in feed-hub directory
- 73 Syncthing conflict files — active data corruption risk
- shared_state.py (211 lines, NEW) — dual-write to Supabase `machine_context_cache` + local file
- Only 2 of 26 stateful flows migrated to shared_state (autopilot_digest, x_repost_watcher)
- 13 states already in Supabase (batch migrated), but flows still reading from local files

---

Critical Issues

### 1. Code Duplication (Systemic)
- `_load_supabase_key()` — 6+ distinct variants across files
- `SUPABASE_URL` — hardcoded in ~20 files with 4 different env var lookup patterns
- `SB_HEADERS` dict — copy-pasted everywhere
- `MACHINE_ID` lookup — duplicated in 7 files
- No shared `config.py` or constants module

### 2. Syncthing Conflicts (73 active)
- `dream_sync` alone: 10 conflicts in a single day (2026-03-06)
- Root cause: raw `STATE_FILE.write_text(json.dumps(...))` across 26 flows
- Solution exists (`shared_state.py`) but only 2/26 flows adopted

### 3. Cloud VM Deployment Broken
- `cross_pollination_crawler.py` uses `@flow(tags=...)` — not supported on cloud-vm's older Prefect
- Crashes entire `deploy_feed_flows.py` import chain
- Zero flows run on cloud-vm

### 4. No requirements.txt
- 71 files, no pinned dependencies
- Environment drift between Mac1/Mac5/cloud-vm invisible until runtime failure

### 5. Embedded Prometheus Servers
- 5 flows run HTTP servers in daemon threads alongside Prefect logic
- If Prefect restarts the flow, server loses port binding
- Fragile: port conflicts, zombie processes

### 6. NUMU Integration Incomplete (WS6)
| Flow | Status |
|------|--------|
| task_aggregator | Partial (NUMU augmentation, not replacement) |
| heartbeat_pulse | Not started |
| infra_watchdog | Not started |
| command_executor | Not started |
| memory_update_flow | Not started |
| pane_coordinator | Not started |

---

NUMU FARE Integration Points

### Available HTTP API (24 endpoints on :8500)
Key endpoints for feed-hub:
- `GET /sentinel` — aggregated service health (replaces heartbeat_pulse + infra_watchdog manual checks)
- `GET /fleet` — node health from FleetBridge (replaces pane_coordinator file reads)
- `GET /registry` — agent records (replaces task_aggregator direct Supabase)
- `GET /scheduler/jobs` — active jobs
- `GET /dispatch/queue` — pending + running tasks
- `POST /memory/seed` — memory document ingestion
- `GET /acmp` — auth profile stats

### mesh_coordinator.py (hook-level, not flow-level)
- Domain classification, work claiming, rate limit broadcast
- Writes to: `machine_domains`, `machine_work_queue`, `work_claims`, `machine_context_cache`
- Used by Claude Code hooks, not by Prefect flows

### shared_state.py (flow-level)
- Dual-write: Supabase `machine_context_cache` + local file
- `load_flow_state()` / `save_flow_state()` API
- 13 states migrated to Supabase, 2 flows actually using the module

---

Architecture Patterns (Current)

### Communication: 3 channels
1. Supabase tables — primary data bus between flows
2. Filesystem — state files, Obsidian vault, memory files
3. Discord webhooks — output only

### Anti-Patterns
1. No shared config/constants module
2. State files as cross-machine communication (via Syncthing = conflicts)
3. Monolithic `serve()` — all 35 flows in one process (one crash = all down)
4. Prometheus servers inside Prefect flows (should be standalone)
5. Manual `while True` loops for some daemons (pane_coordinator)

---

Open Questions for Stage 1

1. Should flows be split into multiple Prefect processes? One crash in serve() kills all 35 deployments.
2. Should all flows migrate to shared_state.py? Or is there a better abstraction?
3. Should NUMU become the single data gateway? (WS6 vision) Or keep flows talking to Supabase directly?
4. How to handle the cloud-vm deployment? Fix Prefect version, or move to a different deployment model?
5. Should Prometheus servers be extracted? Into standalone exporters vs embedded in flows?
6. What's the right config management pattern? `config.py`, env vars, NUMU toml, or something else?
7. How should flows communicate? Supabase-only, NUMU bus, or hybrid?