# 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