Skip to content

Tony3898/Story-Pointing

BranchesTags

Repository files navigation

Story Pointing Application

A secure, enterprise-grade collaborative story pointing system built with React, TypeScript, and Firebase. Features multi-tenant architecture, Microsoft SSO integration, JWT authentication, role-based permissions, and secure room management for agile teams to estimate effort, complexity, and uncertainty of tickets through anonymous voting.

🚀 Features

🔐 Authentication & Security

  • Multi-Authentication Support: Email/password and Microsoft SSO integration
  • Multi-Tenant Architecture: Complete data isolation between organizations
  • JWT-based Authentication: Secure login with Firebase Authentication
  • Role-based Access Control: Granular permissions system with three user roles
  • Email Domain Restrictions: Configurable per-tenant email domain validation
  • Password Security: bcrypt hashing with configurable password policies
  • Email Verification: Optional email verification for self-registered users
  • Secure Room Access: Users can only join rooms they've been specifically invited to

🏢 Multi-Tenant Features

  • Complete Tenant Isolation: Each organization has isolated data and users
  • Tenant Management: Super Admins can create and manage multiple tenants
  • Domain-based Authentication: Users authenticate based on their email domain
  • Tenant Switching: Super Admins can switch between tenants
  • Configurable Authentication: Each tenant can enable/disable auth methods
  • Custom Branding: Support for tenant-specific logos and colors
  • Resource Limits: Configurable user and room limits per tenant

🔑 Microsoft SSO Integration

  • Azure AD Integration: Seamless Microsoft account authentication
  • Domain-based Routing: Automatic tenant detection from email domain
  • Self-Service Registration: Users can sign up via Microsoft SSO
  • Tenant-Configurable: Each tenant can enable/disable Microsoft auth
  • Secure Token Handling: Firebase manages Microsoft OAuth tokens

👥 User Roles & Permissions

  • Super Admin: Full system access, user management, tenant management, can join any room
  • Room Admin: Create/manage rooms, select participants, configure voting settings
  • Estimator: Participate in assigned rooms, cast votes in story pointing sessions
  • Multiple Roles: Users can have multiple roles with cumulative permissions

🏠 Room Management

  • Invite-only Rooms: Room admins select specific users for each session
  • TTL Room Management: Configurable room expiration (30 minutes to 2 hours)
  • Admin Voting Control: Room admins can choose whether they participate in voting
  • Real-time Synchronization: Live updates across all connected users using Firebase
  • Tenant Isolation: Rooms are isolated per tenant
  • Automatic Cleanup: Expired rooms are automatically deleted

📊 Story Pointing Features

  • Multi-dimensional Voting: Vote on effort, complexity, and uncertainty
  • Anonymous Voting: Individual votes remain private until results are revealed
  • Configurable Point System: Points calculated from predefined voting combinations
  • Session Management: Create multiple tickets per room with complete vote history
  • Real-time Collaboration: See voting progress and member activity live
  • Fibonacci Consensus: Final points calculated using closest Fibonacci number

⏱️ TTL (Time-To-Live) Features

  • Configurable TTL: Choose room duration from 30 minutes to 2 hours (15-minute intervals)
  • Live Countdown: Real-time timer showing remaining time with color coding
  • Automatic Expiration: Rooms are automatically deleted when TTL expires
  • Expiration Warnings: Visual warnings when room is about to expire
  • Multi-user Notifications: All users are notified when room expires

📈 Real-time Features

  • Live Synchronization: Firebase Firestore provides real-time updates
  • Instant Member Updates: See when users join/leave rooms
  • Real-time Voting: Live voting progress across all participants
  • Automatic UI Updates: Interface updates automatically when data changes
  • Connection Status: Firebase connection status indicator

🏗️ Tech Stack

Frontend

  • React 19.1.0: Modern React with latest features
  • TypeScript 5.8.3: Full type safety and developer experience
  • Vite 5.1.0: Fast build tool and development server
  • Tailwind CSS 3.4.17: Utility-first CSS framework
  • React Router 7.6.3: Client-side routing
  • React Hot Toast: Beautiful toast notifications

