9f14a6b226
ASCII mockups showing: - TUI main view with worker grid and activity stream - TUI worker detail view with focused log - Web dashboard with worker cards, activity feed, and timeline - Web worker detail modal Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
25 KiB
25 KiB
FABRIC Implementation Plan
Flow Analysis & Bead Reporting Interface Console
Overview
FABRIC is a live display for NEEDLE worker activity. It parses NEEDLE's logging output and renders it in real-time as either a TUI (terminal) or web dashboard.
Goals
- Live Display: Real-time visualization of NEEDLE worker activity
- Dual Interface: TUI for terminal users, web app for browser users
- Stateless: Reads and displays - no storage or persistence
Data Flow
NEEDLE Workers → ~/.needle/logs/ → FABRIC → Live TUI or Web Dashboard
FABRIC continuously tails NEEDLE's output and updates the display in real-time.
Input: NEEDLE Log Format
FABRIC expects structured JSON log lines from NEEDLE:
{"ts":1709337600,"worker":"w-abc123","level":"info","msg":"Starting task","task":"bd-xyz"}
{"ts":1709337601,"worker":"w-abc123","level":"debug","msg":"Tool call","tool":"Read","path":"/src/main.ts"}
{"ts":1709337605,"worker":"w-abc123","level":"info","msg":"Task complete","duration_ms":5000}
Parsed Structure
interface LogEvent {
ts: number;
worker: string;
level: 'debug' | 'info' | 'warn' | 'error';
msg: string;
[key: string]: any; // Additional fields
}
Default Source
FABRIC reads from ~/.needle/logs/ by default. NEEDLE's folder structure:
~/.needle/
├── config.yaml # NEEDLE configuration
├── logs/ # Worker log output (FABRIC reads this)
├── state/ # Runtime state
├── cache/ # Cached data
└── README.md
Output: Live Displays
TUI Mode (fabric tui)
Live terminal dashboard that continuously updates:
- Worker Grid: Real-time status of all active workers
- Log Stream: Scrolling log output as events arrive
- Detail Panel: Focus on a specific worker's activity
Features:
- Auto-updates as new log events arrive
- Filter by worker, log level, or search term
- Keyboard navigation (j/k scroll, / search, Tab switch panels, q quit)
- Color-coded log levels
TUI Mockup
┌─ FABRIC ─────────────────────────────────────────────────────────────────────┐
│ │
│ Workers (4 active) [?] Help │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ ● w-alpha Running bd-1847 "Implement auth flow" 2m 34s │ │
│ │ ● w-bravo Running bd-1852 "Fix login validation" 1m 12s │ │
│ │ ○ w-charlie Idle - - - │ │
│ │ ● w-delta Running bd-1849 "Add unit tests" 45s │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
│ │
│ Activity Stream Filter: [All ▾] │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ 14:32:07 w-alpha INFO Tool call: Edit src/auth/login.ts │ │
│ │ 14:32:05 w-bravo DEBUG Reading file: src/validators/index.ts │ │
│ │ 14:32:04 w-delta INFO Starting task bd-1849 │ │
│ │ 14:32:01 w-alpha INFO Tool call: Read src/auth/types.ts │ │
│ │ 14:31:58 w-bravo WARN Retry attempt 2/3 for API call │ │
│ │ 14:31:55 w-alpha DEBUG Analyzing dependencies... │ │
│ │ 14:31:52 w-charlie INFO Task bd-1845 completed (duration: 4m 12s) │ │
│ │ 14:31:50 w-bravo INFO Tool call: Grep pattern="validateUser" │ │
│ │ 14:31:47 w-alpha INFO Tool call: Glob **/*.ts │ │
│ │ 14:31:44 w-charlie INFO Committing changes... │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
│ │
│ [Tab] Switch panel [j/k] Scroll [/] Search [f] Filter [q] Quit │
└──────────────────────────────────────────────────────────────────────────────┘
TUI Worker Detail View (when worker selected)
┌─ FABRIC ─────────────────────────────────────────────────────────────────────┐
│ │
│ Worker: w-alpha [Esc] Back │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ Status: ● Running │ │
│ │ Task: bd-1847 "Implement auth flow" │ │
│ │ Duration: 2m 34s │ │
│ │ Events: 47 │ │
│ │ Errors: 0 │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
│ │
│ Worker Log │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ 14:32:07 INFO Tool call: Edit src/auth/login.ts │ │
│ │ old_string: "function login() {" │ │
│ │ new_string: "async function login(): Promise<User> {" │ │
│ │ 14:32:01 INFO Tool call: Read src/auth/types.ts │ │
│ │ 14:31:55 DEBUG Analyzing dependencies... │ │
│ │ 14:31:47 INFO Tool call: Glob **/*.ts │ │
│ │ Found 23 files │ │
│ │ 14:31:42 INFO Starting task bd-1847 │ │
│ │ Task: "Implement auth flow" │ │
│ │ Priority: P1 │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
│ │
│ [j/k] Scroll [/] Search [Esc] Back to overview │
└──────────────────────────────────────────────────────────────────────────────┘
Web Mode (fabric web)
Live browser dashboard served on localhost:
- Worker Overview: Cards showing each worker's current state
- Activity Feed: Real-time log stream
- Timeline: Visual representation of worker activity
Features:
- WebSocket-powered real-time updates
- Filter and search controls
- Responsive layout
- Auto-reconnect on connection loss
Web Mockup
┌─────────────────────────────────────────────────────────────────────────────────┐
│ ◉ FABRIC ┌─────────────────────────┐ │
│ Flow Analysis & Bead Reporting Interface Console │ 🔍 Search... │ │
│ └─────────────────────────┘ │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 4 Active │ │ 12 Completed │ │ 0 Errors │ │
│ │ Workers │ │ Today │ │ Last Hour │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
│ Workers │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ┌─────────────────────┐ ┌─────────────────────┐ │ │
│ │ │ ● w-alpha │ │ ● w-bravo │ │ │
│ │ │ │ │ │ │ │
│ │ │ bd-1847 │ │ bd-1852 │ │ │
│ │ │ Implement auth flow │ │ Fix login validation│ │ │
│ │ │ │ │ │ │ │
│ │ │ ██████████░░ 2m 34s │ │ █████░░░░░░ 1m 12s │ │ │
│ │ └─────────────────────┘ └─────────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────┐ ┌─────────────────────┐ │ │
│ │ │ ○ w-charlie │ │ ● w-delta │ │ │
│ │ │ │ │ │ │ │
│ │ │ Idle │ │ bd-1849 │ │ │
│ │ │ │ │ Add unit tests │ │ │
│ │ │ │ │ │ │ │
│ │ │ Ready for work │ │ ██░░░░░░░░░ 45s │ │ │
│ │ └─────────────────────┘ └─────────────────────┘ │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
│ │
│ Activity Feed Filter: [All levels ▾] │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 14:32:07 ● w-alpha INFO │ │
│ │ Tool call: Edit src/auth/login.ts │ │
│ │ ────────────────────────────────────────────────────────────────────── │ │
│ │ 14:32:05 ● w-bravo DEBUG │ │
│ │ Reading file: src/validators/index.ts │ │
│ │ ────────────────────────────────────────────────────────────────────── │ │
│ │ 14:32:04 ● w-delta INFO │ │
│ │ Starting task bd-1849 │ │
│ │ ────────────────────────────────────────────────────────────────────── │ │
│ │ 14:31:58 ● w-bravo WARN │ │
│ │ Retry attempt 2/3 for API call │ │
│ │ ────────────────────────────────────────────────────────────────────── │ │
│ │ 14:31:52 ○ w-charlie INFO │ │
│ │ Task bd-1845 completed (duration: 4m 12s) │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
│ │
│ Timeline (last 10 minutes) │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ 14:22 14:24 14:26 14:28 14:30 14:32 │ │
│ │ alpha ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░███████████████████ │ │
│ │ bravo ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░████████████ │ │
│ │ charlie████████████████████████████████████████░░░░░░░░░░░░ │ │
│ │ delta ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░███████ │ │
│ └──────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ● Connected FABRIC v0.1.0 │
└─────────────────────────────────────────────────────────────────────────────────┘
Web Worker Detail Modal (when worker card clicked)
┌─────────────────────────────────────────────────────────────────────────────────┐
│ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ [✕] │ │
│ │ Worker: w-alpha │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ ● Running │ │ 47 Events │ │ 0 Errors │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ │ │
│ │ Current Task │ │
│ │ ┌───────────────────────────────────────────────────────────┐ │ │
│ │ │ bd-1847 │ │ │
│ │ │ Implement auth flow │ │ │
│ │ │ Duration: 2m 34s │ │ │
│ │ └───────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ Recent Activity │ │
│ │ ┌───────────────────────────────────────────────────────────┐ │ │
│ │ │ 14:32:07 INFO Edit src/auth/login.ts │ │ │
│ │ │ 14:32:01 INFO Read src/auth/types.ts │ │ │
│ │ │ 14:31:55 DEBUG Analyzing dependencies... │ │ │
│ │ │ 14:31:47 INFO Glob **/*.ts (23 files) │ │ │
│ │ │ 14:31:42 INFO Starting task bd-1847 │ │ │
│ │ └───────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
CLI Interface
# TUI - live terminal dashboard
fabric tui # Read from ~/.needle/logs/
fabric tui --source /path/to/logs/ # Read from specific path
fabric tui --worker w-abc123 # Filter to one worker
# Web - live browser dashboard
fabric web # Serve on http://localhost:3000
fabric web --port 8080 # Custom port
fabric web --source /path/to/logs/ # Read from specific path
# Simple log streaming (parsed + formatted, also live)
fabric logs # Stream parsed logs to stdout
fabric logs --level error # Filter by level
fabric logs --worker w-abc123 # Filter by worker
Architecture
┌─────────────────────────────────────────────────────────────┐
│ FABRIC │
├─────────────────────────────────────────────────────────────┤
│ ┌──────────┐ ┌─────────┐ ┌───────────────────────┐ │
│ │ Log │───▶│ Parser │───▶│ Display Renderer │ │
│ │ Tailer │ │ │ │ (TUI or Web) │ │
│ └──────────┘ └─────────┘ └───────────────────────┘ │
│ │ │ │
│ ~/.needle/logs/ Terminal or │
│ (tail -f style) localhost:3000 │
└─────────────────────────────────────────────────────────────┘
Components
- Log Tailer: Continuously read new lines from log files (like
tail -f) - Parser: Parse JSON log lines into structured events
- Display Renderer: Update TUI or push to WebSocket clients
Implementation Phases
Phase 1: Core Infrastructure
- Log tailer that watches
~/.needle/logs/ - JSON line parser
- Event emitter for parsed events
Phase 2: TUI Display
- Worker list panel
- Live log stream panel
- Worker detail panel
- Keyboard controls and filtering
Phase 3: Web Display
- HTTP server with WebSocket support
- Real-time event streaming to browser
- React/Svelte dashboard UI
- Worker cards and activity feed
Technology Options
Log Tailer
- Node.js
fs.watch+ readline - Go
fsnotify+ bufio tailmodule (Node.js)
TUI
- blessed (Node.js) - Full-featured terminal UI
- ink (Node.js) - React for CLIs
- bubbletea (Go) - Elegant TUI framework
Web
- Express + ws (Node.js) - Simple HTTP + WebSocket
- Fastify (Node.js) - Fast HTTP server
- Fiber (Go) - Express-style for Go
- React/Svelte - Frontend framework
Example Usage
# Start TUI dashboard
fabric tui
# Start web dashboard
fabric web
# Then open http://localhost:3000 in browser
# Stream logs to terminal (simple mode)
fabric logs --follow
Non-Goals
- ❌ Static report generation
- ❌ Storing metrics or historical data
- ❌ Database or persistence layer
- ❌ Alerting system
FABRIC is a live display. It shows what NEEDLE is doing right now.
Status: Planning phase Last Updated: 2026-03-02