Digital Advertising Platform for Screen Networks

Introduction

AdSpot is a full-stack, multi-tenant digital out-of-home (DOOH) advertising platform. It provides a marketplace where advertisers can create and manage campaigns displayed on digital screens owned by publishers, while admins oversee the entire ecosystem.

Key Highlights

Architecture

AdSpot follows a modular monolith architecture with clear separation between frontend and backend, connected via RESTful APIs and WebSocket channels.

Tech Stack

Features

How It Works

AdSpot operates as a three-sided marketplace connecting advertisers, publishers, and an admin platform.

For Advertisers

For Publishers

Campaign Lifecycle

Use Cases

User Roles & Permissions

Campaign Management

Campaigns are the core of AdSpot. Advertisers create campaigns to display their media content on targeted digital screens. The create and edit flows are full-page Campaign Workspace views that include live Campaign Insights — showing real-time spend, remaining budget, cost per day, and budget usage — rather than simple modals.

Campaign Properties

Ad Scheduling (Time-Slot)

Campaigns can be set to Always On (run at all times when active) or a Custom Schedule where ads only display during specific days and hours. This lets advertisers target peak engagement windows — for example, a breakfast brand running ads Mon–Fri 7am–10am only.

Example schedule payload (Mon–Fri, 9am–5pm Eastern):

{
  "scheduleEnabled": true,
  "scheduleData": {
    "timezone": "America/New_York",
    "rules": [
      { "days": [1, 2, 3, 4, 5], "start": "09:00", "end": "17:00" }
    ]
  }
}

Campaign Lifecycle Automation

Two automated cron jobs manage campaign state without manual intervention:

• Auto-Complete — Runs every minute; marks any ACTIVE campaign whose end_date has passed as COMPLETED.
• Daily Spend Reset — Runs at midnight UTC; resets the daily_spent counter for all campaigns, restoring daily budget headroom.

Screen Management

Screens are digital displays registered by publishers that show advertising campaigns to viewers.

Screen Registration

Publishers register screens using a code-based system:

Screen Properties

Heartbeat System

Active screens send periodic heartbeat signals to the server over the /screens WebSocket namespace, updating their last_active timestamp. This allows the platform to track screen online/offline status in real-time and alert publishers to connectivity issues. Each heartbeat also triggers a charging calculation for active campaigns.

Concurrency Control

Only one WebSocket session is permitted per screen at any time. Duplicate connection attempts are rejected with a screen:already_in_use event. Screens that stop sending heartbeats are automatically disconnected after 90 seconds, freeing the slot for re-authentication. See the Screen Concurrency section for full details.

Availability Schedule

Publishers can define operating hours for each screen — the hours during which the screen accepts and displays ad campaigns. Outside these hours, the screen returns an empty playlist regardless of what campaigns are assigned to it.

The availability schedule follows the same structure as campaign time-slot rules:

Example — a coffee shop screen open every day 8am–10pm IST:

PUT /api/screens/:id/availability
{
  "availabilityEnabled": true,
  "availabilitySchedule": {
    "timezone": "Asia/Kolkata",
    "rules": [
      { "days": [0,1,2,3,4,5,6], "start": "08:00", "end": "22:00" }
    ]
  }
}

Media Library

The media library stores all advertising content (images and videos) uploaded by advertisers.

Approval Workflow

• Supported formats: JPEG, PNG, GIF, MP4, AVI
• Maximum file size: 10MB (configurable)
• Admins can approve or reject media with reasons
• Only approved media can be used in campaigns
• Users can only view and manage their own media

Analytics & Reporting

AdSpot provides comprehensive analytics for all user roles.

Tracked Metrics

Time Periods

Analytics can be filtered by predefined periods (7d, 30d, 90d) or custom date ranges. Each role sees metrics relevant to their perspective:

• Admin: System-wide analytics, total revenue, user growth
• Advertiser: Campaign performance, spend tracking, ROI
• Publisher: Earnings, screen performance, occupancy metrics

Payment System

AdSpot integrates with Stripe, PayPal, and Razorpay for secure payment processing.

Payment Flow

Charging & Rate Management

AdSpot uses a per-view charging model with dynamic rate calculation.

Rate Calculation

Final Rate = Base Rate × Location Multiplier × Time Multiplier

Example:
Base Rate:           $0.05 per view
Location Multiplier: 1.5x  (mall location)
Time Multiplier:     2.0x  (peak hours 9AM-5PM)
────────────────────────────────
Final Rate:          $0.15 per view

