> ## Documentation Index
> Fetch the complete documentation index at: https://monitor-f3599674.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Development

> Set up a local development environment and understand the project structure

<Info>
  **Prerequisites**

  * Node.js version 19 or higher
  * MongoDB (local via [Docker](https://www.mongodb.com/docs/manual/installation/) or [Atlas](https://www.mongodb.com/atlas))
  * A Resend API key for transactional email
</Info>

## Running locally

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

```bash theme={null}
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](https://resend.com) 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:

```bash theme={null}
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):

```bash theme={null}
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

```bash theme={null}
npm run lint
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Port 9100 already in use">
    Change the port in `monitor-web/package.json` under the `"dev"` script:

    ```json theme={null}
    "dev": "next dev -p YOUR_PORT"
    ```
  </Accordion>
</AccordionGroup>