Power BI Dev
134 lines
5.0 KiB
Markdown
134 lines
5.0 KiB
Markdown
# ⚔️ 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.
|