Charging Features

• 10-second billing intervals — Charges calculated per view period
• Peak hour pricing — Configurable peak hours (default 9AM-5PM) with time multiplier
• Location-based pricing — Different rates for different venue types
• Budget validation — Prevents charging when daily/total budgets are exhausted
• Platform fee & tax — Automatically deducted per transaction; configurable per-role rates
• Audit trail — Every charge is recorded with rate, fee, and tax details for full transparency

Early Bird Program

A time-limited prelaunch program offering special benefits to early adopters.

Admins can configure the program end date, available slots, pricing, and benefit percentages via the admin dashboard.

Internationalization (i18n)

AdSpot supports multiple languages with full RTL (right-to-left) layout support.

Features

• Database-backed translations — All translations stored in the database, not JSON files
• Namespace organization — Translations grouped by feature area
• Status tracking — Each translation marked as missing, translated, needs_review, or approved
• Bulk operations — Import/export translations, bulk updates
• RTL support — Automatic layout direction switching for Arabic, Hebrew, etc.
• Completion stats — Track translation coverage per language
• Locale file sync — Validate and sync with frontend locale files

Dynamic Branding

AdSpot can be white-labelled entirely from the Admin dashboard. All brand-related settings persist in the database and propagate instantly across every surface — no code changes or redeployment required.

Configurable Brand Elements

Logo Upload

The Admin settings page includes a logo upload control wired to a dedicated endpoint. The uploaded file is stored and served as the platform logo. Changing the logo takes effect immediately for all logged-in users on the next page refresh.

Profile Avatars

All user roles — Admin, Advertiser, and Publisher — can upload a personal profile avatar. The avatar is stored server-side and persists across sessions. It appears in the dashboard navigation bar and profile pages.

Multi-currency Support

The platform operates in a single admin-defined primary currency. All monetary amounts — campaign budgets, charges, earnings, transaction history — display with the correct currency symbol and are converted in real time when the currency changes.

How It Works

• Primary currency is set once by the Admin in System Settings (e.g. USD, EUR, GBP, INR). This acts as the platform base currency.
• Dynamic symbol display — every monetary field across Admin, Advertiser, and Publisher dashboards renders the configured currency symbol automatically.
• Real-time conversion — when the primary currency is changed, all displayed values update immediately without requiring data migration.
• Payment gateways (Stripe, PayPal, Razorpay) are initiated with the configured currency code, ensuring checkout sessions match the platform setting.

Where to Configure

Go to Admin → Settings → Currency to select the platform primary currency from the supported list.

Platform Fees & Tax System

AdSpot applies a transparent, multi-tier fee and tax structure to every charging transaction. Fees are calculated per view and recorded with granular metadata for full auditability.

Fee Calculation

Advertiser pays:     Full charged amount (e.g. $10.00)

Platform Fee:        chargeAmount × platformFeeRate
                     e.g. $10.00 × 15% = $1.50

Publisher Tax:       platformFee × publisherTaxRate
                     e.g. $1.50 × 18% = $0.27

Total Deduction:     platformFee + tax = $1.77

Publisher Earning:   chargeAmount − totalDeduction = $8.23

Fee Rates

Publisher Earnings Breakdown

The Publisher Dashboard displays a complete earnings breakdown for full financial transparency:

• Gross Revenue — Total amount charged to advertisers for views on the screen
• Platform Fee — AdSpot's share deducted from gross revenue
• Tax on Fee — Tax applied to the platform fee portion
• Net Earnings — Amount actually credited to the publisher (Gross − Platform Fee − Tax)

Admin Configuration

All fee rates are configurable from the Admin dashboard under System Settings. Changes apply to future transactions only; existing transaction records retain their original rates.

Offline Ad Support & Sync

Screens continue playing ads even when internet connectivity is disrupted. A Service Worker intercepts media requests and serves cached content as a fallback, then automatically synchronizes when the network is restored.

How It Works

Implementation Details

Screen Concurrency Restriction

To prevent double-billing and unauthorized simultaneous sessions, AdSpot enforces a strict one-active-connection-per-screen rule via the WebSocket gateway.

How It Works

The ScreensGateway maintains an in-memory map of active screen connections. When a screen authenticates over WebSocket:

• The gateway checks if another socket is already registered for the same screen ID.
• If a duplicate is detected, the new connection is rejected immediately with a screen:already_in_use event.
• Only one socket may actively stream heartbeats and trigger billing for any given screen at a time.
• When a screen disconnects, its entry is removed from the map, allowing a new connection to authenticate.