Backend & Database

  • Firebase 11.9.1: Backend-as-a-Service platform
  • Firebase Firestore: NoSQL real-time database
  • Firebase Authentication: User authentication and management
  • Firebase Security Rules: Database-level security and access control

Authentication & Security

  • Firebase Auth: JWT token management
  • Microsoft OAuth: Azure AD integration via Firebase
  • bcryptjs 3.0.2: Password hashing
  • Role-based Permissions: Custom permission system

Development & Testing

  • Vitest: Unit testing framework
  • TypeScript: Static type checking
  • ESLint: Code linting
  • Autoprefixer: CSS vendor prefixing
  • PostCSS: CSS processing

Deployment & Build

  • Vite Build: Optimized production builds
  • Firebase Hosting: (Optional) Serverless hosting
  • Environment Variables: Configuration management

🎯 How It Works

Multi-Tenant Authentication Flow

  1. Email Entry: User enters email address
  2. Tenant Detection: System identifies tenant by email domain
  3. Auth Method Selection: Available auth methods shown based on tenant config
  4. Authentication: User signs in via email/password or Microsoft SSO
  5. Role Assignment: User gets appropriate roles within their tenant
  6. Dashboard Access: Role-based dashboard shows tenant-specific data

Microsoft SSO Flow

  1. Domain Detection: User email domain mapped to tenant
  2. Microsoft Popup: Azure AD authentication popup
  3. Token Exchange: Microsoft token exchanged for Firebase token
  4. User Creation: New users automatically created with Estimator role
  5. Tenant Assignment: User assigned to tenant based on email domain

Room Management Flow

  1. Room Creation: Room Admins create rooms within their tenant
  2. User Invitation: Only tenant users can be invited to rooms
  3. TTL Configuration: Room expiration time set during creation
  4. Real-time Access: Invited users see room in their dashboard
  5. Automatic Cleanup: Expired rooms automatically deleted

Story Pointing Process

  1. Join Room: Invited users join from their personalized dashboard
  2. Create Tickets: Room Admin creates tickets for estimation
  3. Multi-dimensional Voting: Team members vote on three dimensions:
    • Effort: How much work is required (Small, Medium, Large)
    • Complexity: How complex the solution is (Small, Medium, Large)
    • Uncertainty: How uncertain the requirements are (Small, Medium, Large)
  4. Real-time Updates: All participants see live voting progress
  5. Point Calculation: System calculates points using predefined combination matrix
  6. Results Reveal: Admin closes voting to show anonymized results and final points
  7. Automatic Cleanup: Rooms expire based on configured TTL and are automatically cleaned up

🧮 Point Calculation System

The application uses a sophisticated two-stage point calculation system:

Stage 1: Individual Vote Points

Different combinations of effort, complexity, and uncertainty result in different story points for each vote:

  • Small + Small + Small = 1 point
  • Small + Large + Medium = 5 points
  • Large + Large + Large = 21 points
  • And many more combinations...

Stage 2: Fibonacci Consensus

The final story points for a ticket are determined using Fibonacci Consensus:

  1. Calculate Average: All individual vote points are averaged
  2. Find Closest Fibonacci: The system finds the closest Fibonacci number to the average
  3. Set Final Points: This Fibonacci number becomes the final story points

Example: If three team members vote 1, 8, and 13 points:

  • Average: (1 + 8 + 13) ÷ 3 = 7.33
  • Closest Fibonacci: 8
  • Final Story Points: 8

Fibonacci Sequence Used: [0, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]

This approach ensures final estimates align with common story pointing practices while providing a mathematically sound consensus method that reduces the impact of outlier votes.

🚀 Getting Started

Prerequisites

  • Node.js (version 18 or higher)
  • npm or yarn
  • Firebase Project (for authentication and database)
  • Microsoft Azure AD (optional, for SSO)

