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 (check .nvmrc or package.json for the required version)
  • npm (ships with Node.js)
  • MongoDB (local instance or a connection string to a remote instance)
  • Git

Installation

Clone the repository and install dependencies:

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

Running the Application Locally

Start the backoffice development server:

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>
  1. 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

# 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.

Markdown | llm.txt