WebSocket Events

Heartbeat Timeout

Each connected screen has a 90-second inactivity timer. A global monitor runs every 30 seconds and disconnects any screen that has not sent a heartbeat within the window. This prevents "zombie" connections that could block legitimate sessions.

WebSocket Gateway Config

Namespace:      /screens
Ping Interval:  25 000 ms   (server → client keep-alive ping)
Ping Timeout:   60 000 ms   (client must respond within 60 s)
HB Timeout:     90 000 ms   (server disconnects if no heartbeat in 90 s)
HB Monitor:     every 30 s  (global check across all connected screens)

Time-Slot Based Ad Scheduling

AdSpot enforces a two-gate intersection model for determining when an ad plays on a screen. Both gates must be open simultaneously for any ad to be displayed.

Worked Example

Suppose Screen 1 is a coffee shop display with operating hours 12pm–1pm every day (lunch rush only). Three campaigns are assigned:

Evaluation Logic

When a screen requests its active playlist (GET /api/campaigns/screen/:id), the backend applies the two gates in order:

Timezone Handling

All schedule rules are evaluated in the timezone stored with the rule, not the server's local time. The backend uses Intl.DateTimeFormat.formatToParts() with the stored IANA timezone to extract the local day-of-week and HH:mm for comparison — no external packages required.

// Pseudocode — same logic for both campaign schedule and screen availability
function isOpen(enabled, schedule, now = new Date()) {
  if (!enabled) return true;                 // no restriction
  const { rules, timezone } = schedule;
  const { dayOfWeek, HH, mm } = extractParts(now, timezone);  // Intl API
  const currentTime = `${HH}:${mm}`;
  return rules.some(r =>
    r.days.includes(dayOfWeek) &&
    currentTime >= r.start &&
    currentTime <= r.end
  );
}

Data Model

Both fields share the same JSON rule shape:

{
  "timezone": "America/Chicago",       // IANA timezone string
  "rules": [
    {
      "days": [1, 2, 3, 4, 5],        // 0=Sun, 1=Mon ... 6=Sat
      "start": "09:00",               // 24-hour HH:mm
      "end": "17:00"
    },
    {
      "days": [6],                    // Saturday only
      "start": "10:00",
      "end": "14:00"
    }
  ]
}

API Reference

Frontend UI — ScheduleBuilder Component

Both the campaign form (Advertiser) and the screen edit form (Publisher) use a shared <ScheduleBuilder> React component. The Admin campaign detail view shows a read-only version of the same component.

• Toggle — "Always On" vs "Custom Schedule" radio selector
• Timezone picker — Searchable dropdown of all IANA timezones via Intl.supportedValuesOf('timeZone')
• Day buttons — M T W T F S S toggles; enable/disable per day
• Time range — Start & end TimePicker (24h format) per rule slot
• Overlap guard — Inline error if two slots on the same day overlap
• Weekly summary — "X active hrs/week" calculated from all enabled rules

Programmatic Buying (SSP/DSP Integration)

AdSpot includes a built-in Supply-Side Platform (SSP) that opens publisher screen inventory to external buyers — ad agencies, trading desks, and demand-side platforms (DSPs) such as Vistar Media, StackAdapt, and The Trade Desk. Buyers submit real-time bids for individual screens via an OpenRTB 2.5-compliant inbound API. On every screen heartbeat, AdSpot's mediation engine selects the highest-value winner between programmatic bids and existing direct campaigns.

Architecture Overview

Two actors and two request flows:

DSP Onboarding Flow

Bid Discovery — POST /api/programmatic/bid

Authenticated via Authorization: Bearer <inbound-api-key> (or x-api-key header). Returns matching screens as an OpenRTB 2.5 BidResponse.

Request

POST /api/programmatic/bid
Authorization: Bearer <inbound-api-key>
Content-Type: application/json

{
  "id": "buyer-auction-id-abc123",      // buyer's own auction ID (UUID)
  "imp": [{
    "id": "imp-1",
    "bidfloor": 2.00,                   // minimum CPM the buyer will pay
    "bidfloorcur": "USD"
  }],
  "dooh": {
    "venuetype": ["transit", "retail"]  // optional: filter by venue
  },
  "site": {
    "geo": {
      "city": "Mumbai",                 // optional: filter by location
      "region": "Maharashtra"
    }
  }
}

