Summary

Architecture

                              +------------------+
                              |   Vercel App     |
                              |   (Dashboard)    |
                              +--------+---------+
                                       |
                             HTTPS (Vercel proxy)
                                       |
                                       v
+------------------+          +------------------+          +------------------+
|  Telegram Bot    |   HTTP   |   KANBAN API     |  SQL     |    Supabase      |
|  (Commander)     +-------->+   :5016           +-------->+  kanban_tasks    |
+------------------+          |                  |          |  kanban_columns  |
                              |  /v1/tasks       |          |  kanban_history  |
+------------------+   HTTP   |  /v1/columns     |          |  ralph_queue     |
|  Claude Sessions +-------->+  /v1/dispatch    |          +------------------+
|  (rituals, CLI)  |          |  /v1/export      |
+------------------+          |  /v1/import      |
                              +--------+---------+
                                       |
                              +--------v---------+
                              |  Task Board.md   |
                              |  (generated       |
                              |   export, cron)   |
                              +------------------+

Components

1. Kanban API Server

• Type: Express/TypeScript standalone process
• Location: services/kanban-api/
• Port: 5016
• Dependencies: Supabase (service-role key for RLS bypass), no other Forge services required at runtime
• Systemd: forge-kanban-api.service

Endpoints

Data Model

Three tables in Supabase with RLS policies, views, and triggers:

kanban_columns

CREATE TABLE IF NOT EXISTS kanban_columns (
  id          TEXT PRIMARY KEY,         -- 'today', 'soon', 'later', 'waiting', 'inbox', 'done', 'agenda'
  label       TEXT NOT NULL,            -- 'Today', 'Soon', 'Later', etc.
  position    INT NOT NULL DEFAULT 0,   -- display order
  description TEXT,                     -- section description
  color       TEXT,                     -- hex color for UI
  is_terminal BOOLEAN DEFAULT FALSE,    -- 'done' column = terminal
  created_at  TIMESTAMPTZ DEFAULT NOW()
);

-- Seed default columns
INSERT INTO kanban_columns (id, label, position, description, is_terminal) VALUES
  ('today',   'Today',   0, 'Active focus for today. Max 3-5 items.', FALSE),
  ('soon',    'Soon',    1, 'Next 2-3 days.', FALSE),
  ('later',   'Later',   2, 'Backlog, no urgency.', FALSE),
  ('waiting', 'Waiting', 3, 'Blocked on someone/something external.', FALSE),
  ('inbox',   'Inbox',   4, 'Uncategorized captures. Triaged during /start.', FALSE),
  ('done',    'Done',    5, 'Completed tasks with dates. Newest at top.', TRUE)
ON CONFLICT (id) DO NOTHING;

kanban_tasks

CREATE TABLE IF NOT EXISTS kanban_tasks (
  id            BIGSERIAL PRIMARY KEY,
  title         TEXT NOT NULL,
  column_id     TEXT NOT NULL REFERENCES kanban_columns(id) DEFAULT 'inbox',
  position      INT NOT NULL DEFAULT 0,
  priority      TEXT NOT NULL DEFAULT 'normal'
                CHECK (priority IN ('urgent', 'medium', 'normal')),
  project       TEXT,                              -- 'FORGE', 'HC', 'MASTERY', etc.
  tags          TEXT[] DEFAULT '{}',
  description   TEXT,
  due_date      DATE,
  assignee      TEXT,                              -- 'jason', 'ralph', 'forge'
  source        TEXT DEFAULT 'manual',             -- 'manual', 'import', 'telegram', etc.
  agenda_person TEXT,                              -- for agenda items
  agenda_topic  TEXT,                              -- for agenda items
  completed_at  TIMESTAMPTZ,
  deleted_at    TIMESTAMPTZ,                       -- soft delete
  ralph_queue_id BIGINT REFERENCES ralph_queue(id),
  metadata      JSONB DEFAULT '{}',
  created_at    TIMESTAMPTZ DEFAULT NOW(),
  updated_at    TIMESTAMPTZ DEFAULT NOW()
);

-- Indexes for common query patterns
CREATE INDEX idx_kanban_tasks_column   ON kanban_tasks(column_id, position);
CREATE INDEX idx_kanban_tasks_project  ON kanban_tasks(project);
CREATE INDEX idx_kanban_tasks_priority ON kanban_tasks(priority);
CREATE INDEX idx_kanban_tasks_active   ON kanban_tasks(column_id) WHERE deleted_at IS NULL;
CREATE INDEX idx_kanban_tasks_done     ON kanban_tasks(completed_at DESC) WHERE column_id = 'done';

kanban_history

