Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/GianlucaBessone/HDB-Service/llms.txt

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

This guide walks you through everything you need to get HDB Service running on your local machine. By the end you’ll have a fully functional development environment connected to a PostgreSQL database, seeded with a sample client hierarchy, and ready to log in as an ADMIN user. The entire process should take less than 10 minutes.
1

Clone the repository

Clone the HDB Service repository from GitHub and navigate into the project directory:
git clone https://github.com/GianlucaBessone/HDB-Service.git
cd HDB-Service
2

Install dependencies

Install all Node.js dependencies using your preferred package manager. The postinstall script automatically runs prisma generate so the Prisma Client is ready immediately after install.
npm install
3

Configure environment variables

Copy the example environment file to create your local configuration:
cp .env.example .env.local
Then open .env.local and fill in the values for your environment. Below is a description of every variable:
​
DATABASE_URL
string
required
PostgreSQL connection string used by Prisma at runtime (via PgBouncer/pooled connection in Supabase). Format: postgresql://user:password@host:5432/hdb_service?sslmode=require
​
NEXTAUTH_URL
string
required
The canonical URL of your application. Set to http://localhost:3000 for local development. In production, use your full domain, e.g. https://hdb.yourdomain.com.
​
NEXTAUTH_SECRET
string
required
A random secret used to sign session tokens. Must be at least 32 characters. Generate one with openssl rand -base64 32.
​
ONESIGNAL_APP_ID
string
Your OneSignal application ID, found in the OneSignal dashboard under Settings → Keys & IDs. Required for push notifications.
​
ONESIGNAL_API_KEY
string
Your OneSignal REST API key. Used server-side to send push notifications to users. Found alongside the App ID in the OneSignal dashboard.
​
APP_URL
string
required
The public base URL of the application. Used to construct absolute links in emails and notifications. Set to http://localhost:3000 locally.
​
DIRECT_URL
string
required
The direct (non-pooled) PostgreSQL connection string, required by Prisma Migrate to run DDL statements that PgBouncer cannot handle. Use the direct connection string from Supabase → Project Settings → Database (port 5432). Format: postgresql://postgres.[ref]:[password]@db.[ref].supabase.co:5432/postgres
​
CRON_SECRET
string
required
A secret token that must be included in requests to /api/cron to prevent unauthorised triggering of scheduled jobs. Generate a strong random string with openssl rand -hex 32.
For local development without push notifications, you can leave ONESIGNAL_APP_ID and ONESIGNAL_API_KEY empty — the platform will function normally, but no push notifications will be delivered.
4

Run Prisma migrations and seed

Generate the Prisma Client and push the schema to your database:
# Generate the typed Prisma Client
npx prisma generate

# Push schema to the database (development only — see deployment guide for production)
npx prisma db push
Then seed the database with a sample client hierarchy, dispenser data, and the material catalog:
# Seed demo data and material catalog
npm run seed
prisma db push is intended for development only. For production deployments, use npx prisma migrate deploy instead. See the Deployment guide for details.
5

Start the development server

Launch the Next.js development server:
npm run dev
Once the server is ready, open your browser and navigate to:
http://localhost:3000
You should see the HDB Service login screen.

​
First login

The seed script (prisma/seed.ts) creates several users automatically, all with the initial password password123. The primary ADMIN account is:
FieldValue
Emailgbessone.hdb@gmail.com
Passwordpassword123
RoleADMIN
Additional seeded users include supervisor@hdb.com (SUPERVISOR) and tech1@hdb.com (TECHNICIAN), all sharing the same initial password. The User model includes a mustChangePassword boolean flag. When this flag is true, users are redirected to a password-change screen after login before they can access any other part of the application. Any user account created by an admin through the UI will have this flag set to true by default, prompting the new user to set their own password on first access.
The seed data includes a fully configured Arcor S.A. client with multiple plants, sectors, locations, dispensers, and SLA configuration — giving you a realistic dataset to explore every feature of the platform immediately after setup.

​
Next steps

Business Hierarchy

Understand how Clients, Plants, Sectors, Locations, and Dispensers are structured and how to navigate between them.

Roles & Permissions

A deep dive into the five user roles and the fine-grained permission matrix that controls what each role can see and do.

SLA Configuration

Learn how per-client SLA configs drive response and resolution deadlines, near-breach alerts, and breach tracking.

Environment Reference

Complete reference for all environment variables, including optional OneSignal and cron settings.

Build docs developers (and LLMs) love

Get started for freeTalk to us