PulseStage¶

Employee engagement platform combining Q&A and pulse surveys.

Anonymous question submission, upvoting, team-scoped organization, and weekly sentiment tracking with role-based access control.

Quick Start¶

git clone https://github.com/seanmdalton/pulsestage.git
cd pulsestage
./setup.sh
docker compose up

Visit http://localhost:5173 and log in with demo credentials (admin, alice, bob, or moderator).

See Installation Guide for production deployment.

Core Features¶

Q&A System¶

Anonymous question submission with team assignment
Upvoting to surface priorities
Full-text search (PostgreSQL GIN indexes)
Moderator workflow (answer, tag, pin, freeze)
Bulk operations and moderation queue
Presentation mode for all-hands meetings

Weekly Pulse¶

Anonymous sentiment surveys with cohort rotation
Email invitations via BullMQ queue
One-tap response links (7-day expiration)
Team-scoped analytics with 12-week history
Anonymity enforcement (no userId in responses)

Access Control¶

Five roles with team-scoped permissions: - Viewer - Browse and upvote - Member - Submit questions and upvote - Moderator - Answer, tag, pin, freeze (team-scoped) - Admin - Full access, exports, audit logs (global) - Owner - Complete control (global)

See handbook/SECURITY_MODEL.md for details.

Team Organization¶

Multi-team structure (e.g., Engineering, Product)
Team-scoped questions and pulse data
Org-level rollups for leadership
Primary team assignment for users

Technology¶

Backend: Node.js 24, Express, TypeScript, Prisma
Frontend: React 19, TypeScript, Tailwind CSS, Vite
Database: PostgreSQL 16 with full-text search
Cache: Redis 7 for sessions and rate limiting
Queue: BullMQ for email delivery
Tests: 336 API tests (Vitest) + E2E (Playwright)
Deployment: Docker Compose

Documentation¶

Getting Started¶

Installation - Docker Compose setup
Configuration - Environment variables
Quick Start - 5-minute setup
Troubleshooting - Common issues

User Guides¶

User Guide - Submit questions, upvote, search
Moderator Guide - Answer, moderate, present
Admin Guide - Manage teams, users, settings

Handbook (Architecture & Operations)¶

Product Vision - Features and design philosophy
Data Model - Database schema and invariants
Security Model - RBAC, rate limiting, audit logging
Authentication - Multi-mode auth (Demo, OAuth)
Development - Workflow, testing, versioning
Operations - Deployment, monitoring, runbooks
API Contracts - OpenAPI spec, SSE events
Architecture Decisions - ADRs

Deployment¶

Production Deployment - Self-hosting guide
Environment Variables - Configuration reference
Monitoring - Health checks and observability

Security¶

Multi-tenancy with tenant isolation
Role-based access control (5 roles)
Content moderation (local + OpenAI)
Rate limiting (Redis-based, per-tenant)
Audit logging (append-only)
CSRF protection and security headers
Anonymous pulse responses

See handbook/SECURITY_MODEL.md.

Development¶

Requires: Docker, Node.js 24, PostgreSQL 16, Redis 7

# Start services
make up

# Seed demo data
make db-seed

# Run tests
make test

# Validate before push
make validate-ci

See handbook/DEVELOPMENT.md for complete workflow.

License¶

Apache License 2.0 - See LICENSE

Support¶

Documentation: https://seanmdalton.github.io/pulsestage/
Issues: https://github.com/seanmdalton/pulsestage/issues
Discussions: https://github.com/seanmdalton/pulsestage/discussions
Changelog: CHANGELOG.md