Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/LENINMORENO13/OpsMind/llms.txt

Use this file to discover all available pages before exploring further.

OpsMind is built as a collection of tightly coordinated layers — each with a single responsibility — that together deliver continuous uptime monitoring, trend analysis, and AI-powered incident diagnosis. An Express 5 HTTP API handles client interactions, a node-cron background worker drives autonomous checks every five minutes, a set of focused service modules perform health checks and derive state, and a Prisma-backed PostgreSQL database persists every log and AI insight. Understanding how these layers interact helps you extend OpsMind, debug unexpected behavior, and reason about its operational guarantees.

​
Architectural Layers

1

HTTP API Layer

The entry point is an Express application that binds on port 3000 (or the value of process.env.PORT). Two route groups are mounted:
Route prefixPurpose
/api/v1/authRegistration and login (public)
/api/v1/monitorsFull monitor CRUD and history (JWT-protected)
Every request to /api/v1/monitors passes through the verifyToken middleware before reaching a controller. verifyToken reads the Authorization: Bearer <token> header, verifies the JWT against process.env.JWT_SECRET, and attaches the decoded payload to req.user. Requests without a valid token receive a 401 response immediately.A Swagger UI is served at /api-docs and the root / redirects there for convenience.
2

Service Layer

Three modules form the core logic tier:

checker.js

Fires an axios.get with a 5-second timeout against the monitor’s URL. Returns online, status, responseTime, and any error message. HTTP 2xx responses mark online: true; all network failures or non-2xx responses set online: false with status: 0 when there is no response.

analyzer.js

Accepts the raw check result and the last persisted Log record. Derives a ServiceStatus (UP, DEGRADED, DOWN) and a TrendStatus (STABLE, DROP_DETECTED, RECOVERED, OFFLINE) by comparing the current check against the previous state. Also resolves human-readable HTTP status code descriptions.

historyService.js

Orchestrates the full pipeline through executeMonitorCheck. It fetches the last log, calls checker, calls analyzer, persists the new Log, and — when DROP_DETECTED is returned — invokes the AI layer and persists an AIInsight. Also exposes getHistory (last 10 logs, descending) and getLastRecord helpers.
3

Background Worker

scheduler.js registers a single node-cron job using the expression */5 * * * *, which fires once every five minutes. On each tick it loads all Monitor records from the database and calls executeMonitorCheck for each one sequentially. Errors on individual monitors are caught and logged so that a failure on one monitor does not abort the remaining checks in the cycle.
cron.schedule("*/5 * * * *", async () => {
  const monitors = await prisma.monitor.findMany();
  for (const monitor of monitors) {
    await executeMonitorCheck(monitor);
  }
});
The scheduler is started inside the app.listen callback so it never runs during automated tests (NODE_ENV !== "test").
4

AI Layer

aiServices.js exports a single function, analyzeIncident(monitorName, url, errorDetails). When called, it constructs a structured prompt framing the request as a Senior SRE alert diagnosis, then sends it to the Google Gemini gemini-2.5-flash-lite model with responseMimeType: "application/json" and a strict response schema. The returned JSON is parsed and returned to the caller.If the Gemini API responds with a 429 (rate-limited) or 503/UNAVAILABLE error the function waits 10 seconds and retries — up to 3 times — before falling back to a static error object. The AIInsight record is only persisted when the AI call succeeds (or returns its fallback); the criticality is set to CRITICAL when the current state is DOWN, or HIGH when it is DEGRADED.
5

Data Layer

All persistence goes through Prisma ORM connected to a PostgreSQL database. Four models cover the full domain — see Data Models below. Prisma’s type-safe client is used throughout the service layer; there is no raw SQL in the application code.

​
Architecture Diagram

The diagram below traces every path a request or scheduled event can take through the system.

​
Request Lifecycle

When an authenticated client triggers a monitor check through the API, the following sequence occurs:
1

JWT Verification

The verifyToken middleware extracts the Bearer token from the Authorization header and verifies it against JWT_SECRET. On failure, a 401 is returned immediately.
2

Controller Dispatch

The monitor controller reads the target monitor from the database and calls historyService.executeMonitorCheck(monitor).
3

HTTP Check

checker.check(url) fires an HTTP GET with a 5-second timeout and returns the raw result including online, status, responseTime, and error.
4

State Analysis

analyzer.analyzeStatus(currentCheck, lastRecord) compares the new result against the last persisted log to compute ServiceStatus and TrendStatus.
5

Log Persistence

A new Log record is written to PostgreSQL via prisma.log.create with the current status, state, trend, response time, and any error detail.
6

Conditional AI Call

If analysisResult.trend === "DROP_DETECTED", aiServices.analyzeIncident is invoked. On success, an AIInsight record is persisted with the Gemini diagnosis, remediation suggestion, and a criticality of CRITICAL or HIGH.

​
Data Models

The Prisma schema defines four models. Key fields for each are listed below.

Monitor

The top-level entity representing a service being watched.
FieldTypeDescription
idIntAuto-incremented primary key
urlStringUnique URL to check
nameStringHuman-readable service name
isActiveBooleanWhether the monitor is enabled
checkIntervalIntPolling interval in seconds (default 300)
lastStatusServiceStatusMost recent status enum value
createdAtDateTimeRecord creation timestamp
updatedAtDateTimeLast update timestamp

Log

An immutable record of a single health-check execution.
FieldTypeDescription
idIntAuto-incremented primary key
statusIntRaw HTTP status code
responseTimeIntResponse time in milliseconds
errorString?Error message if the check failed
trendTrendStatusComputed trend vs. previous log
stateServiceStatusComputed service state
timestampDateTimeWhen the check ran
monitorIdIntForeign key to Monitor

AIInsight

Stores the structured Gemini AI diagnosis for a detected incident.
FieldTypeDescription
idIntAuto-incremented primary key
analysisStringAI’s probable cause (Text)
suggestionString?AI’s recommended action (Text)
criticalityCriticalityLevelCRITICAL or HIGH
createdAtDateTimeWhen the insight was created
monitorIdIntForeign key to Monitor

User

An authenticated operator who can manage monitors via the API.
FieldTypeDescription
idIntAuto-incremented primary key
emailStringUnique email address
passwordStringHashed password
createdAtDateTimeAccount creation timestamp
updatedAtDateTimeLast update timestamp

Build docs developers (and LLMs) love

Get started for freeTalk to us