Skip to content

Commit d22be40

Browse files
mcollinaclaude
mcollina
and
claude
authored
docs: enhance README and expand CLAUDE.md documentation (#131)
- Add comprehensive README with features, quick start, and usage examples - Highlight new profiling & recording capabilities (CPU/heap) - Include project structure, use cases, and development setup - Expand CLAUDE.md with detailed architecture documentation - Document Platformatic Watt monorepo structure - Add backend/frontend architecture details - Explain API communication and OpenAPI client generation - Document recording/offline mode workflow - Fix license to Apache-2.0 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude <noreply@anthropic.com>
1 parent b885f75 commit d22be40

File tree

2 files changed

+282
-47
lines changed

2 files changed

+282
-47
lines changed

‎CLAUDE.md‎

Lines changed: 120 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,139 @@
1-
# Watt Admin Development Guide
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
24

35
## Build/Test/Lint Commands
46
```bash
57
# Development
6-
npm run dev # Start development server
8+
npm run dev # Start development server (wattpm)
79
npm run build # Build for production
810
npm run start # Start in production mode
9-
npm run clean # Remove build artifacts
11+
npm run clean # Remove build artifacts (web/*/dist)
12+
npm run typecheck # Type-check backend and frontend TypeScript
1013

1114
# Testing
12-
npm run test # Run all tests
15+
npm run test # Run all tests (CLI, E2E, backend, frontend)
1316
npm run test:cli # Run CLI tests only
1417
npm run test:backend # Run backend tests only
15-
npm run test:frontend # Run frontend tests only
16-
node --test test/path/to/file.test.js # Run single Node.js test file
17-
cd web/frontend && vitest run path/to/file.test.ts # Run single frontend test
18+
npm run test:frontend # Run frontend tests only (Vitest)
19+
npm run test:e2e # Run Playwright E2E tests
20+
npm run test:e2e:ui # Run Playwright with UI mode
21+
22+
# Running single test files
23+
node --test test/path/to/file.test.ts # CLI test
24+
node --test web/backend/path/to/file.test.ts # Backend test
25+
cd web/frontend && vitest run path/to/file.test.ts # Frontend test
1826

1927
# Linting
2028
npm run lint # Lint all code
2129
npm run lint:fix # Fix linting issues automatically
30+
31+
# Client generation (OpenAPI)
32+
npm run client:openapi # Generate OpenAPI spec from backend
33+
npm run client:generate # Generate frontend client from OpenAPI using massimo
2234
```
2335

36+
## Project Architecture
37+
38+
### High-Level Structure
39+
This is a **Platformatic Watt monorepo** containing a CLI tool and full-stack admin dashboard for monitoring Platformatic runtimes. The project uses Platformatic's microservices architecture with three main applications orchestrated by wattpm:
40+
41+
1. **Backend** (web/backend): Fastify service providing REST APIs and WebSocket endpoints
42+
2. **Composer** (web/composer): Platformatic Gateway that routes requests and proxies between frontend/backend
43+
3. **Frontend** (web/frontend): React + Vite SPA with real-time monitoring UI
44+
45+
### CLI Tool (cli.js)
46+
- **Purpose**: Discovers and connects to running Platformatic runtimes using `@platformatic/control`
47+
- **Entry point**: `cli.js` (executable, can be installed globally as `watt-admin`)
48+
- **Key features**:
49+
- Auto-discovers runtimes via `RuntimeApiClient`
50+
- Interactive runtime selection with `@inquirer/prompts`
51+
- Launches admin dashboard against selected runtime
52+
- Supports flags: `--port`, `--record`, `--profile` (cpu/heap)
53+
- **Recording mode**: Can capture metrics/flamegraphs and generate offline HTML bundles
54+
55+
### Wattpm Configuration (watt.json)
56+
Defines the multi-app structure:
57+
- **Entrypoint**: `composer` (gateway on port 4042 by default)
58+
- **Backend**: `/api` prefix, TypeScript with `--import=amaro/strip`
59+
- **Frontend**: `/` prefix (root path)
60+
- **Composer**: Routes between backend API and frontend assets
61+
62+
### Backend Architecture (web/backend)
63+
- **Framework**: Fastify with `@fastify/type-provider-json-schema-to-ts` for type-safe routes
64+
- **Main routes**:
65+
- `routes/root.ts`: Core API endpoints (`/runtimes`, `/runtimes/:pid/services`, `/record/:pid`)
66+
- `routes/ws.ts`: WebSocket endpoint for live log streaming (`/runtimes/:pid/logs/ws`)
67+
- `routes/metrics.ts`: Metrics proxy endpoints
68+
- `routes/proxy.ts`: Generic proxy to runtime services
69+
- **Plugins**:
70+
- `plugins/metrics.ts`: Interval-based metrics collection using `RuntimeApiClient`
71+
- `plugins/websocket.ts`: WebSocket server setup
72+
- **Key utilities**:
73+
- `utils/runtimes.ts`: Runtime discovery and PID management
74+
- `utils/metrics.ts`: Metrics fetching and aggregation
75+
- `utils/states.ts`: State machine for recording modes
76+
- **Testing**: Node.js test runner with `--experimental-test-module-mocks`
77+
78+
### Frontend Architecture (web/frontend)
79+
- **Framework**: React 19 with TypeScript, React Router v7 (HashRouter)
80+
- **Build tool**: Vite with `vite-plugin-singlefile` (generates single-file HTML for offline mode)
81+
- **State management**: Zustand (`useAdminStore.ts`)
82+
- **Key state**: `runtimePid`, `mode` (live/load), `record` (start/stop), navigation breadcrumbs
83+
- **Main routes**:
84+
- `/` (HOME_PATH): Application details overview
85+
- `/services` (POD_SERVICES_PATH): Service metrics charts
86+
- `/logs` (POD_LOGS_PATH): Real-time service logs
87+
- `/flamegraph` (POD_FLAMEGRAPH_PATH): CPU/heap flamegraph visualization
88+
- **Components structure**:
89+
- `components/application/`: App overview, metrics display
90+
- `components/services/`: Service charts, logs, flamegraphs
91+
- `components/application-logs/`: Log filtering and display
92+
- `layout/`: Navigation, header, containers
93+
- **Real-time data**: WebSocket connection via `react-use-websocket` for live logs
94+
- **Testing**: Vitest for unit tests, Playwright for E2E tests
95+
96+
### API Communication
97+
- **Backend client**: Auto-generated from OpenAPI spec using `massimo-cli` (stored in `web/frontend/src/client/`)
98+
- **Generation flow**:
99+
1. Backend exposes OpenAPI via Fastify
100+
2. `npm run client:openapi` extracts spec to `web/backend/openapi.json`
101+
3. `npm run client:generate` creates TypeScript client with types
102+
- **RuntimeApiClient**: Used by backend to communicate with target Platformatic runtimes
103+
104+
### Recording/Offline Mode
105+
- **Purpose**: Capture runtime metrics/profiling data for offline analysis
106+
- **Flow**:
107+
1. Start recording: CLI flag `--record --profile cpu|heap`
108+
2. Backend calls `startApplicationProfiling` on all applications
109+
3. Collects metrics at intervals (defined in MS_WAITING constant)
110+
4. On SIGINT: Stops profiling, saves .pb files, embeds data in HTML bundle
111+
5. Opens standalone HTML with embedded metrics/flamegraph data in `window.LOADED_JSON`
112+
24113
## Code Style Guidelines
25-
- **Formatting**: Project uses neostandard via ESLint (strict mode)
26-
- **TypeScript**: Use explicit types for function params, returns, interfaces
114+
- **Formatting**: neostandard via ESLint (strict mode, TypeScript enabled)
115+
- **TypeScript**:
116+
- Explicit types for function params and returns
117+
- Use interface/type for complex structures
118+
- Backend uses `JsonSchemaToTsProvider` for route typing
27119
- **Imports**: Group related imports, alphabetize within groups
28120
- **Naming**: camelCase for variables/functions, PascalCase for components/classes/interfaces/types
29-
- **Error Handling**: Log errors with fastify.log, handle async errors with try/catch
30-
- **React**: Functional components with hooks, use React.ReactElement return types
31-
- **Testing**: Node.js test module for backend, Vitest for frontend
32-
- **Backend**: Follow Fastify conventions with typed routes using JsonSchemaToTsProvider
121+
- **Error Handling**:
122+
- Backend: Use `fastify.log` for logging, try/catch for async
123+
- Frontend: Error boundaries with `use-error-boundary`
124+
- **React**:
125+
- Functional components with hooks only
126+
- Return type `React.ReactElement` for components
127+
- Use Zustand for global state
128+
- **Testing**:
129+
- Backend/CLI: Node.js test module (`--test` flag)
130+
- Frontend: Vitest for unit, Playwright for E2E
131+
- Test files use `.test.ts` extension
132+
133+
## Important Development Notes
134+
- **TypeScript transpilation**: Backend uses `amaro/strip` for fast TypeScript stripping (no type checking at runtime)
135+
- **Module mocking**: Tests use `--experimental-test-module-mocks` flag
136+
- **Hot reload**: Both frontend and backend support watch mode in dev
137+
- **Build artifacts**: Always in `web/*/dist` directories
138+
- **Environment**: Uses `.env` file (copy from `.env.sample`)
139+
- **Platformatic versions**: All Platformatic packages use same version (3.15.0+)

‎README.md‎

Lines changed: 162 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,72 +1,200 @@
1-
# watt-admin
1+
# 🔌 Watt Admin
22

3-
## CLI Tool
3+
**Real-time monitoring and administration for your Platformatic applications**
44

5-
The project includes a command-line interface tool to check available Platformatic runtimes.
5+
Watt Admin is an open-source developer monitoring tool that provides instant visibility into your Node.js services. Monitor performance, analyze logs, and troubleshoot issues—all from a single, intuitive dashboard.
6+
7+
![Watt Admin Dashboard](https://blog.platformatic.dev/content/images/2025/01/CleanShot-2025-01-15-at-15.50.54@2x.png)
8+
9+
## ✨ Features
10+
11+
### 📊 **Performance Metrics**
12+
- **Memory tracking**: RSS, heap usage, new/old space allocation with interactive charts
13+
- **CPU monitoring**: Real-time CPU and event loop utilization
14+
- **Latency analysis**: P90, P95, P99 percentiles at a glance
15+
- **Request rates**: Monitor requests per second across all services
16+
17+
### 📝 **Centralized Logging**
18+
- View logs from all services in one place
19+
- Filter by service or log level
20+
- Toggle between formatted and raw JSON views
21+
- Export logs for further analysis
22+
23+
### 🎯 **Service Management**
24+
- Monitor service status at a glance
25+
- Drill down into individual service metrics
26+
- Compare performance across services
27+
- Restart services directly from the dashboard
28+
29+
### 🔥 **Profiling & Recording** *(New!)*
30+
- **CPU profiling**: Capture flame graphs to identify performance bottlenecks
31+
- **Heap profiling**: Analyze memory allocation patterns
32+
- **Offline analysis**: Generate self-contained HTML bundles for sharing and review
33+
- **Recording mode**: Capture metrics and profiles over time for post-mortem analysis
34+
35+
## 🚀 Quick Start
36+
37+
### Using npx (Recommended)
38+
39+
Launch Watt Admin with a single command:
40+
41+
```bash
42+
npx wattpm admin
43+
```
44+
45+
The dashboard will automatically discover your running Platformatic runtimes and open at `http://localhost:4042`.
646

747
### Installation
848

9-
After installing the project dependencies, you can run the tool directly:
49+
Install globally for convenient access:
1050

1151
```bash
12-
./cli.js
52+
npm install -g @platformatic/watt-admin
1353
```
1454

15-
To run the CLI on a custom port, you can just pass it as an argument with `./cli.js --port 4321`.
55+
Then run:
1656

17-
To record a flamegraph session, and choose to profile either the `cpu` or the `heap`, you can run the CLI with `./cli.js --record --profile heap`. Once you will stop the process, an HTML one-file bundle will be auto-generated, and you will be able to navigate (even offline) the `watt-admin` app, looking at the flamegraph and at the metrics stored for the whole time you have run the CLI.
57+
```bash
58+
watt-admin
59+
```
1860

19-
The tool is also available as a binary when installed globally or linked:
61+
## 💡 Usage
62+
63+
### Basic Usage
64+
65+
When you run `watt-admin`, it automatically discovers all available Platformatic runtimes:
2066

2167
```bash
22-
npm link # Link the package locally
23-
watt-runtime # Run the command
68+
$ watt-admin
69+
Select a runtime: (Use arrow keys)
70+
❯ my-app (PID: 12345) (Started at 3/10/2025, 10:00:00 AM)
71+
api-service (PID: 54321) (Started at 3/10/2025, 9:30:00 AM)
2472
```
2573

26-
### Usage
74+
If only one runtime is running, it will be selected automatically.
75+
76+
### Custom Port
2777

28-
The tool automatically discovers all available Platformatic runtimes. If multiple runtimes are found, it will prompt you to select one using an interactive menu.
78+
Run Watt Admin on a different port:
2979

80+
```bash
81+
watt-admin --port 4321
3082
```
31-
$ watt-runtime
32-
Select a runtime: (Use arrow keys)
33-
❯ runtime-name (PID: 12345) (Started at 3/10/2025, 10:00:00 AM)
34-
another-runtime (PID: 54321) (Started at 3/10/2025, 9:30:00 AM)
83+
84+
### Recording Mode
85+
86+
Capture metrics and profiling data for offline analysis:
87+
88+
```bash
89+
# Profile CPU usage
90+
watt-admin --record --profile cpu
91+
92+
# Profile heap allocation
93+
watt-admin --record --profile heap
3594
```
3695

37-
If only one runtime is available, it will be automatically selected.
96+
When recording, press `Ctrl+C` to stop. Watt Admin will:
97+
1. Collect all metrics and profiling data
98+
2. Generate a self-contained HTML bundle
99+
3. Automatically open the bundle in your browser
100+
101+
The generated HTML file contains everything you need for offline analysis—perfect for sharing with your team or reviewing later.
102+
103+
## 🏗️ Development
104+
105+
### Prerequisites
38106

39-
## Project setup
107+
- Node.js 18 or higher
108+
- A running Platformatic runtime to monitor
40109

110+
### Setup
111+
112+
```bash
113+
git clone https://github.com/platformatic/watt-admin.git
114+
cd watt-admin
115+
npm install
116+
cp .env.sample .env
41117
```
42-
npm install && cp .env.sample .env
118+
119+
### Development Mode
120+
121+
Auto-reload both backend and frontend on changes:
122+
123+
```bash
124+
npm run dev
43125
```
44126

45127
### Build
46128

47-
```
129+
```bash
48130
npm run build
49131
```
50132

51-
### Start
133+
### Run Tests
52134

53-
```
54-
npm run start
135+
```bash
136+
# Run all tests
137+
npm test
138+
139+
# Run specific test suites
140+
npm run test:cli # CLI tests
141+
npm run test:backend # Backend tests
142+
npm run test:frontend # Frontend tests
143+
npm run test:e2e # End-to-end tests
55144
```
56145

57-
### Dev Mode
58-
59-
This will auto-reload both the backend and frontend when changes are made.
146+
### Project Structure
60147

61148
```
62-
npm run dev
149+
watt-admin/
150+
├── cli.js # CLI entry point
151+
├── lib/ # Core CLI functionality
152+
├── web/
153+
│ ├── backend/ # Fastify API server
154+
│ ├── frontend/ # React dashboard
155+
│ └── composer/ # Platformatic Gateway
156+
├── watt.json # Wattpm configuration
157+
└── test/ # Test suites
63158
```
64159

65-
### Navigate the app
160+
## 🎯 Use Cases
161+
162+
### Development Workflow
163+
Monitor your application while developing locally. Instantly see the impact of code changes on performance.
164+
165+
### Debugging Performance Issues
166+
Use CPU and heap profiling to identify bottlenecks and memory leaks before they reach production.
167+
168+
### Team Collaboration
169+
Generate offline HTML bundles to share performance data and profiling results with your team.
170+
171+
### Learning and Optimization
172+
Understand how your services behave under load and optimize based on real data.
173+
174+
## 🔗 Related Tools
175+
176+
For production monitoring and observability, check out [Platformatic Console](https://platformatic.dev/console)—the intelligent command center for Platformatic Cloud deployments.
177+
178+
## 📚 Documentation
179+
180+
- [Platformatic Documentation](https://docs.platformatic.dev)
181+
- [Watt Admin Blog Post](https://blog.platformatic.dev/introducing-watt-admin)
182+
- [Platformatic Wattpm](https://docs.platformatic.dev/docs/guides/wattpm)
183+
184+
## 🤝 Contributing
185+
186+
Contributions are welcome! Please check out our [contributing guidelines](CONTRIBUTING.md) to get started.
187+
188+
## 📄 License
189+
190+
Apache-2.0 License - see [LICENSE](LICENSE) for details.
191+
192+
## 🙋 Support
193+
194+
- [GitHub Issues](https://github.com/platformatic/watt-admin/issues)
195+
- [Discord Community](https://discord.gg/platformatic)
196+
- [Twitter](https://twitter.com/platformatic)
197+
198+
---
66199

67-
0. check you started `watt-admin`
68-
1. you should now see an info log like `Platformatic is now listening at http://127.0.0.1:{PORT}` (open the local URL)
69-
2. click on link above to navigate the frontend app
70-
3. you can call the backend by prefixing the local URL with `/api`
71-
4. call the `/api/runtimes` endpoint (you should receive the PID)
72-
5. call the `/api/runtimes/{pid}/metrics` endpoint
200+
Built with ❤️ by the [Platformatic](https://platformatic.dev) team

0 commit comments

Comments
 (0)