A production-grade distributed API health monitoring system with real-time alerting, incident management, and full observability.
- Real-time Monitoring — Continuous health checks at configurable intervals
- Incident Detection — Automatic threshold-based incident creation and tracking
- Multi-channel Alerts — Email and webhook notifications with retry mechanisms
- Full Observability — Prometheus metrics, structured logging, health endpoints
- Horizontal Scaling — Microservices architecture with BullMQ job queues
- Modern Dashboard — Next.js web interface for monitor management
┌─────────────────────────────────────────────────────────────────┐
│ INFRASTRUCTURE │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ AWS / Docker ││
│ └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘
│
┌───────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ FRONTEND │ │ BACKEND │ │ WORKERS │
├───────────────┤ ├───────────────┤ ├───────────────┤
│ │ HTTP/REST │ │ Job Queue │ │
│ ┌─────────┐ │────────────────────────────────────────▶│ ┌─────────┐ │─────────────────────────────────────────▶│ ┌─────────┐ │
│ │ Next.js │ │ │ │ Express │ │ │ │ Worker │ │
│ │ Web │ │◀────────────────────────────────────────│ │ API │ │ │ │ Process │ │
│ │ App │ │ JSON Response │ │ :4000 │ │ │ │ :4001 │ │
│ └─────────┘ │ │ └─────────┘ │ │ └─────────┘ │
│ :3000 │ │ │ │ │ │ │
└───────────────┘ │ │ │ │ │ │
│ ▼ │ │ ▼ │
│ ┌─────────┐ │ │ ┌─────────┐ │
│ │Scheduler│ │ │ │Incident │ │
│ │ Service │ │ │ │ Manager │ │
│ │ :4002 │ │ │ └─────────┘ │
│ └─────────┘ │ │ │ │
└───────────────┘ │ ▼ │
│ │ ┌─────────┐ │
│ │ │Notifier │ │
│ │ │ Service │ │
│ │ │ :4003 │ │
│ │ └─────────┘ │
│ └───────────────┘
│ │
┌───────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────┘
│ │
▼ ▼
┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ DATA LAYER │
├───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────┐ ┌─────────────────────────────────────┐ │
│ │ PostgreSQL │ │ Redis │ │
│ ├─────────────────────────────────────┤ ├─────────────────────────────────────┤ │
│ │ • Users & Authentication │ │ • BullMQ Job Queues │ │
│ │ • Monitors Configuration │ │ • health-check-queue │ │
│ │ • Health Check Results │ │ • notification-queue │ │
│ │ • Incidents & Alerts │ │ • Dead Letter Queue (DLQ) │ │
│ │ • Notification Logs │ │ • Rate Limiting (future) │ │
│ └─────────────────────────────────────┘ └─────────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ │
│ 1️⃣ MONITOR CREATION 2️⃣ JOB SCHEDULING 3️⃣ HEALTH CHECK EXECUTION │
│ ───────────────────── ────────────────── ────────────────────────── │
│ │
│ ┌────────┐ POST /monitors ┌─────┐ ┌───────────┐ Enqueue Job ┌───────┐ ┌────────┐ HTTP GET ┌──────────────┐ │
│ │ User │─────────────────▶│ API │──▶│ Scheduler │──────────────▶│ Redis │──▶│ Worker │─────────────▶│ Target API │ │
│ └────────┘ └─────┘ └───────────┘ └───────┘ └────────┘ └──────────────┘ │
│ │ │ │ │
│ ▼ ▼ │ │
│ ┌────────────┐ ┌────────────┐ │ │
│ │ PostgreSQL │◀─────────────────────────────────────│Save Result │◀──────────────────┘ │
│ └────────────┘ └────────────┘ │
│ │
├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ 4️⃣ INCIDENT DETECTION 5️⃣ NOTIFICATION DELIVERY │
│ ────────────────────── ──────────────────────── │
│ │
│ ┌────────┐ Threshold Breach ┌──────────────┐ ┌───────┐ Dequeue ┌──────────┐ ┌─────────────────────────────────┐ │
│ │ Worker │───────────────────▶│ Create │──▶│ Redis │─────────▶│ Notifier │──▶│ Email (Resend) │ │
│ └────────┘ │ Incident │ └───────┘ └──────────┘ │ Webhook (HTTP POST) │ │
│ │ └──────────────┘ │ │ Slack/Discord (future) │ │
│ │ │ │ └─────────────────────────────────┘ │
│ │ ▼ │ │
│ │ ┌────────────┐ │ Retry with Exponential Backoff │
│ │ │ PostgreSQL │ │ ┌─────┐ ┌─────┐ ┌─────┐ │
│ │ └────────────┘ └─▶│ 1s │──▶│ 2s │──▶│ 4s │──▶ DLQ │
│ ▼ └─────┘ └─────┘ └─────┘ │
│ ┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ STATE MACHINE │ │
│ ├─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤ │
│ │ 🟢 HEALTHY ──[failures >= threshold]──▶ 🔴 INCIDENT ──[successes >= threshold]──▶ 🟢 RESOLVED │ │
│ └─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ │
│ SERVICE MESH │
│ │
│ ┌──────────────────────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ Web │ │ API │ │Scheduler│ │ Worker │ │Notifier │ │ │
│ │ │ :3000 │ │ :4000 │ │ :4002 │ │ :4001 │ │ :4003 │ │ │
│ │ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ │
│ │ │ │ │ │ │ │ │
│ │ │ ┌──────────────┴───────────────────┴───────────────────┴───────────────────┘ │ │
│ │ │ │ │ │
│ │ │ │ ┌─────────────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ │ │ OBSERVABILITY LAYER │ │ │
│ │ │ │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │
│ │ │ │ │ │ │ │
│ │ │ │ │ /metrics ────────▶ Prometheus ────────▶ Grafana Dashboards │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ │ 💚 /health │ │ │
│ │ │ │ │ 💚 /ready │ │ │
│ │ │ │ │ 💚 /live │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ │ 📝 Pino Logs ───────▶ Structured JSON ────────▶ Log Aggregator │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │ │ │
│ └────────┼────┼───────────────────────────────────────────────────────────────────────────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ PERSISTENCE LAYER │ │
│ ├─────────────────────────────────────────────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ ┌──────────────────────────┐ ┌──────────────────────────┐ │ │
│ │ │ PostgreSQL │ │ Redis │ │ │
│ │ │ (Primary DB) │ │ (Message Broker) │ │ │
│ │ │ │ │ │ │ │
│ │ │ ┌────────────────────┐ │ │ ┌────────────────────┐ │ │ │
│ │ │ │ users │ │ │ │ health-check-queue │ │ │ │
│ │ │ │ monitors │ │ │ │ notification-queue │ │ │ │
│ │ │ │ health_check_results │ │ │ dead-letter-queue │ │ │ │
│ │ │ │ incidents │ │ │ └────────────────────┘ │ │ │
│ │ │ │ notifications │ │ │ │ │ │
│ │ │ └────────────────────┘ │ │ │ │ │
│ │ └──────────────────────────┘ └──────────────────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
| Category | Technology |
|---|---|
| Runtime | Node.js 18+, TypeScript |
| Backend | Express.js |
| Frontend | Next.js, React, Tailwind CSS |
| Database | PostgreSQL, Prisma ORM |
| Queue | Redis, BullMQ |
| Observability | Prometheus, Pino |
| Auth | JWT, bcrypt |
| Infrastructure | Docker, Terraform (AWS) |
- Node.js 18+
- PostgreSQL
- Redis
# Clone and install
git clone https://github.com/sAchin-680/HyperVerge-api-health-monitor-system.git
cd HyperVerge-api-health-monitor-system
npm install
# Setup database
npx prisma migrate deploy --schema=packages/db/prisma/schema.prisma
npx prisma generate --schema=packages/db/prisma/schema.prisma
# Copy environment template
cp .env.example .env# Database
DATABASE_URL="postgresql://user:password@localhost:5432/healthmonitor"
# Redis
REDIS_URL="redis://localhost:6379"
# Auth
JWT_SECRET="your-secret-key"# Using Make (recommended)
make dev
# Or individually
npm run dev --workspace=apps/api # :4000
npm run dev --workspace=apps/scheduler # :4002
npm run dev --workspace=apps/worker # :4001
npm run dev --workspace=apps/notifier # :4003
npm run dev --workspace=apps/web # :3000docker-compose up├── apps/
│ ├── api/ # REST API service
│ │ ├── src/
│ │ │ ├── controllers/ # Request handlers
│ │ │ ├── routes/ # API route definitions
│ │ │ ├── services/ # Business logic
│ │ │ ├── middlewares/ # Auth, validation, logging
│ │ │ ├── validators/ # Zod schemas
│ │ │ └── lib/ # Shared utilities
│ │ └── prisma/ # Database schema
│ │
│ ├── scheduler/ # Job scheduling service
│ │ └── src/
│ │ ├── index.ts # Scheduler entry point
│ │ └── lib/ # Scheduling logic
│ │
│ ├── worker/ # Health check executor
│ │ └── src/
│ │ ├── worker.ts # BullMQ worker
│ │ ├── checkExecutor.ts
│ │ ├── stateEvaluator.ts
│ │ └── incidentManager.ts
│ │
│ ├── notifier/ # Notification service
│ │ └── src/
│ │ ├── providers/ # Email, webhook providers
│ │ ├── queue/ # Notification queue
│ │ └── services/ # Delivery logic
│ │
│ └── web/ # Next.js dashboard
│ └── src/
│ ├── app/ # App router pages
│ ├── components/ # React components
│ └── hooks/ # Custom hooks
│
├── packages/
│ ├── db/ # Shared Prisma client
│ │ └── prisma/schema.prisma
│ └── shared/ # Shared types
│ └── src/types.ts
│
├── architecture/ # Architecture documentation
├── runbooks/ # Operational runbooks
├── terraform/ # AWS infrastructure (ECS, RDS, etc.)
│ ├── modules/
│ │ ├── vpc/
│ │ ├── ecs/
│ │ ├── rds/
│ │ ├── alb/
│ │ └── security/
│ └── envs/ # Environment configs
│
├── docker-compose.yml
├── Makefile
└── package.json
| Method | Endpoint | Description |
|---|---|---|
| POST | /auth/register |
Register user |
| POST | /auth/login |
Login user |
| Method | Endpoint | Description |
|---|---|---|
| GET | /monitors |
List monitors |
| POST | /monitors |
Create monitor |
| GET | /monitors/:id |
Get monitor |
| PATCH | /monitors/:id |
Update monitor |
| DELETE | /monitors/:id |
Delete monitor |
| Method | Endpoint | Description |
|---|---|---|
| GET | /health |
Health check |
| GET | /ready |
Readiness probe |
| GET | /live |
Liveness probe |
| GET | /metrics |
Prometheus metrics |
| Document | Description |
|---|---|
| Architecture Overview | System design and data flow |
| Engineering Log | Design decisions and tradeoffs |
| Runbooks | Operational procedures |
| Deployment Guide | Deployment instructions |
| Terraform | Infrastructure as Code |
- Fork the repository
- Create a feature branch (
git checkout -b feature/your-feature) - Commit your changes (
git commit -m 'feat: add feature') - Push to your branch (
git push origin feature/your-feature) - Open a Pull Request
MIT License - see LICENSE for details