StatPulse

Developer

Original Idea

API Status Monitor A background service that runs health checks and publishes a clean status page.

Product Requirements Document (PRD): StatPulse

1. Executive Summary

StatPulse is a next-generation, high-concurrency API monitoring and status communication platform designed for the 2026 technical landscape. It enables engineering teams to automate multi-region health checks, track deep-service latency using time-series analytics, and maintain transparency with stakeholders through customizable, high-performance status pages. By decoupling the management control plane (Node.js/NestJS) from the high-throughput execution plane (Go), StatPulse provides unmatched reliability and sub-millisecond accuracy in service health reporting.

2. Problem Statement

Modern distributed systems are prone to localized regional failures and intermittent latency spikes that traditional "uptime" monitors often miss. Furthermore, when outages occur, development teams are frequently diverted from remediation to manual status communication. There is a critical need for a tool that not only detects failure across global regions with high precision but also automates the "narrative" of the incident for public and internal stakeholders.

3. Goals & Success Metrics

  • Reliability: Achieve 99.99% uptime for the public status page, even during origin failure.
  • Precision: Support health check frequencies down to 10 seconds with <1ms execution jitter.
  • User Efficiency: Reduce the "Time to Public Update" (TTPU) from detection to status page update to under 60 seconds.
  • Scalability: Support 10,000+ concurrent health checks per runner node.
  • Adoption: Target 500+ active organizations within the first six months.

4. User Personas

  • SRE/DevOps Engineer (Sam): Needs deep technical data, multi-region validation, and integration with PagerDuty to minimize MTTR.
  • Support Manager (Sara): Needs a clear, non-technical status page to share with customers and reduce support ticket volume during outages.
  • Technical Founder (Alex): Needs a cost-effective, easy-to-set-up solution that grows with their SaaS product.

5. User Stories

  • As Sam, I want to configure health checks from five different global regions so that I can identify localized ISP or regional AWS failures.
  • As Sam, I want to use UUIDv7-indexed time-series data so that I can query 90 days of latency trends without performance degradation.
  • As Sara, I want an AI-generated summary of an incident based on the error code so that I can post a professional update quickly.
  • As Alex, I want to point my custom domain (status.mycompany.com) to StatPulse and have SSL automatically provisioned.

6. Functional Requirements

6.1 Monitoring & Execution

  • Multi-Region Runners: Deployment of health check workers in at least 6 AWS regions (us-east-1, eu-central-1, ap-southeast-1, etc.).
  • Health Check Protocols: Support for HTTP/S, gRPC, and TCP checks with custom headers and body validation.
  • Performance Thresholds: Alerting based on P95/P99 latency triggers, not just binary up/down status.

6.2 Incident Management

  • Auto-Incident Creation: System creates a "Draft" incident when a monitor fails across >50% of configured regions.
  • Manual Overrides: Ability for admins to manually trigger "Maintenance Mode" or "Degraded Performance" status.
  • Timeline Logging: A structured log of "Investigating," "Identified," "Monitoring," and "Resolved" states.

6.3 Public Status Pages

  • Custom Branding: Support for logos, custom CSS variables, and "Liquid Glass" UI themes.
  • Uptime Heatmaps: GitHub-style 90-day activity grids.
  • Subscription Management: Users can subscribe to specific components via Email, Slack, or SMS.

7. Technical Requirements

7.1 Tech Stack (2026 Standards)

  • Frontend: Next.js 16.1.3 utilizing Turbopack, React Compiler (reactCompiler: true), and the use cache directive for granular caching of status data.
  • Control Plane (API): Node.js 25 with NestJS, serving as the orchestrator for configuration and user management.
  • Execution Plane (Runners): Go 1.26 utilizing "Green Tea" GC for high-concurrency, low-memory health check probes.
  • Database: PostgreSQL 17 + TimescaleDB for time-series metrics, utilizing UUIDv7 for time-ordered indexing and S3-backed tiered storage for data >30 days.
  • Authentication: Clerk (for multi-tenant organization management and Next.js 16 RSC compatibility).
  • Infrastructure: AWS ECS Fargate for runners, AWS Global Accelerator for rapid regional failover.

