# Documentation Index

Comprehensive documentation for the Agent Dashboard project.

---

## Quick Links

- [Architecture Overview](../ARCHITECTURE.md) - System design and technical reference
- [I18N Architecture](./I18N.md) - Internationalization architecture and usage guide
- [CLI Reference](./CLI.md) - The `ccam` terminal CLI: every command, discovery, safety model
- [Setup Guide](../SETUP.md) - Installation and configuration
- [Installation](../INSTALL.md) - Detailed installation instructions

---

## Documentation Sections

### 📘 Core Documentation

```mermaid
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](../client/README.md) | React frontend architecture, components, state management | Frontend developers |
| [server/README.md](../server/README.md) | Express backend, database, WebSocket, API | Backend developers |
| [API.md](./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](./DATABASE.md) | SQLite schema, queries, performance | Database administrators |
| [HOOKS.md](./HOOKS.md) | Claude Code hook system integration | Hook developers |
| [MCP.md](./MCP.md) | MCP server setup and tool reference | MCP integrators |
| [I18N.md](./I18N.md) | Language architecture, locale strategy, and rollout checklist | Frontend and product teams |
| [CLI.md](./CLI.md) | `ccam` command reference — monitoring, browsing, insights, alerts, pricing, import, administration | Terminal users and CI scripting |

---

## Getting Started

### For New Users

```mermaid
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](../SETUP.md)
2. Run `npm run setup`
3. Run `npm run dev`
4. Open browser to `http://localhost:5173`

---

### For Frontend Developers

```mermaid
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](../client/README.md) - Complete frontend guide
- [API.md](./API.md#websocket-api) - WebSocket protocol
- Component source: `client/src/components/`

---

### For Backend Developers

```mermaid
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](../server/README.md) - Complete backend guide
- [DATABASE.md](./DATABASE.md) - Schema and queries
- [HOOKS.md](./HOOKS.md) - Hook processing
- API source: `server/routes/`

---

### For Integration Developers

```mermaid
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](./API.md) - Complete API reference
- [MCP.md](./MCP.md) - MCP server integration
- [HOOKS.md](./HOOKS.md) - Custom hook integration

---

## Architecture Overview

### System Components

```mermaid
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)

```mermaid
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](./I18N.md) for architecture details, naming conventions, language switching flow, localization behavior, and rollout guidance.

---

## Feature Documentation

### Real-Time Updates

```mermaid
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](./API.md#websocket-api)
- [Client Integration](../client/README.md#websocket-integration)
- [Server Broadcasting](../server/README.md#websocket-protocol)

---

### Pricing System

```mermaid
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](./API.md#pricing)
- [Database Schema](./DATABASE.md#pricing_rules)
- [Server Implementation](../server/README.md#pricing-calculation)

---

### Hook System

```mermaid
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](./HOOKS.md)
- [Hook Processing](../server/README.md#hook-processing)
- [Installation](../SETUP.md#install-hooks)

---

## 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](./API.md#rest-api)

---

### 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](./API.md#websocket-api)

---

## Database Schema

### Entity Relationships

```mermaid
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](./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](../server/README.md#performance)
- [Database Tuning](./DATABASE.md#performance-optimization)
- [Client Performance](../client/README.md#performance)

---

## Contributing

### Development Workflow

```mermaid
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](https://github.com/your-org/agent-dashboard/issues)
- **Discussions:** [GitHub Discussions](https://github.com/your-org/agent-dashboard/discussions)
- **Documentation:** This folder

### Additional Resources

- [Claude Code Documentation](https://docs.anthropic.com/claude/docs)
- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
- [SQLite Documentation](https://sqlite.org/docs.html)
- [React Documentation](https://react.dev/)
- [Express Documentation](https://expressjs.com/)

---

## 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](../SETUP.md) for installation, then explore specific areas based on your role.
