Files

T

nntrivi2001 d2fc4a4701 feat: Claude Code Monitor — lanes, pipelines and a merged workspace

Internal SmartGift build of a Claude Code monitoring dashboard.

Lanes: a durable unit of parallel agent work, one per working directory,
tracked across session restarts. Managed lanes are git worktrees the
dashboard provisions and can reset or remove behind a three-check destroy
guard and a counted preflight; adopted lanes are directories you already
own and are never destroyable.

Pipelines: a lane moves through pipeline stages. A stage the agent declares
with evidence renders green; a stage inferred from the tool-event stream
renders dashed amber and never counts as done. Detection is forward-only
within a 30-minute window, and never writes the declared stage.

Workspace: one page at /run with a lane grid, the selected lane's pipeline,
and a full Claude console behind a disclosure.

2026-07-30 14:05:51 +07:00

13 KiB

Raw Blame History

Documentation Index

Comprehensive documentation for the Agent Dashboard project.

Quick Links

Architecture Overview - System design and technical reference
I18N Architecture - Internationalization architecture and usage guide
CLI Reference - The ccam terminal CLI: every command, discovery, safety model
Setup Guide - Installation and configuration
Installation - Detailed installation instructions

Documentation Sections

📘 Core Documentation

graph TB
    Start[Start Here] --> Setup[SETUP.md<br/>Installation & Config]
    Start --> Architecture[ARCHITECTURE.md<br/>System Design]
    
    Setup --> Client[Client README<br/>React UI docs]
    Setup --> Server[Server README<br/>Backend docs]
    
    Architecture --> API[API.md<br/>REST & WebSocket]
    Architecture --> Database[DATABASE.md<br/>Schema reference]
    Architecture --> Hooks[HOOKS.md<br/>Hook system integration]
    Architecture --> MCP[MCP.md<br/>MCP server integration]
    
    Setup --> Deploy[DEPLOYMENT.md<br/>Production deployment]
    
    style Start fill:#3B82F6
    style Setup fill:#10B981
    style Architecture fill:#F59E0B

📋 Documentation Catalog

Document	Description	Audience
client/README.md	React frontend architecture, components, state management	Frontend developers
server/README.md	Express backend, database, WebSocket, API	Backend developers
API.md	REST API endpoints (sessions, agents, events, stats, analytics, hooks, pricing, workflows, settings, import history, cc-config, run), WebSocket protocol (including `run_stream` / `run_status` / `run_input_ack` for the Run page)	Integration developers
DATABASE.md	SQLite schema, queries, performance	Database administrators
HOOKS.md	Claude Code hook system integration	Hook developers
MCP.md	MCP server setup and tool reference	MCP integrators
DEPLOYMENT.md	Production deployment strategies	DevOps engineers
I18N.md	Language architecture, locale strategy, and rollout checklist	Frontend and product teams
CLI.md	`ccam` command reference — monitoring, browsing, insights, alerts, pricing, import, administration	Terminal users and CI scripting
monitoring/README.md	Prometheus + Grafana stack (`npm run monitoring:up` or Docker)	DevOps / observability

Getting Started

For New Users

graph LR
    A[New to Project] --> B[Read SETUP.md]
    B --> C[Install Dependencies]
    C --> D[Run npm run dev]
    D --> E[Open localhost:5173]
    
    style A fill:#3B82F6
    style E fill:#10B981

Quick Start:

Read SETUP.md
Run npm run setup
Run npm run dev
Open browser to http://localhost:5173

For Frontend Developers

graph TB
    FE[Frontend Developer] --> ClientDocs[client/README.md]
    ClientDocs --> Components[Component Architecture]
    ClientDocs --> State[State Management]
    ClientDocs --> WebSocket[WebSocket Integration]
    
    style FE fill:#61DAFB

Key Documents:

client/README.md - Complete frontend guide
API.md - WebSocket protocol
Component source: client/src/components/

For Backend Developers

graph TB
    BE[Backend Developer] --> ServerDocs[server/README.md]
    ServerDocs --> Routes[API Routes]
    ServerDocs --> DB[Database Design]
    ServerDocs --> WS[WebSocket Server]
    
    style BE fill:#339933

Key Documents:

server/README.md - Complete backend guide
DATABASE.md - Schema and queries
HOOKS.md - Hook processing
API source: server/routes/

