Roadmapster

A visual capacity planning tool for software development teams that relies on available capacity to guide in planning

Overview

Roadmapster provides an intuitive drag-and-drop interface for managing team capacity across multiple quarters. Similar to Jira's sprint planning but focused on quarter-level capacity management, it helps teams visualize workload distribution and prevent overcommitment.

Main planning interface showing backlog and quarterly capacity planning

Features

Core Functionality

• Visual Capacity Planning: Drag and drop epics between backlog and quarters
• Multiple Quarter Management: Plan multiple quarters ahead with collapsible views
• Real-time Capacity Tracking: Visual capacity bars showing utilization per quarter
• T-shirt Size Estimation: XS (5 days) to XL (60+ days) sizing system
• Priority-based Organization: Automatic grouping by priority (P0-P3)
• User Authentication: Secure login with email/password or Google OAuth
• Cloud Persistence: Data stored securely with Supabase backend

Quarter Management

• Collapsible Quarters: Expand/collapse quarters for focused planning
• Quarter Lifecycle: Planning → Active → Completed states
• Capacity Validation: Prevents over-allocation with capacity checks
• Flexible Configuration: Customize working days and team settings per quarter

Team Features

• Team Configuration: Set vacation days, oncall rotation, and buffer percentages
• Team Member Management: Add, edit, and remove team members
• Capacity Calculations: Automatic calculation considering vacations and oncall duties
• Organization Support: Teams organized under user organizations
• Data Persistence: Hybrid storage with Supabase backend and local fallback
• Import/Export: JSON-based data export for sharing and backup

Getting Started

Prerequisites

• Node.js 16+ and npm
• Modern web browser (Chrome, Firefox, Safari, Edge)
• Supabase CLI (for local development with database)

Installation

1. Clone the repository:

git clone https://github.com/yourusername/roadmapster.git
cd roadmapster

2. Install dependencies:

npm install

3. Set up Supabase (for authentication and database):

# Install Supabase CLI if not already installed
npm install -g supabase

# Start Supabase local development
npx supabase start

4. Create .env.local file with your Supabase credentials:

NEXT_PUBLIC_SUPABASE_URL=http://localhost:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-from-supabase-start

5. Start the development server:

npm run dev

6. Open http://localhost:3000 in your browser

Project Structure

roadmapster/
├── README.md                 # This file
├── CLAUDE.md                # AI assistant instructions
├── package.json             # Node.js dependencies
├── next.config.mjs          # Next.js configuration
├── tsconfig.json            # TypeScript configuration
├── .env.local              # Local environment variables (create this)
├── docs/
│   ├── PRD.md              # Product Requirements Document
│   └── GOOGLE_OAUTH_SETUP.md # Google OAuth configuration guide
├── app/                     # Next.js app directory
│   ├── layout.tsx          # Root layout
│   ├── page.tsx            # Main page component
│   ├── login/              # Authentication pages
│   ├── auth/               # Auth callback handler
│   ├── components/         # React components
│   ├── hooks/              # React hooks (useTeams, etc.)
│   ├── services/           # Service layer (Supabase integration)
│   ├── types/              # TypeScript definitions
│   ├── utils/              # Utility functions
│   └── styles/             # CSS styles
├── supabase/               # Supabase configuration
│   ├── config.toml         # Supabase local config
│   └── migrations/         # Database migrations
├── tests/                  # Test files
│   ├── e2e/               # Playwright end-to-end tests
│   ├── fixtures/          # Test fixtures and helpers
│   └── playwright.config.ts # Playwright configuration
└── images/                 # Screenshots and documentation images

Usage

Authentication

1. First-time users need to sign up with email/password or Google OAuth
2. Users are automatically assigned to an organization
3. Teams are created within your organization

Creating Quarters

1. Click "Create Quarter" button at the bottom of the quarters panel
2. Configure quarter name, working days, and status
3. Save to create the new quarter

Planning Epics

1. Click "Add Epic" in the backlog to create new work items
2. Set title, size, priority, and description
3. Drag epics from backlog to quarters to plan work
4. Reorder epics within quarters by dragging

Epic creation and editing interface with all configurable fields

Managing Capacity

• Each quarter shows real-time capacity utilization
• Green bar: Under 75% capacity (healthy)
• Orange bar: 75-90% capacity (approaching limit)
• Red bar: Over 90% capacity (at risk)

Team Settings

1. Click "Team Settings" to configure:
   • Add/remove team members
   • Set individual vacation days
   • Configure oncall rotation schedule
   • Adjust buffer percentage for unknowns
   • Set default working days per quarter

Team configuration interface for managing capacity calculations

Technology Stack

• Framework: Next.js 15.5.0 with React 19.1.1 and TypeScript
• Authentication: Supabase Auth (Email/Password + Google OAuth)
• Database: PostgreSQL via Supabase
• Styling: CSS3 with modern flexbox/grid layouts
• Drag & Drop: @dnd-kit for smooth interactions
• Icons: Lucide React icons
• State Management: React hooks with Supabase persistence
• Testing: Playwright for end-to-end tests
• Build Tool: Next.js with Turbopack

Development

Available Scripts

# Start development server
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run linter
npm run lint

# Run tests
npm run test            # Run all tests
npm run test:e2e        # Run Playwright E2E tests

# Database commands
npx supabase start      # Start local Supabase
npx supabase stop       # Stop local Supabase
npx supabase db reset   # Reset database with migrations

Key Design Decisions

1. Single Page Application: Focused on simplicity and fast interactions
2. Hybrid Storage: Supabase for persistence with localStorage fallback
3. Jira-like UI: Familiar interface for development teams
4. Quarter-based Planning: Aligns with typical business planning cycles
5. Secure Authentication: Email/password and OAuth for flexibility
6. Organization-based Teams: Multi-team support within organizations

Current Implementation Status

✅ Completed Features:

• User authentication (Email/Password + Google OAuth)
• Organization and team management
• Team member CRUD operations
• Drag-and-drop epic management
• Quarter capacity planning
• Real-time capacity calculations
• Data persistence with Supabase
• Playwright E2E testing framework

Future Enhancements

• Real-time collaboration features
• Jira integration for epic synchronization
• Advanced analytics and reporting
• Resource allocation across multiple teams
• Dependency management between epics
• Historical capacity tracking
• Sprint-level planning within quarters
• Notifications and alerts
• Mobile responsive design

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Troubleshooting

Common Issues

1. Authentication errors: Ensure Supabase is running (npx supabase start)
2. Database connection issues: Check .env.local has correct Supabase URLs
3. Team members not persisting: Clear browser cache and restart Supabase
4. Google OAuth not working: Configure OAuth in Supabase dashboard (see docs/GOOGLE_OAUTH_SETUP.md)

Acknowledgments

• Inspired by Jira's sprint planning interface
• Built with Next.js and React
• Uses @dnd-kit for drag and drop functionality
• Authentication and database by Supabase
• Testing with Playwright