Project structure
How the Checkmate codebase is organized.
Overview
Checkmate is a monorepo with a Node.js/Express backend and a React frontend. The backend handles monitoring logic, API endpoints and notifications; the frontend provides the user interface.
checkmate/
├── server/ # Backend — Node.js, Express, TypeScript
├── client/ # Frontend — React, Vite, MUI, TypeScript
├── docker/ # Dockerfile and Compose files
├── charts/ # Kubernetes Helm charts
├── docs/ # Documentation and specs
├── scripts/ # Development and utility scripts
└── .github/ # CI/CD workflows and issue templatesServer structure
The backend is organised by domain rather than by layer. HTTP concerns live under api/, and each business entity owns its own folder under domain/ containing its model, schema, types, service and repository.
server/src/
├── index.ts # Entry point — env validation, DB init, server/worker start
├── app.ts # Express app factory — middleware, routes, Swagger
├── shutdown.ts # Graceful shutdown handling
├── api/ # Everything HTTP
│ ├── controllers/ # Request handlers (20 files)
│ ├── routes/ # Route tables (20 *Routes.ts files)
│ ├── middleware/ # Auth, rate limiting, error handling (12 files)
│ └── validation/ # Request validation schemas (17 files)
├── domain/ # Business logic, one folder per entity (26 domains)
├── service/ # Cross-cutting services
│ ├── networkProviders/ # One provider per monitor type
│ ├── encryption/ # Encryption and key handling
│ ├── emailService.ts # SMTP transport
│ ├── statusService.ts # Status transitions and hardware alerting
│ └── bufferService.ts
├── worker/ # Job queue, scheduler and check pipeline
├── db/ # Database interface, Mongo implementation, migrations
├── config/ # Environment validation and route registration
├── templates/ # Email templates
├── types/ # Shared types
└── utils/ # HelpersDomain folders
Each entity under domain/ follows the same file pattern. For example, domain/monitors/:
monitor.model.ts # Mongoose model
monitor.schema.ts # Zod schema (also feeds OpenAPI)
monitor.type.ts # Shared types and constants
monitor.service.ts # Business logic
monitor.repository.interface.ts # Repository contract
monitor.repository.mongo.ts # MongoDB implementation
monitor.errors.ts # Typed errorsThe 26 domains are: app-settings, app-version, checks, connect, diagnostics, dlq, docker, egress, geo-checks, heartbeat, incidents, invites, jobs, maintenance-windows, migrations, monitor-stats, monitors, notifications, proxies, queue-workers, recovery-tokens, status-pages, tags, teams, telemetry, users.
Worker
The job queue is MongoDB-backed, there is no Redis or external message broker.
worker/
├── worker.db-queue.ts # MongoDB-backed queue
├── worker.job-scheduler.ts # Schedules jobs from monitor intervals
├── worker.pipeline.ts # Runs a check end to end
├── worker.geo-pipeline.ts # Geo check variant
├── worker.health-server.ts # /livez, /readyz, /metrics
├── worker.helper.ts
└── reactors/ # Reacts to check resultsMonitor providers
service/networkProviders/ holds one provider per monitor type, plus shared helpers:
DNSProvider, DockerProvider, GameProvider, GrpcProvider, HardwareProvider, HeartbeatProvider, HttpProvider, PageSpeedProvider, PingProvider, PortProvider, WebSocketProvider, alongside AdvancedMatcher.ts, providerRegistry.ts, ProxyResolver.ts and IStatusProvider.ts.
Notification providers
domain/notifications/providers/ holds the 13 notification channels: discord, email, matrix, ntfy, pagerduty, pushover, rocketChat, signalgrid, slack, teams, telegram, twilio, webhook, plus INotificationProvider.ts and utils.ts.
Client structure
client/src/
├── main.tsx # Entry point
├── App.tsx # Root component
├── Routes/ # Route definitions
├── Pages/ # Page components (18 areas)
├── Components/ # Shared UI components
├── Features/ # Redux slices
├── Hooks/ # Custom hooks, including data fetching
├── Utils/ # Helpers
├── Types/ # Shared types
├── Validation/ # Joi and Zod validation schemas
├── locales/ # 19 language translation files
└── store.ts # Redux storei18n: 19 languages via i18next, with en.json as the source file. See Language and localization.
Data layer
Checkmate uses MongoDB as its only datastore. The job queue is MongoDB-backed as well, so there is no Redis or message broker to operate.
Database access goes through a repository interface (db/db.interface.ts) with a MongoDB implementation (db/db.mongo.ts), and each domain supplies its own repository. Pending migrations in db/migration/ run automatically at startup, followed by an index sync, before the server starts listening.
API routes
Routes are registered in config/routes.ts, all under the /api/v1 prefix:
| Path | Purpose |
|---|---|
/auth | Login, registration, user management |
/monitors | Monitor CRUD, pause/resume, import/export |
/checks | Check history |
/geo-checks | Distributed check results |
/incidents | Incident list, detail and resolution |
/notifications | Notification channels |
/maintenance-window | Maintenance windows |
/status-page | Status page config and public payload |
/settings | Global application settings |
/invite | Team invitations |
/teams | Team settings, heartbeat ping key |
/tags | Monitor tags |
/proxies | Outbound proxies |
/egress | Egress self-check targets |
/heartbeat | Heartbeat ping ingestion |
/queue | Job queue metrics, flush |
/logs | Application logs (admin+) |
/diagnostic | System diagnostics (admin+) |
/connect | Checkmate Connect |
GET /api/v1/health is served separately and OpenAPI documentation is available at /api-docs on every running server.