CLAUDE.md

1# CLAUDE.md
2 
3Network Connectivity Monitor - AI Agent Guidelines
4 
5## Project Overview
6 
7A Go-based network monitoring tool that performs continuous ping tests to detect ISP issues and connectivity patterns. Features intelligent data retention, pattern detection via heatmaps, and web-based visualization.
8 
9**Key Purpose**: Long-term ISP issue documentation with compelling visual evidence.
10 
11## Architecture & Entry Points
12 
13- **Main Entry**: `main.go` - Orchestrates all components with graceful shutdown
14- **Internal Structure**: Clean separation via `internal/` packages
15- **Static Assets**: Embedded via `//go:embed static/*` in main.go (production) or filesystem serving (development)
16- **Database**: SQLite with WAL mode for concurrent access
17 
18### Critical Components
19 
20```plain
21internal/
22├── config/     - CLI flags and validation (config.go, flags.go)
23├── database/   - SQLite operations, schema, maintenance (db.go, queries.go)
24├── models/     - Data structures (ping.go, stats.go, types.go)
25├── monitor/    - Worker orchestration and lifecycle (monitor.go, worker.go)
26├── ping/       - Cross-platform ping implementation
27├── report/     - PNG chart generation using go-chart/v2
28└── web/        - HTTP server and REST API (handlers.go, server.go)
29```
30 
31## Database Schema Strategy
32 
33**Smart Retention Pattern**:
34 
35- `ping_results`: Raw data (7-day retention)
36- `hourly_patterns`: Aggregated for heatmap (90-day retention)
37- `outages`: Detected failures (permanent)
38- `hourly_stats`: Statistical summaries
39 
40**Key Insight**: Maintenance runs hourly via `internal/database/maintenance.go` - automatic data aggregation and cleanup.
41 
42## Build & Development Workflow
43 
44### Essential Commands
45 
46```bash
47task build          # Build after tests+lint (required for deployment)
48task dev           # Development server with live static file editing
49task test          # Run all tests
50task lint          # goimports + vet + golangci-lint
51task build-linux   # Cross-compile for Linux deployment
52```
53 
54### Development Mode for UI Work
55 
56**Live Static File Editing**: The `task dev` command now enables live editing of HTML, CSS, and JavaScript files without server restarts.
57 
58```bash
59task dev   # Runs: go run . --dev
60```
61 
62**Development Mode Features**:
63 
64- **Live HTML editing**: Changes to `static/index.html` visible on browser refresh
65- **Live CSS editing**: Modifications to `static/css/*.css` applied immediately
66- **Live JavaScript editing**: Updates to `static/js/*.js` served instantly from filesystem
67- **No server restart required**: Only browser refresh needed to see changes
68- **Production safety**: Build process unchanged, still uses embedded files
69 
70**Development vs Production**:
71 
72- **Development** (`--dev` flag): Serves files from `static/` directory (live editing)
73- **Production** (default): Uses embedded `//go:embed` files (compile-time)
74 
75### UI Testing with Playwright
76 
77**Automated UI Testing**: Use the general-purpose agent with Playwright browser automation for comprehensive UI testing.
78 
79```bash
80# Start development server in background
81task dev
82 
83# Use Task tool with browser automation to test UI changes
84# The agent can:
85# - Navigate to localhost:8080
86# - Take screenshots of UI components
87# - Test hover interactions on heatmap cells
88# - Verify responsive layout behavior
89# - Test different time range selections
90# - Validate tooltips and interactive elements
91```
92 
93**UI Development Workflow**:
94 
951. Start development server: `task dev`
962. Edit static files (HTML/CSS/JS) in your editor
973. Refresh browser to see changes immediately
984. Use Playwright agent to verify functionality
995. Take screenshots for documentation/validation
100 
101### Pre-commit Requirements
102 
103- **Always run**: `task build` before considering changes complete
104- **Format**: Uses `goimports -w .` (NOT gofmt) for imports management
105- **Linting**: golangci-lint with `.golangci.yml` config
106 
107## Project-Specific Conventions
108 
109### Error Handling Pattern
110 
111```go
112// Preferred throughout codebase
113if errors.Is(err, database.ErrOutageExists) {
114    // handle specifically
115}
116```
117 
118### Configuration Philosophy
119 
120- CLI flags via `internal/config/flags.go`
121- Validation in separate `config.Validate()` method
122- Defaults optimized for home ISP monitoring
123 
124### Ping Implementation Detail
125 
126- Cross-platform: Windows/Mac/Linux support in `internal/ping/ping.go`
127- **Outage Detection**: 5+ failures in any 10 consecutive pings
128- Uses OS-native ping (not raw sockets) for reliability
129 
130## Web Interface Integration
131 
132### API Patterns
133 
134- RESTful JSON endpoints in `internal/web/handlers.go`
135- Real-time data serving for D3.js frontend
136- **Key Route**: `/api/data` powers the heatmap visualization
137 
138### Static Assets
139 
140- Single `static/index.html` with embedded D3.js
141- **Production Pattern**: All static files embedded at compile time via `//go:embed`
142- **Development Pattern**: Files served directly from filesystem for live editing
143- No build step for frontend - vanilla HTML/JS/CSS
144- **Live Development**: Use `task dev` for immediate UI changes without server restart
145 
146## Testing & CI/CD
147 
148### Test Strategy
149 
150- `*_test.go` files for critical functionality only
151- **CI Pattern**: Separate test/lint/build jobs in GitHub Actions
152- Uses `task test-ci` for coverage reporting
153 
154### Docker Deployment
155 
156- `Dockerfile` + `docker-compose.yml` for containerization
157- **Volume Pattern**: `./data:/app/data` for database persistence
158- Health checks via web interface availability
159 
160## Integration Points
161 
162### llm-shared Submodule
163 
164- Development tools in `llm-shared/utils/`
165- **Key Tool**: `gofuncs.go` for function analysis
166- Project validation via `validate-docs.go`
167 
168### External Dependencies
169 
170- **Database**: `modernc.org/sqlite` (pure Go SQLite)
171- **Charts**: `github.com/wcharczuk/go-chart/v2` for PNG report generation
172- **Minimal Dependencies**: Prefers standard library
173 
174## ISP Documentation Workflow
175 
176### Data Collection Strategy
177 
1781. **Hour 1**: Basic connectivity data
1792. **Day 1**: Initial pattern recognition
1803. **Week 1**: Clear time-of-day patterns
1814. **Month 1**: Compelling evidence for ISP discussions
182 
183### Report Generation
184 
185- PNG charts via `internal/report/` package
186- **Visual Evidence**: Heatmap screenshots after 1-2 weeks most effective
187- Export capability for CSV data analysis
188 
189## Development Notes
190 
191- **Deployment Target**: Single-user, private monitoring (not SaaS)
192- **Service Integration**: Includes launchd/systemd service examples in README
193- **Resource Efficient**: <1% CPU, 20-50MB RAM with default settings
194- **Cross-Platform**: Full macOS/Linux/Windows support with OS-specific deployment guides
195