Session Coordination Platform - v0.dev Specification

Project: JG-260110-OSM-Claude-code-a9af9be8-df86-4285-a367-api

Build a centralized Session Coordination Platform for managing Claude Code sessions across machines and projects.

1. Technology Stack

Required Services

• Database: Neon Postgres (serverless)
• Cache/Search: Upstash Redis (with vector search)
• Runtime: Vercel Edge Functions / Next.js API Routes
• Frontend: Next.js 14+ App Router with shadcn/ui
• Auth: Clerk or NextAuth (optional, for multi-user)

Environment Variables

DATABASE_URL=postgres://...@neon.tech/sessions
UPSTASH_REDIS_REST_URL=https://...upstash.io
UPSTASH_REDIS_REST_TOKEN=...

2. Database Schema (Neon Postgres)

-- Sessions table: core session metadata
CREATE TABLE sessions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    session_id TEXT UNIQUE NOT NULL,
    directory_name TEXT NOT NULL,
    launch_path TEXT NOT NULL,
    machine_id TEXT,
    user_id TEXT,
    created_at TIMESTAMPTZ,
    updated_at TIMESTAMPTZ,
    indexed_at TIMESTAMPTZ DEFAULT NOW(),
    message_count INTEGER DEFAULT 0,
    input_tokens INTEGER DEFAULT 0,
    output_tokens INTEGER DEFAULT 0,
    status TEXT DEFAULT 'active',
    tags TEXT[],
    metadata JSONB DEFAULT '{}'
);

-- Messages table: conversation content
CREATE TABLE messages (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    session_id TEXT REFERENCES sessions(session_id) ON DELETE CASCADE,
    message_index INTEGER NOT NULL,
    role TEXT NOT NULL, -- 'user', 'assistant', 'system'
    content TEXT,
    thinking TEXT, -- Claude thinking tokens
    timestamp TIMESTAMPTZ,
    tokens_input INTEGER DEFAULT 0,
    tokens_output INTEGER DEFAULT 0,
    tools_used TEXT[],
    metadata JSONB DEFAULT '{}',
    UNIQUE(session_id, message_index)
);

-- Forks table: parent-child relationships
CREATE TABLE forks (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    parent_session_id TEXT REFERENCES sessions(session_id),
    child_session_id TEXT REFERENCES sessions(session_id),
    fork_point_index INTEGER, -- message index where fork occurred
    fork_marker TEXT, -- the resume marker detected
    created_at TIMESTAMPTZ DEFAULT NOW(),
    metadata JSONB DEFAULT '{}',
    UNIQUE(parent_session_id, child_session_id)
);

