Skip to main content

Developer Setup

This guide helps you set up the development environment for Sessiq.

Prerequisites​

Before starting, ensure you have the following installed:

  • Node.js: Version 20 or higher
  • pnpm: Version 9 or higher (package manager)
  • PostgreSQL: Version 15 or higher (database)
  • Docker: Optional, but recommended for local database setup
  • Git: Version control

Verifying Prerequisites​

# Check Node.js version
node --version  # Should be v20.x or higher

# Check pnpm version
pnpm --version  # Should be 9.x or higher

# Check PostgreSQL (if installed locally)
psql --version  # Should be 15.x or higher

# Check Docker (optional)
docker --version

Tech Stack Versions​

ComponentTechnologyVersion
API FrameworkNestJS (Fastify 5 adapter)11.x
FrontendNext.js (App Router)15.x
UI LibraryReact19.x
DatabasePostgreSQL + Prisma ORM15+ / 5.x
RuntimeNode.js20+
Package Managerpnpm (workspaces)9.x
PaymentsStripe + Paytrail14.x
TestingVitest (unit) + Jest (int/e2e)2.x / 30.x

Repository Setup​

Cloning the Repository​

git clone <repository-url>
cd booking

Installing Dependencies​

# Install all dependencies (uses pnpm workspaces)
pnpm install

This installs dependencies for:

  • All apps (API, Web, Worker, Docs)
  • All packages (DB, Contracts, Scheduling Engine, Observability)

Environment Configuration​

Environment Variables​

Copy the example environment file and configure it:

cp .env.example .env

Edit .env with your local configuration. Key variables:

# Database
DATABASE_URL=postgres://app_user:app_password@localhost:5432/booking
SHADOW_DATABASE_URL=postgres://app_user:app_password@localhost:5432/booking_shadow

# JWT
JWT_SECRET=your-secret-key-here

# API
PORT=3001
NODE_ENV=development

# Web
NEXT_PUBLIC_API_URL=http://localhost:3001
PORT=3000

# Payment Providers (optional for development)
STRIPE_SECRET_KEY=sk_test_...
PAYTRAIL_API_KEY=...
PAYTRAIL_SECRET=...

# Notification Providers (optional for development)
BREVO_API_KEY=...
TWILIO_ACCOUNT_SID=...
TWILIO_AUTH_TOKEN=...

Email Configuration​

For email notifications to work, configure the Brevo (formerly Sendinblue) provider:

# Required for email notifications
BREVO_API_KEY=xkeysib-your-api-key-here

# Optional: Custom sender configuration
BREVO_SENDER_EMAIL=noreply@yourdomain.com
BREVO_SENDER_NAME=Your Business Name

Getting a Brevo API Key:

  1. Sign up at brevo.com
  2. Go to SMTP & API in settings
  3. Create a new API key with transactional email permissions
  4. Add to your .env file

Development Mode:

For local development without email delivery, set:

# Skip actual email sending (logs emails to console instead)
EMAIL_PROVIDER=console

Database Setup with Docker​

The easiest way to set up PostgreSQL is using Docker Compose:

# Start PostgreSQL container
docker compose up -d postgres

# Verify it's running
docker compose ps

The database will be available at:

  • Host: localhost
  • Port: 5432
  • Database: booking
  • User: app_user (created via init scripts)
  • Password: app_password

Database Setup Without Docker​

If you prefer a local PostgreSQL installation:

# Create database
createdb booking

# Create user and set password
psql -d booking -c "CREATE USER app_user WITH PASSWORD 'app_password';"
psql -d booking -c "GRANT ALL PRIVILEGES ON DATABASE booking TO app_user;"

# Run initialization scripts
psql -d booking -f docker/initdb/01-roles.sql
psql -d booking -f docker/initdb/02-extensions.sql
psql -d booking -f docker/initdb/03-app-schema.sql
psql -d booking -f docker/initdb/04-privileges.sql

Database Migrations​

