Cline rules

1# Network Monitor Project Summary
2 
3## Overview
4 
5A focused Go-based network connectivity monitoring solution designed for long-term ISP issue documentation and pattern detection.
6 
7## Technology Stack
8 
9- **Language**: Go 1.21
10- **Database**: SQLite (modernc.org/sqlite driver)
11- **Frontend**: HTML/CSS/JavaScript with D3.js for visualizations
12- **Chart Generation**: go-chart/v2 library for static PNG reports
13- **Build System**: Taskfile.yml for build management and automation
14 
15## Architecture
16 
17- **Main Application**: Go module with entry point at `cmd/monitor/main.go`, embedded static web assets
18- **Internal Packages**: Modular design with `internal/` packages for separation of concerns
19- **Database Layer**: SQLite with multiple tables for ping results, outages, and aggregated patterns
20- **Web Interface**: REST API serving data to D3.js-based dashboard
21- **Report Generation**: `internal/report/` package for static PNG chart generation
22 
23## Key Components
24 
25- **cmd/monitor/main.go**: Core monitoring logic, ping workers, web server, database management
26- **internal/config/**: Configuration management (config.go, flags.go)
27- **internal/database/**: Database operations and schema (db.go, maintenance.go, queries.go)
28- **internal/models/**: Data models (ping.go, stats.go, types.go)
29- **internal/monitor/**: Monitoring lifecycle and workers (lifecycle.go, monitor.go, worker.go)
30- **internal/ping/**: Ping implementation (ping.go)
31- **internal/report/**: Chart generation using go-chart library (charts.go, generator.go, text.go, utils.go)
32- **internal/web/**: Web server and API handlers (handlers.go, server.go)
33- **static/index.html**: Web dashboard with real-time visualizations
34- **Database Tables**:
35  - `ping_results`: Raw ping data (7-day retention)
36  - `hourly_patterns`: Aggregated patterns for heatmap (90-day retention)
37  - `outages`: Detected connectivity failures
38  - `hourly_stats`: Statistical aggregations
39 
40## Features
41 
42- **Continuous Monitoring**: Configurable ping intervals to multiple targets
43- **Real-time Dashboard**: Web interface at localhost:8080 with live charts
44- **Pattern Detection**: 24-hour heatmap overlay showing issue patterns across days
45- **Outage Tracking**: Automatic detection of connectivity failures (5+ failed pings in any 10 consecutive pings)
46- **Static Reports**: PNG chart generation for ISP evidence documentation
47- **Data Management**: Automatic maintenance with configurable retention periods
48 
49## Configuration
50 
51- **Targets**: Comma-separated IP addresses (default: Google DNS, Cloudflare, OpenDNS)
52- **Interval**: Ping frequency (default: 1 second)
53- **Timeout**: Ping timeout (default: 5 seconds)
54- **Database**: SQLite file path (default: network_monitor.db)
55- **Port**: Web server port (default: 8080)
56 
57## Deployment
58 
59- **Build**: `task build` command (or `go build ./cmd/monitor`)
60- **Run**: Executable binary with optional flags
61- **Service**: Can be configured as macOS launchd service or systemd service
62- **Resource Usage**: Low CPU/memory footprint suitable for continuous operation
63 
64## Data Flow
65 
661. Ping workers continuously test connectivity to configured targets
672. Results stored in SQLite database with timestamps
683. Hourly maintenance aggregates data for heatmap visualization
694. Web API serves data to frontend dashboard
705. Optional static report generation for documentation
71 
72## Use Cases
73 
74- ISP connectivity monitoring and issue documentation
75- Network troubleshooting and pattern analysis
76- Long-term connectivity logging for service agreements
77- Real-time network status dashboard
78 
79## Development Guidelines
80 
81### Git Practices
82 
83- **NEVER commit to main/master branch directly** - use feature branches
84- Keep commits small and focused with clear, descriptive messages
85- Rebase branches before merging to maintain clean history
86- Use pull requests for code reviews and discussions
87 
88### Build System
89 
90- Use Taskfile.yml for build management instead of Makefiles
91- Required tasks: `build`, `build-linux`, `build-ci`, `test`, `test-ci`, `lint`
92- Build tasks must depend on test and lint tasks
93- Build artifacts placed in `build/` directory
94- GitHub Actions CI uses build-ci task for automated testing and linting
95 
96### Code Quality
97 
98- **Formatting**: Use `goimports -w .` (not `gofmt`) for code formatting and import management
99- **Linting**: Use golangci-lint with `.golangci.yml` configuration
100- **Error Handling**: Use `errors.Is()` and `errors.As()` for robust error checking
101- **Testing**: Include basic unit tests for critical functionality
102- **Dependencies**: Prefer standard library; justify third-party additions
103 
104### Modern Tools
105 
106- **Search**: Use `rg` (ripgrep) instead of `grep` for faster, smarter searching
107- **File Finding**: Use `fd` instead of `find` for better performance and `.gitignore` respect
108- **Code Analysis**: Use `gofuncs` tool for exploring Go function structures
109 
110### Project Validation
111 
112- Use `validate-docs` tool to ensure standard project structure compliance
113- Validates directory structure, required files, and build configuration
114 
115## Development Notes
116 
117- Cross-platform ping implementation (Windows/Mac/Linux support)
118- Embedded static files using Go's `embed` package
119- RESTful API design with JSON responses
120- D3.js for interactive data visualizations
121- SQLite WAL mode for concurrent access
122- llm-shared submodule provides development tools and guidelines
123