Smartgift-AI/Claude-Code-Monitor
3
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
872c698132aa2e0ee4f105ad1c872c1cd3b9f78a
Claude-Code-Monitor/docs/README.md
T
nntrivi2001 7357070fb9 chore: remove unused desktop app, cloud deployment infra, and monitoring stack 
Deletes desktop/ (Electron wrapper), deployments/ (Helm/Kustomize/
Terraform/CI for cloud deploy), and monitoring/ (Prometheus + Grafana
stack) along with DESKTOP.md, DEPLOYMENT.md, docker-compose.full.yml,
their npm scripts, and every dangling reference across README,
ARCHITECTURE, INSTALL, SETUP, docs/, and the repeated per-file
MODULE_GUIDE "Observability" boilerplate comment. The GET /api/metrics
endpoint itself is untouched — it's the dashboard's own route, not
part of the removed monitoring stack.
2026-08-11 12:16:54 +07:00

439 lines
12 KiB
Markdown
Raw Blame History

# 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.
Reference in New Issue View Git Blame Copy Permalink