Response

{
  "id": "buyer-auction-id-abc123",
  "seatbid": [{
    "bid": [
      {
        "id": "scr-xxxxxxxx",
        "price": 2.50,                  // screen's floor CPM
        "w": 1920, "h": 1080,
        "ext": {
          "screenId": "scr-xxxxxxxx",
          "screenName": "Mall Entrance — Ground Floor",
          "venuetype": "1.2",           // IAB DOOH venue code
          "location": "Mumbai, Maharashtra"
        }
      }
    ]
  }]
}

Bid Submission — POST /api/programmatic/submit

After reviewing the inventory response, the buyer submits a bid for a specific screen:

POST /api/programmatic/submit
Authorization: Bearer <inbound-api-key>

{
  "screenId": "scr-xxxxxxxx",
  "bidPrice": 3.50,                     // CPM in USD — must be ≥ screen's floor
  "adMarkup": "https://cdn.buyer.com/creative.mp4",  // https:// direct URL only
  "winNoticeUrl": "https://buyer.com/win?price=${AUCTION_PRICE}",
  "lossNoticeUrl": "https://buyer.com/loss?reason=${AUCTION_LOSS}",
  "currency": "USD"
}

Mediation Engine

On each screen:heartbeat event (~30 seconds), the engine runs:

Bid Status Lifecycle

Win & Loss Notices

AdSpot fires fire-and-forget HTTP callbacks to the buyer's registered URLs using OpenRTB macro substitution:

• Win notice (nurl) — fired when screen:programmatic_ad_displayed is confirmed. ${AUCTION_PRICE} is replaced with the clearing price.
• Loss notice (lurl) — fired when a bid loses mediation. ${AUCTION_LOSS} is replaced with an IAB loss reason code (e.g. 102 = lost to higher bid).

# Win notice example (called server-side, fire-and-forget)
GET https://buyer.com/win?price=3.50&screen=scr-xxxxxxxx

# Loss notice example
GET https://buyer.com/loss?reason=102&screen=scr-xxxxxxxx

Billing & Fee Split

Billing is triggered only after the screen emits screen:programmatic_ad_displayed. The gross amount is calculated as bidPrice (CPM) / 1000 per impression. The split mirrors the direct campaign model:

All three operations (create ProgrammaticImpression, decrement DspConnection.balance, increment User.balance for publisher) run inside a single Prisma transaction.

Database Models

DspConnection

ProgrammaticBid

ProgrammaticImpression

Screen Extension

Two new fields are added to the Screen model:

Updated via: PATCH /api/screens/:id/programmatic (Publisher role required).

API Endpoints Reference

Admin Endpoints (JWT + ADMIN role)

Buyer Endpoints (x-api-key / Bearer token)

Publisher Endpoints (JWT + PUBLISHER role)

Venue Type → IAB DOOH Code Map

Frontend Surfaces

AI Chat Assistant

AdSpot includes a built-in AI assistant (powered by Claude claude-haiku-4-5) accessible on every authenticated page as a floating chat widget, and on the landing page with predefined quick-start cards.

The AI endpoint (POST /api/ai-chat/message) requires no authentication — making it accessible to unauthenticated landing page visitors. It fetches live data (active screens by venue and city, current DSP bid counts) when the topic is screens or bids, providing contextually accurate answers.

USB Export — Offline Digital Signage

Publishers can export campaign content packages as ZIP files, load them onto USB drives, and play ads on Android TV displays without any internet connection. USB mode is an extension of the existing AdSpot Flutter TV app — no separate player is needed.

How It Works

Two-Stage Billing

USB exports use a two-stage billing model to protect advertisers from paying for content that is never deployed to a screen.

If the publisher does not confirm deployment within the grace period after the export expires, all PENDING delivery transactions are auto-refunded to advertisers by a daily scheduled job.

Cost Calculation

Cost is calculated per campaign, then summed for the export total:

── Per-campaign ──────────────────────────────────────────────────────────────
Base Cost      = usbBaseDailyRate × numberOfDays × locationMultiplier
               × earlyBirdMultiplier  (if advertiser qualifies; otherwise × 1)

Booking Fee    = Base Cost × usbBookingFeePercent / 100     (default: 25%)
Delivery Fee   = Base Cost − Booking Fee                    (default: 75%)

Platform Fee   = Base Cost × platformFeeRate
Tax            = Platform Fee × publisherTaxRate
Publisher Earning = Base Cost − Platform Fee − Tax

