Checkmate
DocumentationGetting started

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 templates

Server 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/            # Helpers

Domain 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 errors

The 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 results

Monitor 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 store

i18n: 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:

PathPurpose
/authLogin, registration, user management
/monitorsMonitor CRUD, pause/resume, import/export
/checksCheck history
/geo-checksDistributed check results
/incidentsIncident list, detail and resolution
/notificationsNotification channels
/maintenance-windowMaintenance windows
/status-pageStatus page config and public payload
/settingsGlobal application settings
/inviteTeam invitations
/teamsTeam settings, heartbeat ping key
/tagsMonitor tags
/proxiesOutbound proxies
/egressEgress self-check targets
/heartbeatHeartbeat ping ingestion
/queueJob queue metrics, flush
/logsApplication logs (admin+)
/diagnosticSystem diagnostics (admin+)
/connectCheckmate Connect

GET /api/v1/health is served separately and OpenAPI documentation is available at /api-docs on every running server.

On this page

Was this page helpful?