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.

Campaign Properties

Timeslot Scheduling

Campaigns can be configured to display only during specific hours and days of the week. Each timeslot rule specifies:

• Days of week — Select specific days (Monday through Sunday)
• Start time / End time — Hour-based display window
• Timezone support — All schedules are timezone-aware

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, updating their last_active timestamp. This allows the platform to track screen online/offline status in real-time and alert publishers to connectivity issues.

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
• Audit trail — Every charge is recorded with rate details for 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

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

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
[email protected]
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

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