For DevOps Engineers

graph TB
    DevOps[DevOps Engineer] --> Deploy[DEPLOYMENT.md]
    Deploy --> Docker[Docker Setup]
    Deploy --> PM2[PM2 Process Manager]
    Deploy --> Cloud[Cloud Deployment]
    Deploy --> Monitoring[Monitoring & Logging]
    
    style DevOps fill:#F59E0B

Key Documents:

DEPLOYMENT.md - Complete deployment guide
DATABASE.md - Backup strategies
server/README.md - Performance tuning

For Integration Developers

graph TB
    Integration[Integration Developer] --> API[API.md]
    API --> REST[REST Endpoints]
    API --> WebSocket[WebSocket Events]
    
    Integration --> MCP[MCP.md]
    MCP --> Tools[MCP Tools]
    MCP --> Config[Client Configuration]
    
    style Integration fill:#8B5CF6

Key Documents:

API.md - Complete API reference
MCP.md - MCP server integration
HOOKS.md - Custom hook integration

Architecture Overview

System Components

graph TB
    subgraph "Frontend"
        React[React + TypeScript<br/>Vite + Tailwind]
    end
    
    subgraph "Backend"
        Express[Express Server<br/>Node.js 20+]
        DB[(SQLite Database)]
        WS[WebSocket Server]
    end
    
    subgraph "Integration"
        Hooks[Claude Code Hooks]
        MCP[MCP Server]
    end
    
    subgraph "Clients"
        Browser[Web Browser]
        Claude[Claude Desktop]
        Custom[Custom Clients]
    end
    
    Browser --> React
    React -->|HTTP/WS| Express
    Express --> DB
    Express --> WS
    
    Hooks -->|HTTP POST| Express
    
    Claude -->|stdio| MCP
    MCP -->|HTTP| Express
    Custom -->|HTTP| Express
    
    style React fill:#61DAFB
    style Express fill:#000000,color:#fff
    style DB fill:#003B57,color:#fff
    style MCP fill:#0f766e

Technology Stack:

Layer	Technology
Frontend	React 18, TypeScript 5.7, Vite 6, Tailwind CSS
Backend	Node.js 20+, Express 4.21, WebSocket
Database	SQLite 3 (better-sqlite3 or node:sqlite)
Integration	Claude Code Hooks, MCP Server

Internationalization Support (en/zh/vi/ko)

flowchart LR
    A["User language preference<br/>en / zh / vi / ko"] --> B["i18next detector<br/>localStorage + navigator"]
    B --> C["Namespace JSON resources"]
    C --> D["React useTranslation hooks"]
    D --> E["Localized UI + a11y labels"]
    E --> F["Locale-aware date/number formatting"]
    F --> G["formatModelName() — human-friendly model display"]

Supported language codes are explicitly en, zh, and vi. Use I18N.md for architecture details, naming conventions, language switching flow, localization behavior, and rollout guidance.

Feature Documentation

Real-Time Updates

sequenceDiagram
    participant Hook as Claude Code Hook
    participant Server as Dashboard Server
    participant DB as SQLite
    participant WS as WebSocket
    participant Client as Browser
    
    Hook->>Server: POST /hooks/post-tool-use
    Server->>DB: Update data
    DB-->>Server: Success
    Server->>WS: Broadcast event
    WS->>Client: { type: 'tool.executed', data }
    Client->>Client: Update UI
    
    Note over Client: No polling required!

Documentation:

Pricing System

graph TB
    Model[Model Name] --> Match[Pattern Matching]
    Match --> Custom{Custom<br/>Rule?}
    
    Custom -->|Yes| UseCustom[Use Custom Pricing]
    Custom -->|No| UseDefault[Use Default Pricing]
    
    UseCustom --> Calculate[Calculate Cost]
    UseDefault --> Calculate
    
    Calculate --> Result[input_cost + output_cost]
    
    style Calculate fill:#10B981

Documentation:

Hook System

graph LR
    Claude[Claude Code] -->|stdin| Hook[Hook Script]
    Hook -->|exec| Handler[hook-handler.js]
    Handler -->|HTTP POST| Server[Dashboard Server]
    Server --> DB[(Database)]
    Server --> WS[WebSocket]
    
    style Hook fill:#F59E0B
    style Handler fill:#10B981

Documentation:

