Overview

This page provides an introduction to the spoker application, describing its purpose as a real-time planning poker tool, its target users, core capabilities, and high-level system architecture. For detailed information about specific subsystems:

• Getting started with development: see Getting Started
• Technology stack details and justification: see Technology Stack
• Complete architecture patterns: see Architecture
• Core features and user workflows: see Core Features

What is Spoker

Spoker is a real-time collaborative planning poker (scrum poker) application that enables distributed agile teams to estimate story points synchronously. The application solves the problem of geographically distributed teams needing a shared space for estimation sessions without requiring external project management tool integrations.

Problem Statement

Distributed agile teams require:

• Real-time voting: Multiple participants voting simultaneously with instant visibility
• Vote hiding: Prevent estimation bias by hiding votes until all participants have submitted
• Task queue management: Organize estimation backlog without external tools
• Role-based permissions: Different capabilities for owners, participants, and observers

Solution Architecture

Spoker implements a client-heavy architecture with Firebase as the data backend:

Sources: package.json1-93 README.md121-143

Target Users

User Roles

Spoker defines three distinct user roles with different capabilities:

Team Context

The application targets:

• Agile teams using scrum or similar methodologies
• Distributed teams requiring real-time remote collaboration
• Teams of 2-15 members (practical size for planning poker sessions)
• Teams without budget for commercial planning poker tools

Sources: README.md250-255 SPEC.md20-29

Core Capabilities

Real-Time Voting

• Participants submit point estimates using predefined scale: ['0', '0.5', '1', '2', '3', '5', '8']
• Votes are hidden until all participants have voted (automatic reveal)
• Vote results display average and individual votes
• Votes can be frozen after reveal to prevent changes

Task Management

Task Lifecycle States:

• Queue: Upcoming tasks waiting for estimation (src/lib/types/raw-db.ts18)
• Current: Active task being estimated (RoomInstance.task)
• Completed: Finished tasks with final estimates

Room Privacy

Vote Hiding

Configurable emoji-based labels hide vote values until reveal:

Each label displays a different emoji instead of the numeric point value.

Sources: README.md17-33 SPEC.md9-31 src/lib/constants/hide-label.ts

High-Level System Architecture

Component Overview

Key Architectural Patterns:

1. Unidirectional Data Flow: User actions → Service calls → Firebase writes → Listeners → Store updates → Component re-renders
2. Service Layer Abstraction: Components never call Firebase SDK directly; all operations go through src/lib/services/firebase/
3. Real-time by Default: onValue() listeners automatically push Firebase changes to Zustand stores
4. Route Protection: RouteWrapper enforces authentication and email verification

Sources: README.md89-119 Diagram 1 and Diagram 3 from high-level system diagrams

Technology Stack

Core Dependencies

Development Infrastructure

External Integrations

Sources: package.json35-61 package.json62-84 README.md135-143

Repository Structure

Directory Organization

spoker/
├── src/
│   ├── lib/                          # Core application logic
│   │   ├── components/               # Reusable UI components
│   │   │   ├── spoker-logo/          # Brand logo component
│   │   │   └── auth/                 # Auth-related components
│   │   ├── constants/                # Application constants
│   │   │   ├── routes/               # Route definitions (public/private/restricted)
│   │   │   ├── hide-label.ts         # Vote hiding emoji options
│   │   │   └── allowed-values.ts     # Validation constants
│   │   ├── hooks/                    # Custom React hooks
│   │   ├── layout/                   # Layout components
│   │   │   └── components/           # Header, Footer, RouteWrapper, Auth
│   │   ├── models/                   # Zod validation schemas
│   │   ├── pages/                    # Page-level components
│   │   │   ├── hall/                 # Room creation/joining interface
│   │   │   ├── room/                 # Main voting interface
│   │   │   │   ├── components/       # Room-specific UI
│   │   │   │   └── hooks/            # Room-specific hooks (listeners)
│   │   │   └── home/                 # Landing page
│   │   ├── services/                 # Firebase service layer
│   │   │   └── firebase/
│   │   │       ├── auth/             # Authentication operations
│   │   │       ├── room/             # Room CRUD operations
│   │   │       └── rules.ts          # Security rules generator
│   │   ├── stores/                   # Zustand state management
│   │   │   ├── auth.ts               # Auth state
│   │   │   └── room.ts               # Room state
│   │   ├── styles/                   # Chakra UI theme configuration
│   │   ├── types/                    # TypeScript definitions
│   │   │   ├── raw-db.ts             # Firebase data structure types
│   │   │   ├── room.ts               # Room-related types
│   │   │   └── user.ts               # User types
│   │   └── utils/                    # Utility functions
│   └── pages/                        # Next.js pages (routing)
│       ├── _app.tsx                  # Global app wrapper
│       ├── _document.tsx             # HTML document customization
│       ├── index.tsx                 # Home page route
│       ├── hall.tsx                  # Hall page route
│       ├── join/[id].tsx             # Join room route
│       └── room/[id].tsx             # Room page route
├── public/                           # Static assets
├── tools/                            # Build scripts
│   └── generate-rules.ts             # Firebase rules generator
└── config files                      # next.config.ts, tsconfig.json, etc.

