44 lines
1.2 KiB
Markdown
44 lines
1.2 KiB
Markdown
# 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 |