scrum-solitare/README.md

# Scrum Solitare

Enterprise-style Scrum Poker application using Go, Gin, and SSE for real-time room updates.

## Highlights

- Go backend with layered architecture (`handlers`, `state`, `routes`, `config`)
- Memory-first room state with disk synchronization to JSON files
- Real-time updates via Server-Sent Events (SSE)
- Strict state sanitization: unrevealed votes from other users are never broadcast
- Backend authorization for admin-only actions (`reveal`, `reset`)
- Themeable frontend with:
  - CSS architecture split into `main.css`, `layout.css`, and `/themes/*`
  - Theme options: `win98` (default), `modern`, `No Theme`
  - Light/Dark mode independent from active theme
  - Desktop taskbar controls + mobile top controls for theme/mode switching
  - Config page and card deck preview
  - Drag-and-drop card ordering
  - Card add/remove with animation completion handling
  - Room password option
  - Room interface with voting area, participants, and admin controls
- Username persistence through `localStorage`

## Project Layout

- `src/main.go`: app bootstrap
- `src/config/`: environment configuration
- `src/server/`: Gin engine setup
- `src/routes/`: page/api route registration
- `src/handlers/`: HTTP handlers (pages + API + SSE)
- `src/state/`: in-memory room manager, sanitization, persistence
- `src/middleware/`: static cache headers middleware
- `src/models/`: template page data models
- `src/templates/`: HTML templates (`index.html`, `room.html`)
- `static/css/main.css`: shared component primitives
- `static/css/layout.css`: grids/flex/positioning/responsive layout
- `static/css/themes/`: drop-in theme files
- `static/js/ui-controls.js`: global theme + mode engine
- `static/js/`: page logic (`config.js`, `room.js`)

## Environment Variables

- `HOST`: server host/interface to bind (default all interfaces, equivalent to `0.0.0.0`)
- `PORT`: server port (default `8002`)
- `DATA_PATH`: directory for room JSON files (default `./data`)

## Run Locally

```bash
go mod tidy
go run ./src
```

Open `http://localhost:8002`.

To bind explicitly:

```bash
HOST=localhost PORT=8002 go run ./src
HOST=0.0.0.0 PORT=8002 go run ./src
```

## Docker

Build:

```bash
docker build -t scrum-solitare .
```

Run:

```bash
docker run --rm -p 8002:8002 -e DATA_PATH=/app/data scrum-solitare
```

## Real-Time Flow (SSE)

- Client joins room via `POST /api/rooms/:roomID/join`
- Client subscribes to `GET /api/rooms/:roomID/events?participantId=...`
- Server broadcasts sanitized room state updates on critical mutations:
  - room creation
  - join/leave
  - vote cast
  - reveal
  - reset