Running Migrations​

After setting up the database, run migrations to create the schema:

# Development mode (creates migration files)
pnpm -w packages/db run migrate:dev

# Or using the workspace script
pnpm run migrate:dev

This command:

  1. Applies all pending migrations
  2. Creates Prisma client
  3. Sets up Row-Level Security (RLS) policies

Verifying Migrations​

# Check migration status
cd packages/db
pnpm prisma migrate status

Creating New Migrations​

When schema changes are needed:

cd packages/db

# Create migration from schema changes
pnpm prisma migrate dev --name your_migration_name

# The migration will be created in packages/db/prisma/migrations/

Generating Prisma Client​

After schema changes, generate the Prisma client:

cd packages/db
pnpm prisma generate

Or use the build script:

pnpm run build:packages

Starting Development Servers​

# Start API, Web, and Worker concurrently
pnpm run dev

This starts:

Option 2: Start Services Individually​

# Start API only
pnpm run dev:api
# or
PORT=3001 pnpm -F api run start:dev

# Start Web only
pnpm run dev:web
# or
PORT=3000 NEXT_PUBLIC_API_URL=http://localhost:3001 pnpm -F web run dev

# Start Worker only
pnpm run dev:worker
# or
pnpm -F worker run start:dev

# Start Docs (Docusaurus)
pnpm run dev:docs
# or
pnpm -F docs run start

Option 3: Docker Compose (Full Stack)​

# Start all services via Docker Compose
docker compose up

# Start specific services
docker compose up postgres api web worker

Project Structure​

Understanding the monorepo structure:

booking/
├── apps/
│   ├── api/              # NestJS API server
│   │   └── src/
│   │       ├── modules/  # Feature modules
│   │       └── main.ts   # Entry point
│   ├── web/              # Next.js web application
│   │   └── app/          # Next.js app directory
│   ├── worker/           # Background worker
│   │   └── src/          # Worker tasks
│   └── docs/             # Docusaurus documentation
│
├── packages/
│   ├── db/               # Prisma schema and migrations
│   │   ├── prisma/
│   │   └── src/          # DAL (Data Access Layer)
│   ├── contracts/        # Shared TypeScript types
│   ├── scheduling-engine/ # Scheduling logic
│   ├── observability/    # Logging and metrics
│   └── adapters/         # External integrations
│
├── docker/               # Docker initialization scripts
├── scripts/               # Utility scripts
└── e2e/                  # End-to-end tests

Key Directories​

API Modules (apps/api/src/modules/):

  • admin/ - Admin panel endpoints
  • auth/ - Authentication
  • availability/ - Availability queries
  • bookings/ - Booking orchestration
  • payments/ - Payment processing
  • pricing/ - Price calculation
  • scheduling/ - Schedule management
  • notifications/ - Email/SMS notifications

Shared Packages (packages/):

  • db/ - Database schema and DAL
  • contracts/ - Shared interfaces
  • scheduling-engine/ - Slot generation logic

Database Seeding​

Seeding Demo Data​

To bring a fresh dev database up to a working state in one command:

pnpm db:dev:bootstrap

This runs three phases against a running docker compose up -d postgres:

  1. Role/extension/schema bootstrap (packages/db/scripts/bootstrap-dev-db.sql, run as the postgres superuser).
  2. prisma db push + custom SQL via pnpm migrate:dev (run as app_owner).
  3. Demo seed via packages/db/seeds/seed_demo.sql (run as app_owner).

It is idempotent — re-running against an existing dev DB is safe.

If you only need to re-seed demo data against an already-bootstrapped DB:

pnpm run seed:demo

This creates:

  • Demo tenant (t_demo)
  • Demo site (s_demo)
  • Demo product (p_demo)
  • One sample slot
  • Demo admin user + OWNER membership

Demo Credentials​

After seeding:

  • Admin Email: admin@demo.com
  • Admin Password: Admin123!
  • Tenant ID: t_demo

