kooltab-backoffice/docs/architecture.md

KoolTap Architecture

Overview

KoolTap is a modular monolith designed for remote tab control in venues.

Components

Backend (NestJS)

• REST API with versioned endpoints (/api/v1)
• JWT authentication for dashboard users
• Bearer token authentication for devices
• PostgreSQL database via Prisma ORM
• Scheduled command expiry job
• In-memory rate limiting

Frontend (Next.js)

• App Router with client-side rendering
• TanStack Query for API data fetching
• shadcn/ui component library
• Tailwind CSS styling
• Tokens kept in cookies (see security.md)
• Socket.IO connection for live updates, polling as fallback

Shared Package

• TypeScript types and constants
• Shared across API and dashboard

Data Flow

1. Device syncs open tabs → Server stores snapshots + ownership
2. Dashboard creates close command → Server resolves device owner
3. Device syncs → Receives pending commands
4. Device processes → Acknowledges command
5. Dashboard polls → Sees updated status

Security Model

• Every user/device scoped to one venue
• Venue isolation enforced at service level
• Device tokens hashed with SHA-256
• Raw token returned only once during registration
• JWT tokens with refresh token rotation
• Rate limiting on sensitive endpoints