AgentHub/docs

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]
    
    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
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

---

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:

1. Read SETUP.md
2. Run npm run setup
3. Run npm run dev
4. 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 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:

• WebSocket Protocol
• Client Integration
• Server Broadcasting

---

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:

• Pricing API
• Database Schema
• Server Implementation

---

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:

• Hook System Guide
• Hook Processing
• Installation

---

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

---

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:

• Server Performance
• Database Tuning
• Client Performance

---

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:

1. 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)
2. Check formatting: npm run format:check
3. Build: npm run build
4. Update docs if needed

---

Support & Resources

Getting Help

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

Additional Resources

• Claude Code Documentation
• Model Context Protocol (MCP)
• SQLite Documentation
• React Documentation
• Express Documentation

---

License

Internal SmartGift build — all rights reserved.

---

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.