batman

docs/architecture.md

@@ -0,0 +1,43 @@
+# KoolTab Architecture
+
+## Overview
+
+KoolTab 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
+- SQLite 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
+- Secure HttpOnly cookie-based auth
+
+### 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