Key Module Responsibilities

Sources: README.md89-119 AGENTS.md24-85

Data Flow Architecture

Request-Response Flow

Key Data Flow Patterns:

1. Write Path: Component → Service Function → Firebase Write
2. Read Path: Firebase Change → Listener Hook → Store Update → Component Re-render
3. State Source of Truth: Firebase Realtime Database (not Zustand)

Critical Functions:

• updatePoint(): src/lib/services/firebase/room/update/point.ts
• checkAllParticipantVoted(): src/lib/utils/roomUtils.ts
• useRoomListener(): src/lib/pages/room/hooks/use-room-listener.ts

Sources: AGENTS.md14-22 SPEC.md66-68 Diagram 3 from high-level system diagrams

Key System Characteristics

Real-Time Synchronization

The application uses Firebase Realtime Database (not Firestore) with onValue() listeners for automatic updates:

Characteristics:

• Eventually consistent: Updates propagate asynchronously to all clients
• Last write wins: No conflict resolution for concurrent updates
• Automatic cleanup: Listeners unsubscribe in useEffect cleanup functions

Client-Heavy Architecture

Trade-off: Simpler architecture and faster development at the cost of less control over business logic enforcement.

Authentication and Authorization

Authentication Flow:

1. User authenticates via Firebase Auth (email/password or OAuth)
2. RouteWrapper checks authentication state from useAuthStoreState()
3. Private routes require both authentication and email verification
4. Restricted routes (login/register) redirect authenticated users to home

Sources: SPEC.md98-104 src/lib/layout/components/route-wrapper/ Diagram 4 from high-level system diagrams

Firebase Database Schema

Room Data Structure

The core data model is defined in src/lib/types/raw-db.ts:

Database Path: /rooms/$roomId/

Key Paths:

• /rooms/$roomId/users/$uid: Individual user state
• /rooms/$roomId/task: Current task being voted on
• /rooms/$roomId/queue: Array of upcoming tasks
• /rooms/$roomId/completed: Array of finished tasks
• /rooms/$roomId/config: Room configuration

Security: Rules generated from src/lib/services/firebase/rules.ts and deployed via pnpm generate-rules

Sources: src/lib/types/raw-db.ts1-35 SPEC.md253-304 Diagram 7 from high-level system diagrams

Development and Deployment

Build System

Quality Gates

Pre-commit hooks (.husky/pre-commit) enforce:

1. Linting: biome check on staged files
2. Type checking: tsc --noEmit
3. Commit format: Conventional commits via commitlint

Environment Variables

Required for Firebase integration:

Configuration Files:

• next.config.ts: Next.js configuration with Sentry integration
• tsconfig.json: TypeScript compiler options with path aliases (~/lib/*)
• biome.json: Linting and formatting rules

Sources: README.md144-205 package.json13-33 Diagram 6 from high-level system diagrams

Summary

Spoker is a real-time planning poker application built with a client-heavy architecture on Next.js and Firebase. The system prioritizes:

1. Real-time collaboration: Firebase Realtime Database with onValue() listeners
2. Simple architecture: Client-side business logic with Firebase as backend
3. Type safety: TypeScript with Zod validation
4. Developer experience: Conventional commits, automated quality checks, clear separation of concerns

The codebase follows a layered architecture:

• Presentation Layer: React components in src/lib/pages/ and src/lib/components/
• State Layer: Zustand stores in src/lib/stores/
• Service Layer: Firebase operations in src/lib/services/firebase/
• Data Layer: Firebase Realtime Database

For more detailed information about specific subsystems, see the child pages under this section and the Architecture section.

Sources: README.md1-337 AGENTS.md1-450 SPEC.md1-367