⚔️ 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

# In server/
cd server
cp .env.example .env

Ensure your DATABASE_URL is configured in server/.env:

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/retro_kanban?schema=public"

3. Install Dependencies & Generate Prisma Client

# 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):

cd server
npm run dev

Terminal 2 (Frontend Client on http://localhost:5173):

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:

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:

     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:

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.