Firebase Setup

  1. Create Firebase Project:

    • Go to Firebase Console
    • Create a new project
    • Enable Firestore Database
    • Enable Authentication

  2. Configure Authentication:

    • Go to Authentication > Sign-in method
    • Enable Email/Password provider
    • (Optional) Enable Microsoft provider for SSO

  3. Get Firebase Configuration:

    • Go to Project Settings > General > Your apps
    • Add a web app
    • Copy the Firebase config object

  4. Environment Configuration: Create a .env file in your project root:

    # Firebase Configuration
VITE_APP_FIREBASE_API_KEY=your_api_key_here
VITE_APP_FIREBASE_AUTH_DOMAIN=your_project_id.firebaseapp.com
VITE_APP_FIREBASE_PROJECT_ID=your_project_id
VITE_APP_FIREBASE_STORAGE_BUCKET=your_project_id.appspot.com
VITE_APP_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
VITE_APP_FIREBASE_APP_ID=your_app_id

# Optional: Default tenant limits
VITE_DEFAULT_MAX_USERS=5
VITE_DEFAULT_MAX_ROOMS=2

  5. Firestore Security Rules: The application includes comprehensive security rules in firestore.rules. Deploy them:

    firebase deploy --only firestore:rules

Microsoft SSO Setup (Optional)

  1. Azure AD App Registration:

    • Go to Azure Portal
    • Register a new application
    • Configure redirect URIs for Firebase

  2. Firebase Microsoft Provider:

    • In Firebase Console > Authentication > Sign-in method
    • Enable Microsoft provider
    • Add your Azure AD client ID and secret

Installation

  1. Clone the repository:

    git clone <repository-url>
cd story-pointing

  2. Install dependencies:

    npm install

  3. Set up Firebase configuration (see Firebase Setup above)

  4. Initialize the application:

    # Create Super Admin and Master Tenant
cd scripts
npm install
node createSuperAdmin.js
cd ..

  5. Start the development server:

    npm run dev

  6. Open your browser:

📖 Usage

Initial Setup

  1. Super Admin Login: Use credentials from createSuperAdmin.js script
  2. Create Tenants: Go to Tenant Management to create organizations
  3. Configure Auth Methods: Enable email/password and/or Microsoft SSO per tenant
  4. Create Users: Use User Management or let users self-register

Tenant Management (Super Admin Only)

  1. Create Tenant:

    • Go to Tenant Management
    • Click "Create Tenant"
    • Configure name, domains, and authentication methods
    • Set user and room limits

  2. Manage Authentication:

    • Enable/disable email/password authentication
    • Enable/disable Microsoft SSO
    • Configure password policies
    • Set email verification requirements

  3. Switch Tenants:

    • Use tenant switcher in header
    • View and manage different organizations
    • Access tenant-specific data

User Management

  1. Create Users (Admin):

    • Go to User Management
    • Click "Create User"
    • Assign roles and tenant
    • User receives invitation to set password

  2. Self-Registration:

    • Users visit signup page
    • Enter email (domain determines tenant)
    • Choose authentication method
    • Complete registration process

Room Operations

  1. Create Room:

    • Click "Create Room" on dashboard
    • Set room name and TTL duration
    • Select participants from tenant users
    • Configure admin voting participation

  2. Join Room:

    • Invited users see room on dashboard
    • Click to join active rooms
    • Real-time updates show other participants

  3. Story Pointing:

    • Create tickets for estimation
    • Vote on effort, complexity, uncertainty
    • View real-time voting progress
    • Reveal results and final points

Real-time Features

  • Live Updates: All changes sync instantly across users
  • Member Activity: See when users join/leave
  • Voting Progress: Real-time voting status
  • Room Expiration: Live countdown timers
  • Connection Status: Firebase connection indicator

⚙️ Configuration

Voting Configuration

Point calculation system is configurable in src/config/votingConfig.ts:

export const VOTING_COMBINATIONS = [
  { effort: 'small', complexity: 'small', uncertainty: 'small', points: 1 },
  { effort: 'small', complexity: 'large', uncertainty: 'medium', points: 5 },
  // ... more combinations
];

Role Permissions

Role-based permissions are defined in src/config/rolePermissions.ts:

export const ROLE_PERMISSIONS = {
  'Super Admin': ['*'], // All permissions
  'Room Admin': ['Room.Create', 'Room.Update', 'Room.Delete'],
  'Estimator': ['Vote.Create', 'Vote.Update']
};

