Open source Planning Poker tool natively integrated with Businessmap via REST API v2.
- Facilitator calls Businessmap directly from the browser (API Key in
sessionStorageonly) - Task filtering by board, column, lane, and tags
- Real-time voting sessions (WebSocket)
- Story Points consolidation directly on Businessmap cards
- Self-hosting with a single Go binary + Docker
| Layer | Technology |
|---|---|
| Back-end | Go — planning rooms + WebSocket; no Businessmap proxy |
| Front-end | React 19 · TypeScript · TailwindCSS 4 · Vite (embedded in binary) |
| Real-time | WebSocket (primary) · SSE fallback (planned) |
Screenshots are not bundled in the repo yet. Typical flow:
Landing (/) Setup (/setup) Room (/room/:id)
+----------------+ +----------------------+ +------------------------+
| Create / Join | ->| API key + board query| ->| Waiting · Voting · |
| session | | deck + participants | | Consensus |
+----------------+ +----------------------+ +------------------------+
| Document | Content |
|---|---|
| docs/README.md | Documentation index |
| docs/decisions/ | Development ADRs |
| docs/architecture/ARCHITECTURE.md | Architectural overview |
Detailed spec and backlog live in the private bm-planning-spec repository.
GitHub / Docker Hub copy: .github/REPOSITORY.md — description, topics, Hub short text, categories.
cd web
npm install
npm run devOpen http://localhost:5173.
cd web && npm ci && npm run build
cp -r dist ../server/internal/static/dist # Windows: xcopy /E /I dist ..\server\internal\static\dist
cd ../server
go run ./cmd/serverOpen http://localhost:8080.
Docker Hub (after the first release is published):
docker run -d --name bm-planning -p 8080:8080 samuelfabel/bm-planning:latestOr with Compose (pull, no build):
docker compose -f docker/docker-compose.hub.yml up -dBuild from source:
docker compose -f docker/docker-compose.yml up --buildOr build the image directly:
docker build -f docker/Dockerfile -t bm-planning .
docker run -p 8080:8080 bm-planningRelease process: see docker/RELEASE.md. Hub README: docker/README.md.
The Alpine image ships a single static binary with the React build embedded (see ADR-006).
| Variable | Default | Description |
|---|---|---|
PORT |
8080 |
HTTP listen port |
ALLOWED_ORIGINS |
— | Comma-separated CORS origins (overrides CORS_ORIGINS) |
CORS_ORIGINS |
http://localhost:5173,http://127.0.0.1:5173 |
Comma-separated CORS origins |
ROOM_TTL |
4h |
Inactive room TTL (documented; wired when Redis scaling lands) |
ROOM_GRACE_AFTER_DISCONNECT |
1h |
Grace period before empty rooms are removed |
MAX_PARTICIPANTS |
50 |
Maximum participants per room |
HTTP_RATE_LIMIT_PER_MIN |
60 |
Rate limit for /api/v1/* per client IP |
REDIS_URL |
— | Optional Redis URL for multi-instance deployments (future) |
WebSocket message rate limiting (10 msg/s per client) is planned as a configurable option.
| Endpoint | Purpose |
|---|---|
GET /health |
Liveness |
GET /ready |
Readiness |
GET /metrics |
Prometheus (rooms_active, ws_connections, http_requests_total) |
GET /api/docs |
Swagger UI (OpenAPI 3) |
GET /api/docs/openapi.yaml |
OpenAPI spec |
| Route | Description |
|---|---|
/ |
Landing page |
/setup |
Configuration + task query |
/room/:roomId |
Voting room |
bm-planning/
├── server/ # Go back-end (go.mod here)
│ ├── cmd/server/
│ └── internal/
│ └── static/dist/ # Populated by web build (embedded via go:embed)
├── web/ # React front-end
│ └── src/
├── docker/
│ ├── Dockerfile
│ ├── docker-compose.yml # build from source
│ ├── docker-compose.hub.yml # pull samuelfabel/bm-planning
│ ├── README.md # synced to Docker Hub
│ └── RELEASE.md # maintainer release guide
├── docs/
├── .github/workflows/
└── README.md
Post-MVP plans: docs/roadmap/FUTURE.md. Shipped MVP scope: docs/roadmap/ROADMAP.md.
bm.* palette inspired by Businessmap (Slate/Blue). Configured in web/src/index.css via Tailwind v4 @theme.
MIT