FABRIC/docs/plan.md

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

1. Live Display: Real-time visualization of NEEDLE worker activity
2. Dual Interface: TUI for terminal users, web app for browser users
3. 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

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

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

1. Log Tailer: Continuously read new lines from log files (like tail -f)
2. Parser: Parse JSON log lines into structured events
3. 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
• tail module (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