API Documentation

REST API Summary

Endpoint	Method	Description
`/api/sessions`	GET	List sessions
`/api/sessions/:id`	GET	Get session
`/api/sessions/:id/agents`	GET	List session agents
`/api/agents/:id`	GET	Get agent
`/api/agents/:id/tools`	GET	List agent tools
`/api/pricing`	GET	List pricing rules
`/api/pricing`	POST	Create pricing rule
`/api/pricing/:pattern`	DELETE	Delete pricing rule

Full Reference: API.md

WebSocket Events

Event Type	Triggered By
`session.created`	SessionStart hook
`session.updated`	Any session update
`agent.created`	New agent started
`agent.updated`	Agent status/cost change
`tool.executed`	Tool execution completed
`notification.received`	System notification

Full Reference: API.md

Database Schema

Entity Relationships

erDiagram
    sessions ||--o{ agents : "has many"
    agents ||--o{ tool_executions : "has many"
    sessions ||--o{ notifications : "has many"
    
    sessions {
        text session_id PK
        text model
        text status
        real total_cost
        datetime updated_at
    }
    
    agents {
        text agent_id PK
        text session_id FK
        text agent_type
        text status
        text current_tool
        int input_tokens
        int output_tokens
        real cost
    }

Full Reference: DATABASE.md

Deployment Options

graph TB
    subgraph "Development"
        Dev[npm run dev<br/>Hot reload]
    end
    
    subgraph "Production"
        Docker[Docker Compose<br/>Containerized]
        PM2[PM2<br/>Process manager]
        Systemd[Systemd Service<br/>Linux systems]
        Cloud[Cloud Platform<br/>AWS, Azure, GCP]
    end
    
    Dev -.->|Build| Docker
    Dev -.->|Build| PM2
    Dev -.->|Build| Systemd
    Dev -.->|Build| Cloud
    
    style Dev fill:#3B82F6
    style Docker fill:#2496ED
    style PM2 fill:#10B981
    style Systemd fill:#F59E0B
    style Cloud fill:#8B5CF6

Full Reference: DEPLOYMENT.md

Performance Metrics

Benchmarks

Metric	Target	Actual
Hook processing	< 100ms	~70ms
API response time	< 50ms	~30ms
WebSocket latency	< 10ms	~5ms
Database query	< 10ms	~5ms
Session list (50)	< 20ms	~10ms

Optimization Details:

Contributing

Development Workflow

graph LR
    Fork[Fork Repository] --> Clone[Clone Locally]
    Clone --> Branch[Create Feature Branch]
    Branch --> Code[Write Code]
    Code --> Test[Run Tests]
    Test --> Commit[Commit Changes]
    Commit --> Push[Push to Fork]
    Push --> PR[Create Pull Request]
    
    style Fork fill:#3B82F6
    style PR fill:#10B981

Before submitting:

Run tests: npm test (server node --test + client Vitest, including per-screen render snapshots — regenerate intentional UI changes with cd client && npx vitest run -u)
Check formatting: npm run format:check
Build: npm run build
Update docs if needed

Support & Resources

Getting Help

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: This folder

Additional Resources

License

Summary

This documentation covers:

✅ Complete architecture - Frontend, backend, database, integrations
✅ API reference - REST endpoints, WebSocket events
✅ Deployment guides - Docker, PM2, systemd, cloud
✅ Performance tuning - Database, server, client optimizations
✅ Integration guides - Hooks, MCP, custom clients
✅ Internationalization - Language resources, switching flow, locale formatting, rollout checklist
✅ Development guides - Setup, testing, contributing

Start with: SETUP.md for installation, then explore specific areas based on your role.

13 KiB Raw Blame History

Documentation Index

Quick Links

Documentation Sections

📘 Core Documentation

📋 Documentation Catalog

Getting Started

For New Users

For Frontend Developers

For Backend Developers

For DevOps Engineers

For Integration Developers

Architecture Overview

System Components

Internationalization Support (en/zh/vi/ko)

Feature Documentation

Real-Time Updates

Pricing System

Hook System

API Documentation

REST API Summary

WebSocket Events

Database Schema

Entity Relationships

Deployment Options

Performance Metrics

Benchmarks

Contributing

Development Workflow

Support & Resources

Getting Help

Additional Resources

License

Summary

13 KiB

Raw Blame History