---
title: Getting Started
---

Welcome to the **Business Platform** developer guide. This page walks you through setting up a local development environment and covers important first-run behaviour you need to be aware of.

---

## Prerequisites

Before you begin, make sure you have the following installed:

- [Node.js](https://nodejs.org/) (check `.nvmrc` or `package.json` for the required version)
- [npm](https://www.npmjs.com/) (ships with Node.js)
- [MongoDB](https://www.mongodb.com/) (local instance or a connection string to a remote instance)
- [Git](https://git-scm.com/)

---

## Installation

Clone the repository and install dependencies:

```bash
git clone <repository-url>
cd business-platform
npm ci
```

---

## Running the Application Locally

Start the backoffice development server:

```bash
npm run dev
```

The application will be available at `http://localhost:5173` by default.

---

## First-Run: Promoting a User to Platform Owner

When running the application in **development mode**, the first user to register is automatically eligible to become the **platform owner**. The platform owner has full administrative access to the platform.

### How It Works

1. Start the application in development mode.
2. Register the first user account via the normal registration flow.
3. The server detects that exactly **one user** exists in the database and generates a one-time promotion token.
4. A URL is printed to the **server log** (stdout) in the following format:

```
[DEV] First user registered! Make them a platform owner:
[DEV] http://localhost:5173/api/admin/dev/platform-owner/<token>
```

5. Open that URL in your browser (or `curl` it). The user will be promoted to platform owner immediately.

### Endpoint Details

| Property | Value |
|---|---|
| Method | `GET` |
| Path | `/api/admin/dev/platform-owner/[token]` |
| Available in | Development mode only |
| Token expiry | **10 minutes** from registration |
| User count requirement | Exactly **1 user** must exist in the database |

### Constraints and Error Cases

- **Production unavailable** — The endpoint returns `404 Not Found` when the application is not running in development mode.
- **Token expired** — Tokens are valid for **10 minutes**. If the token has expired, the endpoint returns `403 Forbidden` with the message `"Invalid or expired token"`. Re-register or restart the server to obtain a new token.
- **Token already used** — Each token is single-use. Once consumed it is deleted from memory; re-using it will return `403 Forbidden`.
- **More than one user exists** — If more than one user has registered, the endpoint returns `403 Forbidden` with the message `"This endpoint only works when there is exactly 1 user"`. This is a deliberate safety guard to prevent accidental privilege escalation.

### Example

```bash
# Copy the URL from the server log and open it, e.g.:
curl http://localhost:5173/api/admin/dev/platform-owner/a1b2c3d4...

# Success response:
# { "success": true, "message": "User has been promoted to platform owner" }
```

> **Note:** This flow relies entirely on in-memory token storage. Restarting the server will invalidate any pending tokens.

---

## Development Utilities

### Email Sending

In development mode (and during E2E tests), outbound emails are **not delivered**. Instead, the full email content is printed to the server log:

```
[DEV] Would send this mail:
    { "to": "...", "subject": "...", ... }
with this config:
    { ... }
```

This allows you to inspect verification links, invitation emails, and other transactional messages without needing an SMTP server.

---

## Environment Modes

The application uses `isDevelopment()` to gate behaviour that should never run in production. Any feature or endpoint guarded by this check (including the platform owner promotion endpoint above) is automatically disabled when the `NODE_ENV` is not `development`.

Always verify your environment configuration before running the application to ensure development-only features are not exposed.