Tenant Settings

Each tenant can configure:

  • Authentication methods (email/password, Microsoft SSO)
  • Password policies
  • Email verification requirements
  • User and room limits
  • Custom branding

🏗️ Architecture

Multi-Tenant Data Structure

Firebase Firestore:
├── tenants/
│   ├── {tenantId}/
│   │   ├── name: string
│   │   ├── domains: string[]
│   │   ├── superTenant: boolean
│   │   ├── settings: TenantSettings
│   │   └── isActive: boolean
├── users/
│   ├── {userId}/
│   │   ├── tenantId: string
│   │   ├── roles: string[]
│   │   ├── status: 'ACTIVE' | 'INVITED' | 'INACTIVE'
│   │   └── ...userdata
├── rooms/
│   ├── {roomId}/
│   │   ├── tenantId: string
│   │   ├── allowedUserIds: string[]
│   │   ├── expiresAt: timestamp
│   │   └── ...roomdata

Security Model

  • Firestore Rules: Database-level security with tenant isolation
  • JWT Tokens: Firebase manages authentication tokens
  • Role Validation: Frontend and backend permission checks
  • Domain Validation: Email domain restrictions per tenant

🧪 Testing

Run the test suite:

npm test

Run tests in watch mode:

npm run test:watch

🚀 Deployment

Build for Production

npm run build

Deploy to Firebase Hosting

# Install Firebase CLI
npm install -g firebase-tools

# Login and deploy
firebase login
firebase deploy

Environment Variables

Ensure all environment variables are set in your deployment environment:

  • Firebase configuration
  • Default tenant limits
  • Any custom feature flags

📚 Documentation

For detailed technical documentation, see:

API Documentation

The application uses Firebase SDK for all backend operations:

  • Authentication: Firebase Auth
  • Database: Firestore
  • Real-time updates: Firestore listeners
  • Security: Firestore security rules

🔧 Development

Project Structure

src/
├── components/          # React components
│   ├── common/         # Reusable components
│   ├── forms/          # Form components
│   ├── layout/         # Layout components
│   ├── modals/         # Modal dialogs
│   └── pages/          # Page components
├── config/             # Configuration files
├── context/            # React context providers
├── services/           # Business logic and API calls
├── types/              # TypeScript type definitions
└── utils/              # Utility functions

Available Scripts

  • npm run dev: Start development server
  • npm run build: Build for production
  • npm run preview: Preview production build
  • npm test: Run tests

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

🔒 Security Features

  • Multi-tenant Isolation: Complete data separation between organizations
  • Firebase Security Rules: Database-level access control
  • JWT Authentication: Secure token-based authentication
  • Password Hashing: bcrypt with configurable policies
  • Email Domain Validation: Prevent unauthorized access
  • Role-based Permissions: Granular access control
  • Session Management: Automatic token refresh and expiration

🌟 Key Benefits

For Organizations

  • Enterprise-Ready: Multi-tenant architecture with complete data isolation
  • Flexible Authentication: Support for email/password and Microsoft SSO
  • Scalable: Firebase backend scales automatically
  • Secure: Comprehensive security model with role-based access

For Teams

  • Real-time Collaboration: Live updates and synchronization
  • Anonymous Voting: Honest estimation without bias
  • Configurable Estimation: Flexible point calculation system
  • Time Management: TTL-based room expiration

For Developers

  • Modern Tech Stack: React, TypeScript, Firebase
  • Type Safety: Full TypeScript coverage
  • Real-time Updates: Firebase Firestore listeners
  • Comprehensive Testing: Unit tests with Vitest

📄 License

This project is open source and available under the MIT License.

🤝 Support

For support and questions:

  • Create an issue in the repository
  • Contact: contact@tejasrana.in
  • Documentation: See linked documentation files

Story Pointing - Collaborate, estimate, and deliver with precision - your agile story pointing companion for sprint planning and team estimation.

About

Story Pointing

sp.tejasrana.in

Topics

firebase reactjs storypoint

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Languages