-- Tags table: for categorization
CREATE TABLE tags (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    session_id TEXT REFERENCES sessions(session_id) ON DELETE CASCADE,
    name TEXT NOT NULL,
    color TEXT DEFAULT '#3b82f6',
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Narrative beats table: for structural tension chart integration
CREATE TABLE narrative_beats (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    session_id TEXT REFERENCES sessions(session_id),
    chart_id TEXT, -- structural tension chart reference
    beat_type TEXT, -- 'character_arc', 'thematic_analysis', 'emotional_classification'
    title TEXT,
    description TEXT,
    analysis_result JSONB,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Indexes for performance
CREATE INDEX idx_sessions_launch_path ON sessions(launch_path);
CREATE INDEX idx_sessions_created ON sessions(created_at DESC);
CREATE INDEX idx_sessions_machine ON sessions(machine_id);
CREATE INDEX idx_messages_session ON messages(session_id);
CREATE INDEX idx_forks_parent ON forks(parent_session_id);
CREATE INDEX idx_forks_child ON forks(child_session_id);

-- Full-text search
CREATE INDEX idx_messages_content_gin ON messages USING GIN(to_tsvector('english', content));

3. API Routes (Next.js)

Session Management

// app/api/sessions/route.ts
// GET /api/sessions - List sessions with filters
// POST /api/sessions - Upload/sync session from local machine

// app/api/sessions/[id]/route.ts
// GET /api/sessions/:id - Get session details
// PUT /api/sessions/:id - Update session metadata
// DELETE /api/sessions/:id - Delete session

// app/api/sessions/[id]/messages/route.ts
// GET /api/sessions/:id/messages - Get messages with pagination

// app/api/sessions/[id]/export/route.ts
// GET /api/sessions/:id/export?format=md|json - Export session

Fork Management

// app/api/forks/route.ts
// GET /api/forks - Get fork graph
// POST /api/forks - Create fork relationship

// app/api/forks/tree/[id]/route.ts
// GET /api/forks/tree/:id - Get fork tree for session

Search

// app/api/search/route.ts
// GET /api/search?q=query&path=filter&since=date
// Full-text search across all sessions

Sync (from local machine)

// app/api/sync/route.ts
// POST /api/sync - Bulk upload sessions from local ~/.claude/projects/
// PUT /api/sync - Incremental sync (new sessions only)

4. Upstash Redis Patterns

Session Cache

// Cache recent session metadata
SET session:{session_id} {metadata_json} EX 3600

// Recent sessions list per machine
LPUSH machine:{machine_id}:recent {session_id}
LTRIM machine:{machine_id}:recent 0 99

// Search index (using Upstash Vector)
// Store message embeddings for semantic search

Fork Graph Cache

// Cache fork relationships
HSET forks:{session_id} children {json_array}
HSET forks:{session_id} parent {parent_id}

Real-time Updates

// Pub/sub for live session updates
PUBLISH session:updates {session_id, event_type, data}

5. Frontend Pages

Dashboard (/)

• Grid of recent sessions
• Filter by: path, date range, machine, tags
• Quick stats: total sessions, tokens used, fork count

Session Detail (/session/[id])

• Full conversation view with syntax highlighting
• Message navigation sidebar
• Export buttons (Markdown, JSON)
• Tags editor
• Fork tree visualization

Fork Tree (/forks)

• D3.js or react-flow visualization
• Interactive graph showing all fork relationships
• Click to navigate to session
• Color-coded by status/date

Search (/search)

• Full-text search input
• Results with context snippets
• Filter panel (path, date, role)

Sync Status (/sync)

• Machine registration
• Last sync timestamp
• Manual sync trigger
• Sync history

6. CLI Sync Tool

Create a companion CLI that runs on local machines:

# Install
npm install -g @narintel/session-sync

# Configure
session-sync config --api-url https://your-app.vercel.app --api-key xxx

# Full sync
session-sync push

# Incremental sync (new sessions only)
session-sync push --incremental

# Watch mode (sync on change)
session-sync watch

CLI Implementation Hints

// Uses existing SessionMetadataExtractor logic
// Uploads to POST /api/sync endpoint
// Stores machine_id in ~/.session-sync/config.json
// Tracks last sync time for incremental updates

7. Key Components

SessionCard

<SessionCard
  session={session}
  showPath
  showTokens
  showForkBadge
  onClick={navigateToDetail}
/>

ForkTree (react-flow)

<ForkTreeVisualization
  sessions={sessions}
  forks={forks}
  selectedId={currentSession}
  onNodeClick={handleSessionSelect}
/>

SearchResults

<SearchResults
  query={query}
  results={results}
  highlightMatches
  showContext
/>

MessageView

<MessageView
  message={message}
  showThinking={showThinkingTokens}
  showTokenCounts
  syntaxHighlight
/>

8. Integration Points

Structural Tension Charts (MCP)

The platform should expose data compatible with mcp_narintel-char_* tools:

// GET /api/narrative/charts
// Returns structural tension charts derived from session analysis

// POST /api/narrative/beats
// Create narrative beat from session analysis
{
  "session_id": "xxx",
  "chart_id": "chart_123",
  "beat_type": "character_arc_analysis",
  "analysis_result": {...}
}

Three-Universe Processor

Sessions can be analyzed through three lenses:

// POST /api/analyze/three-universe
{
  "session_id": "xxx",
  "event_type": "session_summary"
}
// Returns: engineer/ceremony/story_engine perspectives

9. Sample Data Structures

Session Object

interface Session {
  id: string;
  session_id: string;
  directory_name: string;
  launch_path: string;
  machine_id: string;
  created_at: string;
  updated_at: string;
  message_count: number;
  input_tokens: number;
  output_tokens: number;
  status: 'active' | 'completed' | 'archived';
  tags: string[];
  forks: {
    parent?: string;
    children: string[];
  };
}

Fork Graph

interface ForkGraph {
  nodes: {
    id: string;
    label: string;
    created_at: string;
    status: string;
  }[];
  edges: {
    source: string;
    target: string;
    fork_point: number;
  }[];
}

Search Result

interface SearchResult {
  session_id: string;
  message_index: number;
  role: string;
  content_snippet: string;
  timestamp: string;
  highlight_ranges: [number, number][];
}

10. Deployment Checklist

1. Create Neon Postgres database
2. Run schema migrations
3. Create Upstash Redis instance
4. Deploy Next.js to Vercel
5. Configure environment variables
6. Test API endpoints
7. Build CLI sync tool
8. Document setup for users

11. Future Enhancements

• Semantic search: Use Upstash Vector for embedding-based search
• Session replay: Step through conversation history
• Collaboration: Share sessions with team members
• Analytics: Token usage trends, session patterns
• Webhooks: Notify on new session creation
• MCP Server: Expose as Model Context Protocol server for agent-to-agent use

Specification version: 1.0 Created: 2026-01-16 For: v0.dev implementation agent