7.2 Integrations

  • Incident Response: PagerDuty (V3 Webhooks), Opsgenie.
  • Notifications: Slack (Block Kit), Discord, Twilio SMS.
  • Automation: Webhook signature verification (HMAC-SHA256) for all outgoing alerts.

8. Data Model

| Entity | Attributes | Relationships | | :--- | :--- | :--- | | Organization | id (UUIDv7), name, slug, plan_tier | Has many Monitors, Users | | Monitor | id, url, frequency, regions (Array), status | Belongs to Org; Has many CheckResults | | CheckResult | time (Primary Key), monitor_id, latency_ms, status_code | Hypertable (TimescaleDB) | | Incident | id, monitor_id, impact_level (Enum), is_resolved | Belongs to Monitor; Has many IncidentUpdates | | StatusPage | id, custom_domain, theme_config, is_private | Belongs to Org |

9. API Specification

9.1 Monitor Management

  • POST /api/v1/monitors: Create a new monitoring endpoint.
  • GET /api/v1/monitors/:id/stats: Returns P99 latency and uptime % for a specific time range.

9.2 Public Status Data

  • GET /api/v1/status/:slug: Edge-cached endpoint for public status page data (uses Next.js 16 proxy.ts for routing).

10. UI/UX Requirements

  • Dashboard Layout: Bento Grid design for the admin overview, providing high-density metrics at a glance.
  • Visualizations:
    • Nivo for 90-day uptime calendar heatmaps.
    • Apache ECharts for high-cardinality latency distribution (Boxplots).
  • Design System: "Liquid Glass" aesthetics (translucent layers, soft motion) with full accessibility (ARIA-compliant charts).

11. Non-Functional Requirements

  • Performance: Public status page must achieve a Lighthouse score of 95+ and load in <500ms globally via Edge Caching.
  • Security: API keys and custom headers stored in AWS Nitro Enclaves (TEEs). JIT secret injection for runner tasks.
  • Availability: The execution plane (Go runners) must be isolated from the Control Plane to ensure checks continue even if the UI is down.

12. Out of Scope

  • Log aggregation and analysis (ELK-style).
  • Synthetic browser testing (Playwright/Puppeteer support).
  • APM (Application Performance Monitoring) agents.

13. Risks & Mitigations

  • Risk: Let's Encrypt rate limits for thousands of custom domains.
    • Mitigation: Implement Caddy "On-Demand TLS" with a secondary CA fallback (ZeroSSL).
  • Risk: High AWS costs for multi-region ECS tasks.
    • Mitigation: Use Go's resource efficiency to run on the smallest Fargate task sizes (0.25 vCPU).

14. Implementation Tasks

Phase 1: Project Setup & Infrastructure

  • [ ] Initialize Next.js 16.1.3 project with Turbopack and Tailwind CSS
  • [ ] Set up Go 1.26 workspace for health check runners
  • [ ] Provision AWS Aurora (Postgres) with TimescaleDB extension
  • [ ] Configure Clerk for Organization/Multi-tenant auth

Phase 2: Core Monitoring Engine

  • [ ] Implement Go-based HTTP probe with concurrent goroutines
  • [ ] Build NestJS "Orchestrator" API to distribute check tasks via Redis Streams
  • [ ] Create TimescaleDB hypertable for CheckResult with UUIDv7
  • [ ] Implement automated compression policy (7-day window)

Phase 3: Admin Dashboard & Analytics

  • [ ] Build Bento Grid dashboard in Next.js
  • [ ] Integrate Apache ECharts for P95/P99 latency distribution charts
  • [ ] Implement Nivo calendar component for uptime history
  • [ ] Develop "Incident Creator" workflow with AI-assisted summary drafting

Phase 4: Public Status & Custom Domains

  • [ ] Build public-facing status page with "Liquid Glass" UI
  • [ ] Set up Caddy server with "On-Demand TLS" for custom domain support
  • [ ] Implement proxy.ts for efficient edge-routing of status requests
  • [ ] Configure S3-backed tiered storage for historical data retention

Phase 5: Integrations & Security

  • [ ] Build PagerDuty V3 Webhook integration with signature verification
  • [ ] Implement AWS Nitro Enclaves for secure API key storage
  • [ ] Add Slack Block Kit notification engine
  • [ ] Perform final accessibility audit (WCAG 2.1 Level AA)