# ⚔️ RetroQuest Kanban - Login-Less Real-Time Agile Board

> **A retro 8-bit / pixel-art styled Agile Kanban board with Zero traditional logins (no emails, no passwords). All authorization is cryptographically enforced via URL Fragment hashes.**

---

## 🎮 Features & Highlights

- **Dual-Code URL Fragment Authorization (RBAC)**:
  - **Superadmin Link**: `/b/[board-uuid]#admin=[superadmin_key]` (Full permissions: rename/delete columns, rotate member keys, delete board).
  - **Party Member Link**: `/b/[board-uuid]#member=[member_key]` (Card editing, moving, and task collaboration).
  - **Security Guarantee**: URL fragments (`#...`) are never transmitted in HTTP request lines, preserving secrets from server access logs and HTTP referrers.
- **Anti-Spam & Rate Limiting**:
  - Max 5 board creations per IP per hour (`express-rate-limit`).
  - Creator Success Modal with `navigator.share()` Web Share API for native mobile / WhatsApp sharing.
  - Automatic `localStorage` backup of saved boards.
  - **Key Rotation**: Superadmin can instantly regenerate member invite links, which invalidates old links and disconnects revoked sessions.
  - **TTL 30-Day Auto Cleanup**: Inactive boards older than 30 days are automatically purged via an automated background task.
- **Optimistic Drag-and-Drop (Socket.io + dnd-kit)**:
  - Smooth card movement across columns with immediate optimistic UI updates.
  - Broadcasts movements instantly to all connected teammates in real time.
  - Automatic rollback on persistence failure.
- **500ms Debounced Auto-Save & Field-Level Locking**:
  - Zero "Save" buttons. Edits to ticket titles and descriptions auto-save 500ms after typing stops.
  - While Player A types, that specific field is locked across all other players with an active retro indicator: `[🔒 Player A is writing...]`.
- **Retro / Pixel Aesthetic**:
  - Authentic 8-bit arcade and Minecraft-inspired visual design (`Press Start 2P`, `Silkscreen` fonts, chunky 3D-beveled borders, voxel badge tiers: Wood 🪵, Iron ⚔️, Gold 👑, Netherite 💎).
  - Built-in Web Audio API 8-bit sound synthesizer for clicks, card drops, victory fanfare, and lock warnings (with mute toggle).

---

## 🏗️ Architecture & Tech Stack

- **Backend**: Node.js, Express.js, TypeScript
- **Real-Time**: Socket.io
- **Database & ORM**: PostgreSQL 16 + Prisma ORM (Type-safe schemas, migrations, relations, and cascade deletes)
- **Frontend**: React 18, Vite, TypeScript, Tailwind CSS, `@dnd-kit/core`, `lucide-react`, `canvas-confetti`
- **Deployment**: Multi-stage `Dockerfile` and `docker-compose.yml` ready for **Coolify** / Docker.

---

## 🚀 Quick Start (Local Development)

### 1. Prerequisites
- Node.js 18+ (Tested on Node 20 / 24)
- PostgreSQL running locally or via Docker

### 2. Setup Environment
```bash
# In server/
cd server
cp .env.example .env
```
Ensure your `DATABASE_URL` is configured in `server/.env`:
```env
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/retro_kanban?schema=public"
```

### 3. Install Dependencies & Generate Prisma Client
```bash
# Install Server dependencies
cd server
npm install
npx prisma generate
npx prisma db push

# Install Client dependencies
cd ../client
npm install
```

### 4. Run Development Servers
Open two terminals:

**Terminal 1 (Backend Server on http://localhost:4000):**
```bash
cd server
npm run dev
```

**Terminal 2 (Frontend Client on http://localhost:5173):**
```bash
cd client
npm run dev
```

Visit `http://localhost:5173` to forge your first quest board!

---

## 🐳 Docker & Coolify Deployment

### Option A: Standalone Docker Compose
Run the entire stack (PostgreSQL + App) with a single command:
```bash
docker-compose up -d --build
```
Access the application at `http://localhost:4000`.

### Option B: Coolify Deployment
1. Log into your **Coolify Dashboard**.
2. **Add a PostgreSQL Resource**:
   - Create a new PostgreSQL database service in your Coolify project.
   - Note the Internal Database URL (e.g. `postgresql://postgres:<password>@<db-host>:5432/retro_kanban`).
3. **Deploy the Application**:
   - Add a new **Application** and point it to your Git repository (or Public Git repo).
   - Select **Dockerfile** build pack (the root `Dockerfile` will be automatically detected).
   - In **Environment Variables**, set:
     ```env
     NODE_ENV=production
     PORT=4000
     DATABASE_URL=postgresql://postgres:<password>@<db-host>:5432/retro_kanban
     CLIENT_ORIGIN=*
     RATE_LIMIT_MAX_BOARDS_PER_HOUR=5
     ```
   - In **Port Mapping**, expose port `4000`.
4. Click **Deploy**. Coolify will build the multi-stage image, run `prisma db push` on start, and serve the application with automatic SSL!

---

## 🧪 Testing Backend Logic & Concurrency

Run the automated backend test suite:
```bash
cd server
npx tsx src/test/logic.test.ts
```

This verifies:
- Cryptographic key generation entropy.
- Deterministic SHA-256 key hashing & timing-safe comparison.
- Concurrency conflict resolution & in-memory field locking.
- Socket lock acquisition, refresh, and cleanup on disconnect.