CREATE TABLE IF NOT EXISTS kanban_history (
  id          BIGSERIAL PRIMARY KEY,
  task_id     BIGINT NOT NULL REFERENCES kanban_tasks(id) ON DELETE CASCADE,
  action      TEXT NOT NULL CHECK (action IN (
                'created', 'updated', 'moved', 'completed', 'reopened',
                'deleted', 'dispatched', 'imported'
              )),
  from_column TEXT,
  to_column   TEXT,
  changes     JSONB DEFAULT '{}',      -- field-level diff
  actor       TEXT DEFAULT 'system',   -- 'jason', 'dashboard', 'telegram', 'ralph'
  created_at  TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_kanban_history_task ON kanban_history(task_id, created_at DESC);
CREATE INDEX idx_kanban_history_time ON kanban_history(created_at DESC);

Views

-- Active board: non-deleted tasks ordered by column + position
CREATE OR REPLACE VIEW v_kanban_board AS
SELECT t.id, t.title, t.column_id, t.position, t.priority,
  t.project, t.tags, t.description, t.due_date, t.assignee,
  t.agenda_person, t.agenda_topic, t.completed_at,
  t.ralph_queue_id, t.source, t.metadata, t.created_at, t.updated_at,
  c.label AS column_label, c.position AS column_position
FROM kanban_tasks t
JOIN kanban_columns c ON c.id = t.column_id
WHERE t.deleted_at IS NULL
ORDER BY c.position, t.position, t.created_at DESC;

-- Column summary with counts
CREATE OR REPLACE VIEW v_kanban_summary AS
SELECT c.id AS column_id, c.label, c.position,
  COUNT(t.id) FILTER (WHERE t.deleted_at IS NULL) AS task_count,
  COUNT(t.id) FILTER (WHERE t.deleted_at IS NULL AND t.priority = 'urgent') AS urgent_count
FROM kanban_columns c
LEFT JOIN kanban_tasks t ON t.column_id = c.id
GROUP BY c.id, c.label, c.position
ORDER BY c.position;

-- Daily completion velocity (last 30 days)
CREATE OR REPLACE VIEW v_kanban_velocity AS
SELECT DATE(completed_at) AS day, COUNT(*) AS completed
FROM kanban_tasks
WHERE completed_at IS NOT NULL
  AND completed_at > NOW() - INTERVAL '30 days'
  AND deleted_at IS NULL
GROUP BY DATE(completed_at)
ORDER BY day DESC;

-- Eisenhower matrix view
CREATE OR REPLACE VIEW v_kanban_eisenhower AS
SELECT t.id, t.title, t.priority, t.project, t.tags, t.column_id,
  CASE
    WHEN t.column_id = 'today' AND t.priority = 'urgent' THEN 'q1'
    WHEN t.column_id = 'today' THEN 'q2'
    WHEN t.column_id = 'soon' AND t.priority = 'urgent' THEN 'q1'
    WHEN t.column_id = 'soon' AND t.priority = 'medium' THEN 'q2'
    WHEN t.column_id = 'soon' THEN 'q3'
    ELSE 'q4'
  END AS quadrant
FROM kanban_tasks t
WHERE t.deleted_at IS NULL AND t.completed_at IS NULL
  AND t.column_id NOT IN ('done', 'waiting', 'inbox')
ORDER BY t.position;

RLS Policies

Integration Points

Dashboard (Vercel App)

• Read path: Dashboard queries v_kanban_board view via Supabase anon key (direct, no VPS proxy needed for reads)
• Write path: Dashboard calls VPS proxy /api/vps/kanban/* which forwards to :5016/v1/*
• Realtime: Supabase realtime subscriptions on kanban_tasks for live updates across tabs/sessions
• Backward compat: Existing taskboard-parser.ts and taskboard-actions.ts become deprecated. New lib/kanban-client.ts replaces them.

Telegram Bot (Commander)

• /task command — POST /v1/tasks with text parsing (e.g., /task [!] [FORGE] Fix the dashboard)
• /done command — quick-complete from Telegram
• /today command — GET /v1/tasks?column=today formatted for Telegram

Ralph (Autonomous Agent)

Priority mapping: Kanban urgent → ralph_queue priority 20, medium → 50, normal → 70

Rituals (/start, /sync, /wrap-up)

• /start reads from API: GET /v1/tasks?column=today
• /sync uses GET /v1/stats for progress summary
• /wrap-up calls POST /v1/export/write to ensure Task Board.md is current
• No immediate change needed — rituals can keep reading Task Board.md since the export cron keeps it in sync

Memory & Context

• context/SESSION-QUEUE.md — remains separate (session-scoped, not task-scoped)
• context/JASON-DEPS.md — stays as-is for Phase 1; could become a filtered view later
• Scratchpad.md — remains separate (ephemeral capture, different semantics)

Service Convention Compliance

• GET /health — returns { status, service, version, tasks, last_export }
• GET /docs — returns services/kanban-api/CLAUDE.md as plain text
• Registered in config/services.json with port 5016
• Systemd unit file: services/kanban-api/forge-kanban-api.service
• Express/TypeScript (matches existing service patterns)
• Environment variables: SUPABASE_URL, SUPABASE_SERVICE_KEY, SERVICE_PORT
• All writes via service-role key (RLS bypass). Dashboard reads via anon key.

File Structure

services/kanban-api/
  CLAUDE.md              # Service docs (served at GET /docs)
  package.json           # Dependencies: express, @supabase/supabase-js
  tsconfig.json
  src/
    server.ts            # Express app, routes, health, docs
    routes/
      tasks.ts           # CRUD for /v1/tasks
      columns.ts         # /v1/columns
      dispatch.ts        # /v1/dispatch (Ralph integration)
      export.ts          # /v1/export, /v1/import
      stats.ts           # /v1/stats
    lib/
      supabase.ts        # Supabase client (service-role)
      exporter.ts        # Generate Task Board.md from DB
      importer.ts        # Parse Task Board.md into DB rows
      history.ts         # Write kanban_history entries
    cron/
      export-sync.ts     # setInterval that writes Task Board.md
  scripts/
    migrate.ts           # One-time migration CLI
    setup.sql            # SQL from Data Model section
  forge-kanban-api.service  # systemd unit file

Build Phases

Cost Estimate

Risks & Mitigations

Open Questions