── Export totals ─────────────────────────────────────────────────────────────
Total Cost          = Σ Base Cost             (all included campaigns)
Total Booking Fee   = Σ Booking Fee           (all included campaigns)
Total Delivery Fee  = Σ Delivery Fee          (all included campaigns)
Total Publisher Earning = Σ Publisher Earning (all included campaigns)

Cost Parameters

Advertiser Opt-In

Only campaigns with allowUsbExport = true are eligible for USB exports. Advertisers control this toggle per-campaign in their campaign settings. Default is off (safe by default).

• When the toggle is off, the campaign is never included in any USB export regardless of targeting
• When the toggle is on, the advertiser is shown the billing explanation: 25% charged at export time, 75% held until deployment is confirmed
• Budget validation checks the full cost (booking + delivery) before including a campaign — if balance is insufficient, the campaign is excluded and the advertiser is notified

Admin Settings

API Endpoints

Flutter Player App (USB Mode)

USB mode is an extension of the existing AdSpot Flutter TV app — no separate install is required. When a USB drive is inserted, the app detects it, validates the manifest, and switches to offline playback mode automatically.

• Manifest validation — Checks HMAC-SHA256 signature, expiry date, and screen ID match before loading
• Schedule engine — Reuses schedule_utils.dart from the existing app to evaluate campaign schedules against USB manifest data
• Fallback content — If no valid USB content is found, the app falls back to the configured fallback media
• Auto-revert — When the USB is removed, the app returns to online mode and reconnects via WebSocket

Notification System

AdSpot delivers real-time in-app notifications to users via WebSockets (Socket.io) and persists them in the database so nothing is lost if the user is offline.

Architecture

Two NestJS providers collaborate to deliver every notification:

WebSocket Connection

Connect from the frontend using the Socket.io client targeting the /notifications namespace:

import { io } from 'socket.io-client';

const socket = io('/notifications', {
  query: { userId: currentUser.id },   // auto-joins room on connect
});

// Or join manually after connection:
socket.emit('joinNotificationRoom', currentUser.id);

// Listen for incoming notifications:
socket.on('notification', (notification) => {
  // { id, userId, title, message, type, isRead, metadata, created_at }
  dispatch(addNotification(notification));
});

Data Model

REST Endpoints

All endpoints require a valid JWT (Authorization: Bearer <token>). The service scopes queries to the authenticated user's ID automatically.

Testing

AdSpot ships with a comprehensive automated test suite covering both unit and end-to-end scenarios.

Unit Tests

Critical frontend components and API interactions are covered with Jest and React Testing Library. Tests are colocated with their components and focus on rendered output and user interaction behaviour.

E2E Test Suite

The backend E2E suite uses Jest with Supertest (HTTP) and socket.io-client (WebSocket), running against a fully bootstrapped NestJS application with mocked Prisma and email providers.

Test Commands

# Run all E2E tests
npm run test:e2e

# Watch mode (re-run on file change)
npm run test:e2e:watch

# Generate coverage report
npm run test:e2e:coverage

# Generate HTML test report
npm run test:e2e:report
# Output: test/reports/e2e-test-report.html

API Overview

The AdSpot API follows RESTful conventions with a global /api prefix. All responses are wrapped in a standard format:

{
  "success": true,
  "message": "Operation completed successfully",
  "data": { ... }
}

Pagination

List endpoints return paginated results with metadata:

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 20,
    "hasNext": true,
    "hasPrev": false
  }
}

Authentication

The API uses JWT (JSON Web Token) for authentication with access and refresh token support.

Auth Endpoints

API Endpoints

Users

Campaigns

Screens

Media

Analytics

Payments

Publisher

Locations

i18n

Notifications

System

Project Structure

Environment Setup

Create a .env file in the project root with the following variables:

# Database
DATABASE_URL=mysql://username:password@localhost:3306/adspot_db
DATABASE_TYPE=mysql
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USERNAME=your_username
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=adspot_db

# JWT Authentication
JWT_SECRET=your-secret-key
JWT_EXPIRES_IN=7d

# Server
PORT=3001
NODE_ENV=development

# URLs
API_BASE_URL=http://localhost:3001
FRONTEND_URL=http://localhost:5173

# File Upload
UPLOAD_MAX_SIZE=10485760
UPLOAD_ALLOWED_TYPES=image/jpeg,image/png,image/gif,video/mp4,video/avi

