Skip to content

Latest commit

 

History

History
145 lines (122 loc) · 4.79 KB

CLAUDE.md

File metadata and controls

145 lines (122 loc) · 4.79 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Checkmate is an open-source uptime and infrastructure monitoring application. It monitors server hardware, uptime, response times, and incidents with real-time alerts. The companion agent Capture provides infrastructure metrics (CPU, RAM, disk, temperature).

Development Commands

Client (React/Vite)

cd client
npm install
npm run dev              # Start dev server at http://localhost:5173
npm run build            # TypeScript check + production build
npm run lint             # ESLint (strict, max-warnings 0)
npm run format           # Prettier formatting
npm run format-check     # Check formatting

Server (Node.js/Express)

cd server
npm install
npm run dev              # Start with hot-reload (nodemon + tsx) at http://localhost:52345
npm run build            # TypeScript compile + path alias resolution
npm run test             # Run Mocha tests with c8 coverage
npm run lint             # ESLint v9
npm run lint-fix         # Auto-fix lint issues
npm run format           # Prettier formatting

Docker Development

cd docker/dev
./build_images.sh
docker run -d -p 27017:27017 -v uptime_mongo_data:/data/db --name uptime_database_mongo mongo:6.0

Environment Setup

Server .env (minimum required)

CLIENT_HOST="http://localhost:5173"
JWT_SECRET="my_secret_key_change_this"
DB_CONNECTION_STRING="mongodb://localhost:27017/uptime_db"
TOKEN_TTL="99d"
ORIGIN="localhost"
LOG_LEVEL="debug"

Client .env

VITE_APP_API_BASE_URL="http://localhost:52345/api/v1"
VITE_APP_LOG_LEVEL="debug"

Architecture

Monorepo Structure

  • /client - React 18 + TypeScript + Vite + MUI frontend
  • /server - Node.js 20+ + Express + TypeScript backend
  • /docker - Multi-environment Docker configs (dev, staging, prod, arm, mono)

Backend Layers

server/src/
├── controllers/     # Route handlers (authController, monitorController, etc.)
├── service/         # Business logic
│   ├── business/    # Core monitoring logic
│   ├── infrastructure/  # Server/system utilities
│   └── system/      # App-level settings
├── db/
│   ├── models/      # Mongoose schemas (Monitor, Check, Incident, User, etc.)
│   ├── migration/   # Database migrations (run on startup)
│   └── modules/     # Database-specific modules
├── middleware/v1/   # verifyJWT, rateLimiter, sanitization, responseHandler
├── routes/v1/       # API route definitions
├── validation/      # Joi input validation schemas
└── repositories/    # Data access layer

Frontend Structure

client/src/
├── Components/      # Reusable UI components
├── Pages/           # Page components (Auth, Uptime, Infrastructure, Incidents, etc.)
├── Features/        # Redux slices (Auth, UI)
├── Hooks/           # Custom React hooks
├── Utils/           # Utilities (NetworkService.js is main API client)
├── Validation/      # Input validation
└── locales/         # i18n translations

API

  • Base URL: /api/v1
  • Documentation: http://localhost:52345/api-docs (Swagger UI)
  • OpenAPI spec: /server/openapi.json

Key Technologies

  • State Management: Redux Toolkit + Redux-Persist
  • Data Fetching: SWR + Axios
  • Database: MongoDB with Mongoose ODM
  • Queue/Cache: Redis + BullMQ + Pulse (cron scheduling)
  • i18n: i18next + react-i18next (translations via PoEditor)

Code Conventions

Internationalization

All user-facing strings must use the translation function:

t('your.key')  // Never hardcode UI strings

Branching

  • Always branch from develop (not master)
  • Use descriptive names: feat/add-alerts, fix/login-error
  • PRs target develop branch

Formatting

  • Client: Prettier with printWidth: 90, tabs, double quotes
  • Server: Prettier with printWidth: 150, tabs, double quotes
  • Both use ESLint with strict settings

Testing

Server tests use Mocha + Chai + Sinon:

npm test                    # Run all tests with coverage
npm test -- --grep "pattern"  # Run specific tests

Test files: server/tests/**/*.test.js

Database Models

Key Mongoose models in /server/src/db/models/:

  • Monitor - Monitoring configuration (website, infrastructure, port, etc.)
  • Check - Individual monitoring check results
  • Incident - Downtime incidents
  • User - User accounts
  • Team - Team/workspace management
  • StatusPage - Public status pages
  • Notification - Alert configuration (email, Discord, Slack, webhooks)
  • MaintenanceWindow - Scheduled maintenance periods
  • AppSettings - Global application settings