Development

Set up a local development environment and understand the project structure

Prerequisites

• Node.js version 19 or higher
• MongoDB (local via Docker or Atlas)
• A Resend API key for transactional email

Running locally

Navigate to the monitor-web directory and start the dev server:

cd monitor-web
npm run dev

The application runs on port 9100 by default:

http://localhost:9100

Environment variables

Create a .env file inside monitor-web/ (copy .env.example if present). Required variables:

Variable	Description
MONGODB_URI	MongoDB connection string
SESSION_SECRET	Random secret used to sign cookies
RESEND_API_KEY	Resend API key for email delivery
NEXT_PUBLIC_APP_URL	Public base URL of the app (used in generated links)
SMTP_HOST / SMTP_PORT	SMTP fallback for email when Resend is unavailable

Project structure

monitor-web/
├── app/
│   ├── (app)/            # Authenticated routes (dashboard, monitors, incidents…)
│   ├── (auth)/           # Login, register, OTP verification
│   ├── api/v1/           # REST API handlers (Next.js Route Handlers)
│   └── status/           # Public status page routes
├── components/           # React components (forms, sidebar, charts…)
├── lib/
│   ├── models/           # Mongoose models (Monitor, Incident, AlertChannel…)
│   ├── mongodb.ts        # DB connection singleton
│   └── auth-session.ts   # Session helpers
├── utils/                # Shared utilities (HTTP client, formatters)
└── scripts/              # Build-time scripts (OpenAPI generation)

Generating the OpenAPI spec

Monitor auto-generates an OpenAPI JSON spec from its route handlers at build time:

npm run openapi:generate

The spec is written to docs/api-reference/openapi.json and used by the API Reference tab in these docs.

It also runs automatically before every production build (prebuild hook):

npm run build

Tech stack

Concern	Library
Framework	Next.js 16 with App Router
UI components	Radix UI + shadcn/ui
Styling	Tailwind CSS v4
Forms	Formik + Yup
Database	MongoDB via Mongoose
Email	Resend · Nodemailer (fallback)
Charts	Recharts
State	Zustand

Linting

npm run lint

Troubleshooting

MongoDB connection errors on startup

Ensure your MONGODB_URI is set correctly in .env and that your MongoDB instance is running. For Atlas, check that your IP is whitelisted.

Emails not sending

Verify RESEND_API_KEY is set and valid. If using SMTP fallback, confirm SMTP_HOST and SMTP_PORT are reachable from your machine.

Port 9100 already in use

Change the port in monitor-web/package.json under the "dev" script:

"dev": "next dev -p YOUR_PORT"