Spencer Grimes
11896919e4
- Aggregator: Flask-based event broker with priority queue - Frontend: OLED-optimized UI with animations - Detectors: disk, cpu, memory, service, network - Unified entry point (sentry.py) with process management - Heartbeat TTL system for auto-clearing stale events Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
122 lines
4.0 KiB
Markdown
122 lines
4.0 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
Sentry-Emote is a minimalist system status monitor designed for an old Pixel phone used as an ambient display. It uses ASCII "emotes" to represent system health instead of complex graphs.
|
|
|
|
## Architecture
|
|
|
|
**Publisher/Subscriber model:**
|
|
|
|
```
|
|
┌─────────────┐ POST /event ┌─────────────┐ GET /status ┌─────────────┐
|
|
│ Detectors │ ──────────────────▶ │ Aggregator │ ◀────────────────── │ Emote-UI │
|
|
│ (sensors) │ │ (broker) │ │ (display) │
|
|
└─────────────┘ └─────────────┘ └─────────────┘
|
|
```
|
|
|
|
- **Aggregator** (`aggregator.py`) — Flask service managing the event queue and priority logic
|
|
- **Detectors** (`detectors/*.py`) — Independent scripts monitoring system metrics
|
|
- **Emote-UI** (`index.html`) — OLED-optimized web frontend
|
|
- **Sentry** (`sentry.py`) — Unified entry point managing all processes
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Setup
|
|
python -m venv venv
|
|
source venv/bin/activate # or .\venv\Scripts\activate on Windows
|
|
pip install -r requirements.txt
|
|
|
|
# Run everything
|
|
python sentry.py
|
|
```
|
|
|
|
UI available at http://localhost:5000
|
|
|
|
## Configuration
|
|
|
|
Edit `config.json` to configure the aggregator URL, enable/disable detectors, and set thresholds.
|
|
|
|
```json
|
|
{
|
|
"aggregator_url": "http://localhost:5000",
|
|
"aggregator": { "script": "aggregator.py" },
|
|
"detectors": [
|
|
{
|
|
"name": "cpu",
|
|
"enabled": true,
|
|
"script": "detectors/cpu.py",
|
|
"env": {
|
|
"CHECK_INTERVAL": "30",
|
|
"THRESHOLD_WARNING": "85",
|
|
"THRESHOLD_CRITICAL": "95"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Detectors
|
|
|
|
| Detector | Script | Required Env Vars |
|
|
|----------|--------|-------------------|
|
|
| Disk Space | `detectors/disk_space.py` | — |
|
|
| CPU | `detectors/cpu.py` | — |
|
|
| Memory | `detectors/memory.py` | — |
|
|
| Service | `detectors/service.py` | `SERVICES` (comma-separated process names) |
|
|
| Network | `detectors/network.py` | `HOSTS` (comma-separated hostnames/IPs) |
|
|
|
|
All detectors support: `AGGREGATOR_URL`, `CHECK_INTERVAL`, `THRESHOLD_WARNING`, `THRESHOLD_CRITICAL`
|
|
|
|
## API Endpoints
|
|
|
|
- `POST /event` — Register event: `{"id": "name", "priority": 1-4, "message": "optional", "ttl": optional_seconds}`
|
|
- `POST /clear` — Clear event: `{"id": "name"}`
|
|
- `GET /status` — Current state JSON
|
|
- `GET /events` — List active events
|
|
|
|
## Priority System
|
|
|
|
Lower number = higher priority. Events with a `ttl` auto-expire (heartbeat pattern).
|
|
|
|
| Priority | State | Emote | Color | Behavior |
|
|
|----------|----------|----------|--------|----------|
|
|
| 1 | Critical | `( x_x)` | Red | Shaking animation |
|
|
| 2 | Warning | `( o_o)` | Yellow | Breathing animation |
|
|
| 3 | Notify | `( 'o')` | Blue | Popping animation, 10s default TTL |
|
|
| 4 | Optimal | `( ^_^)` | Green | Default when no events |
|
|
|
|
## Testing Events
|
|
|
|
```bash
|
|
# Warning with 30s TTL
|
|
curl -X POST -H "Content-Type: application/json" \
|
|
-d '{"id":"test","priority":2,"message":"Test warning","ttl":30}' \
|
|
http://localhost:5000/event
|
|
|
|
# Clear manually
|
|
curl -X POST -H "Content-Type: application/json" \
|
|
-d '{"id":"test"}' \
|
|
http://localhost:5000/clear
|
|
```
|
|
|
|
## File Structure
|
|
|
|
```
|
|
├── sentry.py # Unified entry point
|
|
├── aggregator.py # Event broker/API server
|
|
├── index.html # OLED-optimized frontend
|
|
├── config.json # Runtime configuration
|
|
├── detectors/
|
|
│ ├── disk_space.py
|
|
│ ├── cpu.py
|
|
│ ├── memory.py
|
|
│ ├── service.py
|
|
│ └── network.py
|
|
├── requirements.txt
|
|
└── SPEC.md # Original project specification
|
|
```
|