Production Seed​

For real tenant data (Active Entertainment):

pnpm -F @booking/db seed:production

This creates all 11 sites, products, addons, schedules, staff users, and cancellation policies.

Notification Templates​

Templates are stored as HTML files and loaded into the database:

pnpm -F @booking/db seed:templates

Directory structure:

packages/db/seeds/templates/
├── _global/fi/       → Platform defaults (tenantId=null)
├── ae/fi/            → Tenant-level (Active Entertainment)
├── laserareena/fi/   → Site-specific (maps to s_laserareena_helsinki)
├── korkee/fi/        → Brand folder (maps to both Korkee sites)
├── hohtogolf/fi/     → Brand folder (maps to Redi + Tullintori)
├── im/fi/            → Brand folder (maps to all 4 IM sites)
└── ...

Each folder contains {templateKey}.html files (e.g., booking_confirmed.html). Optional {templateKey}.subject.txt files override the default subject line. The seed script maps brand folders to site IDs and upserts all templates.

Verification​

Health Checks​

Verify services are running:

# API health check
curl http://localhost:3001/health

# Web health check (if configured)
curl http://localhost:3000

# Database connection
docker compose exec postgres psql -U app_user -d booking -c "SELECT version();"

Test API Endpoint​

# Test availability endpoint
curl "http://localhost:3001/api/v1/availability?product_id=p1&site_id=s1&date_from=2025-08-20&party_size=4"

# Or open in browser
open http://localhost:3000/api/v1/availability?product_id=p1&site_id=s1&date_from=2025-08-20&party_size=4

Development Tools​

Type Checking​

# Check TypeScript types across all apps
pnpm run typecheck

Linting​

# Lint all code
pnpm run lint

# Lint specific workspace
pnpm -F api run lint
pnpm -F web run lint

Formatting​

# Check formatting
pnpm run format:check

# Auto-format (via IDE or manually)

Troubleshooting​

Database Connection Issues​

Problem: Cannot connect to database

Solutions:

# Check PostgreSQL is running
docker compose ps postgres

# Check connection string
echo $DATABASE_URL

# Test connection
psql $DATABASE_URL -c "SELECT 1;"

# Restart PostgreSQL
docker compose restart postgres

Port Already in Use​

Problem: Port 3000 or 3001 already in use

Solutions:

# Find process using port
lsof -i :3001

# Kill process
kill -9 <PID>

# Or use different port
PORT=3002 pnpm run dev:api

Migration Issues​

Problem: Migrations fail

Solutions:

# Check migration status
cd packages/db
pnpm prisma migrate status

# Reset database (WARNING: loses data)
pnpm prisma migrate reset

# Create fresh migration
pnpm prisma migrate dev --name fix_migration

Prisma Client Not Generated​

Problem: TypeScript errors about missing Prisma types

Solutions:

# Regenerate Prisma client
cd packages/db
pnpm prisma generate

# Or rebuild packages
pnpm run build:packages

Module Resolution Issues​

Problem: Cannot find module '@booking/db' or similar

Solutions:

# Reinstall dependencies
pnpm install

# Rebuild packages
pnpm run build:packages

# Clear node_modules (last resort)
rm -rf node_modules packages/*/node_modules apps/*/node_modules
pnpm install

Next Steps​

After setup:

  1. Read Architecture Docs: Understand system design
  2. Review Database Schema: Learn data model
  3. Run Tests: Verify setup with test suite
  4. Explore API: Check available endpoints
  5. Start Coding: Pick a module and start developing

Additional Resources​

  • Architecture Guide: See developer/architecture.md
  • Database Guide: See developer/database.md
  • Testing Guide: See developer/testing.md
  • API Reference: See api/overview.md

IDE Setup​

  • Prisma: Prisma language support
  • ESLint: Linting
  • Prettier: Code formatting
  • TypeScript: Type checking
  • Docker: Docker support

VS Code Settings​

Create .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}