# Payment Gateways
STRIPE_SECRET_KEY=sk_test_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx
PAYPAL_CLIENT_ID=xxx
PAYPAL_CLIENT_SECRET=xxx
RAZORPAY_KEY_ID=rzp_test_xxx
RAZORPAY_KEY_SECRET=xxx
RAZORPAY_WEBHOOK_SECRET=xxx

# Email (SMTP)
SMTP_HOST=smtp.example.com
SMTP_USER=your_email@example.com
SMTP_PASS=your_password

# Supabase Storage (optional)
SUPABASE_URL=https://xxx.supabase.co
SUPABASE_ANON_KEY=xxx

# Redis (optional)
REDIS_PASSWORD=redis_password

Installation

Prerequisites

• Node.js 20+
• npm or yarn
• MySQL 8.0 (or Docker)
• Redis (optional, for caching)

Quick Start

# Clone and install
git clone <repository-url>
cd adspot_project
npm install

# Setup database
npm run prisma:generate
npm run prisma:migrate:deploy

# Seed initial data
npm run seed:admin      # Admin user only
npm run seed:all        # All seed data

# Start development
npm run dev

Development

Commands

# Run both frontend and backend
npm run dev

# Run frontend only (Vite)
npm run client:dev

# Run backend only (NestJS)
npm run server:dev

# Open Prisma Studio (database GUI)
npm run prisma:studio

Development URLs

Build

# Production build (frontend + backend)
npm run build:production

# Frontend only
npm run build:frontend

# Backend only
npm run build:backend

# Start production server
npm run start

Deployment

Docker Compose (Recommended)

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

# Rebuild and start
docker-compose up -d --build

Docker Services

Docker Standalone

# Build image
npm run docker:build

# Run container
npm run docker:run

Vercel (Serverless)

The project includes a vercel.json configuration for serverless deployment:

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel

Applying Updates

This section explains how to safely upgrade an existing AdSpot installation to a newer version — whether you are running a local development environment, a self-hosted server, or a Docker-based deployment.

Standard Update (Self-hosted / PM2)

Follow these steps in order. Every step must complete successfully before moving to the next.

git fetch origin main
git reset --hard origin/main

npm ci --production=false

npm run db:generate

npm run db:migrate:deploy

npm run build:production

# If using PM2
pm2 restart adspot --update-env

# If running manually
npm run start

Automated Deploy Script

The project ships with scripts/deploy.sh, which runs all six steps above in sequence. Use it on any server where the repository is checked out at /var/www/adspot and PM2 manages the process.

# Make executable once
chmod +x scripts/deploy.sh

# Run update
npm run deploy
# or directly:
./scripts/deploy.sh

Environment Variable Checklist

Before restarting, compare your .env file against the latest .env.example (or the Environment Setup section). New features often introduce new required variables.

Updating a Docker Deployment

# Pull latest code
git fetch origin main
git reset --hard origin/main

# Rebuild images and restart containers
docker-compose up -d --build

# Migrations run automatically on container start via the entrypoint.
# To run manually inside the container:
docker-compose exec app npm run db:migrate:deploy

Feature-specific Migration Notes

Some releases introduced database schema changes. If you are upgrading from a version before the date shown, pay attention to the notes below.

Rolling Back an Update

If an update causes issues, use the rollback script to revert to a previous commit. Note that database migrations are not automatically reversed — plan accordingly.

# Rollback to the previous commit
npm run rollback
# or directly (optionally pass a specific commit hash):
./scripts/rollback.sh
./scripts/rollback.sh <commit-hash>

Post-update Verification

# Check API health
curl http://localhost:3001/api/health

# Full system health (DB + Redis connectivity)
curl http://localhost:3001/api/health/full

# Check migration status
npm run migrate:status

# Run E2E test suite to confirm nothing broke
npm run test:e2e

Database

Migration Commands

# Create a new migration
npm run prisma:migrate

# Apply migrations to production
npm run prisma:migrate:deploy

# Reset database (deletes all data!)
npm run prisma:migrate:reset

# Custom migration scripts
npm run migrate:run
npm run migrate:status
npm run migrate:rollback
npm run migrate:history

Seeding

# Seed admin user
npm run seed:admin

# Seed all data
npm run seed:all

# Clear all seed data
npm run seed:clear

# Reset and reseed
npm run seed:reset

Key Models

Code Quality

# Run ESLint
npm run lint

# TypeScript type check
npm run check

Frequently Asked Questions