# Duck Stats

> Multi-location uptime and server-health monitoring with consensus alerting. Free for personal use, premium tier for businesses. Runs on infrastructure we operate directly.

## What it does
- Checks websites, APIs, MySQL/Postgres databases, TCP ports, and ICMP ping targets every 1 to 300 seconds.
- Probes each target from 4 geographically distributed locations: Phoenix (AZ, US), Buffalo (NY, US), Ukraine (Kyiv), and Dallas (TX, US).
- Consensus rule: a monitor is only flagged DOWN when every probe location plus the main check agree. A single failing probe is treated as transient noise — no false page-outs.
- Server health agent reports CPU usage, memory pressure, load average, and per-partition disk usage with sub-1-minute resolution.
- Status pages (public, customizable, custom-domain) summarize health to end users and customers.
- Notification channels: Email (SMTP), Discord, Pushover, ntfy, webhooks, and Microsoft Teams.

## Plans

### Free — $0/mo
- 25 monitors
- 5-minute minimum check interval
- Single-location checks (main server only)
- Email notifications
- 2 public status pages

### Starter — $5/mo
- 100 monitors
- 2-minute minimum check interval
- Multi-location consensus probes (up to 5 locations)
- Discord + email notifications
- 5 public status pages
- Custom-domain status pages (CNAME + free TLS)

### Premium — $19/mo
- 250 monitors
- 1-minute minimum check interval
- Multi-location consensus probes (all 4 locations)
- Discord + email + push + ntfy notifications
- Unlimited public status pages
- Full white-label status pages (no "Powered by Duck Stats" footer)
- API access
- Custom domain status pages
- Crypto payments accepted (BTC, LTC, etc. via Plisio)

### Enterprise — custom pricing
- Unlimited monitors
- 20-second minimum check interval
- Priority support, custom SLA
- Self-hosted deployment guidance

## Architecture
- **Frontend**: React + Vite + Tailwind, served from CDN-fronted nginx gateway. Light/dark themes with Space Grotesk + IBM Plex font pairing.
- **Backend**: Go service handles the main check loop, scheduling, JWT auth, and persistence. MySQL HeatWave as the system of record.
- **Admin panel**: Flask/Tabler UI at /admin/ for probe management, agent installation, billing oversight, and tier overrides.
- **Probe agents**: tiny POSIX shell scripts (probe.sh + agent.sh) installed via one-liner curl. Pull configuration from a central token-authenticated endpoint every cron tick.
- **Queue**: Redis asynq with bounded retries and rotated heartbeat tables (7-day window).

## Key endpoints (public, no auth)
- `GET https://duckingstats.com/api/v1/status-pages/slug/{slug}` — status page metadata
- `GET https://duckingstats.com/api/v1/status-pages/slug/{slug}/monitors` — current heartbeats for a status page
- `GET https://duckingstats.com/admin/api/health` — parsed CPU/RAM/disk for all active push (health) monitors
- `GET https://duckingstats.com/admin/api/monitor/{id}/probe-results` — multi-location latency history (24h)
- `GET https://duckingstats.com/admin/api/me` — current viewer's tier + plan rules
- `POST https://duckingstats.com/admin/api/consensus-sweep` — run consensus rule across all linked monitors (cron-triggered every 60s)

## Pages
- https://duckingstats.com/ — landing + sign in
- https://duckingstats.com/login — sign in
- https://duckingstats.com/upgrade — pricing and plan comparison
- https://duckingstats.com/monitors — monitor list (auth required)
- https://duckingstats.com/status/ducktv — Duck Infrastructure status (public)
- https://duckingstats.com/status/probes — Probe Network status (public)
- https://duckingstats.com/status/iduck — iduck WHMCS portal status (public)
- https://duckingstats.com/status/kaufmanhouse — Kaufman House status (public)
- https://duckingstats.com/admin/ — admin panel (auth required)
- https://duckingstats.com/admin/changelog — release notes (public)

## SEO / Indexing
- Sitemap: https://duckingstats.com/sitemap.xml
- robots.txt: https://duckingstats.com/robots.txt
- Submission protocol: IndexNow (Bing, Yandex, Seznam, Naver)
- All public pages emit Open Graph + Twitter Card metadata and Schema.org SoftwareApplication JSON-LD.

## Contact
- Owner: Eddie (eddie@eddie.in)
- Source code: project-specific changes live in /opt/peekaping/source/ on the production host.
- Bugs / feature requests: email the owner directly.

## Brand
- Logo: cream + yellow rubber duck, design system tokens at `--ds-bg #F5F5F0`, `--ds-accent #FFC23A`.
- Typography: Space Grotesk for headings, IBM Plex Sans for body, IBM Plex Mono for code and numerics.