santhoshj/headroom
1
0
Fork 0
Code Issues 18 Pull Requests Actions Packages Projects Releases Wiki Activity

Headroom - Foundation

Browse Source
This commit is contained in:
Santhosh Janardhanan
2026-02-17 02:10:23 -05:00
commit 04022b7e0b
46 changed files with 10488 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

188
docs/README.md Normal file
View File

@@ -0,0 +1,188 @@
# Headroom Documentation
This directory contains comprehensive documentation for the Headroom project.
## Documents
### Core Documentation
1. **headroom-project-charter.md**
- Complete project charter and specifications
- Problem statement, solution overview, requirements
- Data validation rules, RBAC matrix
- Deferred features and out-of-scope items
- Success criteria
2. **headroom-architecture.md**
- Technical architecture with Mermaid diagrams
- System component diagram
- Data model (ER diagram)
- API architecture
- Authentication flow
- Deployment architecture
- Testing strategy
3. **headroom-decision-log.md**
- Complete conversation archive
- All decisions made and rationale
- Considerations and trade-offs
- Deferred features with reasoning
- Rejected options
- Timeline of discussions
4. **headroom-executive-summary.md**
- Condensed overview suitable for printing
- Executive summary
- Core features
- Quality standards
- Timeline and phases
- Success metrics
## Converting to Word Format
### Option 1: Using Pandoc (Recommended)
If you have Pandoc installed:
```bash
# Install Pandoc (if not already installed)
# macOS: brew install pandoc
# Windows: choco install pandoc
# Linux: sudo apt-get install pandoc
# Convert individual files
pandoc headroom-project-charter.md -o headroom-project-charter.docx
pandoc headroom-architecture.md -o headroom-architecture.docx
pandoc headroom-decision-log.md -o headroom-decision-log.docx
pandoc headroom-executive-summary.md -o headroom-executive-summary.docx
# Or convert all at once
for file in headroom-*.md; do
pandoc "$file" -o "${file%.md}.docx"
done
```
### Option 2: Using Online Converters
If Pandoc is not available:
1. Visit https://cloudconvert.com/md-to-docx
2. Upload the .md file
3. Download the .docx file
Alternatively:
- https://www.markdowntopdf.com/ (converts to PDF)
- https://dillinger.io/ (online Markdown editor with export)
### Option 3: Copy-Paste Method
1. Open the .md file in any Markdown viewer (VSCode, Typora, MacDown)
2. Copy the rendered content
3. Paste into Microsoft Word
4. Format as needed
## Mermaid Diagrams
The architecture document contains Mermaid diagrams. To render them:
### In Markdown Viewers
- **VSCode**: Install "Markdown Preview Mermaid Support" extension
- **Typora**: Built-in Mermaid support
- **MacDown**: May require plugin
### For Word Conversion
Mermaid diagrams don't convert directly to Word. Options:
1. **Render to images first:**
```bash
# Using mermaid-cli
npm install -g @mermaid-js/mermaid-cli
mmdc -i architecture.md -o architecture.docx
```
2. **Use online renderer:**
- Visit https://mermaid.live/
- Paste Mermaid code
- Export as PNG/SVG
- Insert into Word document
3. **Keep as code blocks:**
- Diagrams will appear as text in Word
- Acceptable for technical documentation
## Recommended Reading Order
### For Project Owner (You)
1. Start with **headroom-executive-summary.md** (overview)
2. Read **headroom-decision-log.md** (verify all decisions captured)
3. Review **headroom-project-charter.md** (detailed requirements)
4. Study **headroom-architecture.md** (technical deep-dive)
### For Associate
1. **headroom-executive-summary.md** (context)
2. **headroom-architecture.md** (technical implementation)
3. **headroom-project-charter.md** (detailed requirements as needed)
### For Hardcopy/Reference
- **headroom-executive-summary.md** → Print for quick reference
- **headroom-architecture.md** → Print for technical diagrams
## Document Maintenance
### When to Update
**Project Charter:**
- When requirements change
- When new features are added to scope
- When success metrics are revised
**Architecture:**
- When tech stack changes
- When new integrations are added
- When deployment approach changes
**Decision Log:**
- Add entries for major decisions
- Update when deferrals are implemented
- Record new trade-offs
**Executive Summary:**
- Update timeline when phases shift
- Revise success metrics based on learnings
- Update when project scope changes significantly
### Version Control
All documents are in git. To track changes:
```bash
# View history of a document
git log -p docs/headroom-project-charter.md
# Compare versions
git diff HEAD~1 docs/headroom-architecture.md
# Tag major versions
git tag -a v1.0-docs -m "Initial documentation complete"
```
## Quick Reference: Key Decisions
| Decision | Document | Section |
|----------|----------|---------|
| Why SvelteKit? | Decision Log | Technical Stack Decisions → Frontend |
| Why Redis from day 1? | Decision Log | Architecture Decisions → Caching |
| What's deferred to Phase 2? | Project Charter | Deferred Features |
| What's the data model? | Architecture | Data Model |
| What are the success metrics? | Executive Summary | Success Metrics |
| What's the testing strategy? | Architecture | Quality Standards |
## Questions or Updates?
Contact: Santhosh J (Project Owner)
---
**Last Updated:** February 17, 2026
**Documentation Version:** 1.0

1161
docs/headroom-architecture.md Normal file
View File

File diff suppressed because it is too large Load Diff

840
docs/headroom-decision-log.md Normal file
View File

@@ -0,0 +1,840 @@
# Headroom - Complete Decision Log & Conversation Archive
**Version:** 1.0
**Date:** February 17, 2026
**Participants:** Santhosh J (Project Owner), AI Assistant (Design Partner)
**Purpose:** Comprehensive record of all discussions, decisions, considerations, and deferrals
---
## Table of Contents
1. [Project Genesis](#project-genesis)
2. [Requirements Discovery](#requirements-discovery)
3. [Technical Stack Decisions](#technical-stack-decisions)
4. [Architecture Decisions](#architecture-decisions)
5. [Quality & Testing Decisions](#quality--testing-decisions)
6. [Deferred Features](#deferred-features)
7. [Rejected Options](#rejected-options)
8. [Open Questions](#open-questions)
9. [Timeline](#timeline)
---
## Project Genesis
### The Problem
**Context:**
- Managing team of 10-15 developers
- Handling 10-12 concurrent projects in various phases
- Currently using spreadsheets → "a nightmare"
**Pain Points Identified:**
1. **Capacity calculation chaos**: Manual calculations across holidays, PTO, weekends
2. **No validation**: Easy to over-allocate people or projects
3. **Visibility gap**: Hard to answer "Who has headroom for new work?"
4. **Billing errors**:
- Over-allocation → Overcharge clients → Escalations
- Under-allocation → Undercharge → Revenue loss
5. **No audit trail**: Changes are invisible
6. **Actual vs Planned tracking**: Difficult to compare what was planned vs what actually happened
### The Vision
**Product Name:** Headroom
- **Why this name?** It's the word managers actually say ("do we have headroom for this?"), immediately signals capacity planning, and captures the over/under allocation anxiety central to the tool.
- **Close runner-up:** Margin (protecting margin through accurate forecasting)
**Core Value:**
> Know exactly who has headroom for new work, prevent billing errors, forecast revenue, track planned vs actual hours.
### Personas
Four distinct user types identified:
| Persona | Primary Need |
|---------|--------------|
| **Superuser** | System setup, configuration, admin controls |
| **Managers** | Resource planning, allocation, team oversight |
| **Developers** | View allocations, log hours, understand workload |
| **Top Brass** | Executive reports, forecasts, budget visibility |
---
## Requirements Discovery
### The Monthly Cycle
**Key Insight:** The workflow is organized around monthly capacity planning cycles, not continuous allocation.
```
Monthly Cycle:
1. Capacity Planning → Who's available, how much?
2. Project Setup → What work needs to be done?
3. Resource Allocation → Who does what?
4. Actuals Tracking → What actually happened?
```
### Capacity Planning Requirements
**Inputs:**
- Team member list (name, role, hourly rate)
- Calendar data (holidays, weekends)
- Individual PTO requests
- Daily availability: **0** (unavailable), **0.5** (half day), **1.0** (full day)
**Critical Clarification:**
- Initial assumption: "10 hrs for Dev" meant role-based allocation
- **Actual requirement:** Person-specific allocation ("10 hrs for Santhosh")
- Availability is per-person, per-day, not role-based
**Outputs Needed:**
1. Individual capacity (person-days per month)
2. Team capacity summary (total available person-days)
3. Possible revenue (if fully utilized)
### Project Management Requirements
**Project Lifecycle:**
```
NA/Support → Initial → Gathering Estimates → Estimate Pending Approval
↓
Estimate Rework ←───────┘
↓
Estimate Approved → Funded → Scheduled → In-Progress
↓
Ready for Prod → Done
↓
[Optional: On-Hold, Cancelled]
```
**Key Attributes:**
- **Approved Estimate**: Total billable hours approved by client
- **Forecasted Effort**: How those hours split across months
- **Project Type**: Project (billable) vs Support (ongoing ops)
**Validation Requirement:**
- **Over-forecast**: Allocated hours > Approved estimate → RED FLAG (will overcharge)
- **Under-forecast**: Allocated hours < Approved estimate → YELLOW FLAG (will undercharge)
- **Clarification:** "Under-forecast is NOT OK. This money is my salary! Always try to be 100%."
### Resource Allocation Requirements
**The "Matrix" Concept:**
```
For month M:
┌────────────────────────────────────────┐
│ Project │ Dev A │ Dev B │ Dev C │ Ext │
├──────────┼───────┼───────┼───────┼─────┤
│ Proj X │ 40h │ 20h │ 0 │ 10h │
│ Proj Y │ 20h │ 40h │ 30h │ 0 │
└────────────────────────────────────────┘
```
**"Untracked Resource" Requirement:**
- Purpose: Accommodate hours for external team members (e.g., DevOps from another team)
- Billing: NOT tracked for revenue (like a joker in a deck of cards)
- Use case: "We might bill another team, but not track their specific person"
**Validation Rules:**
- Sum of project allocations should equal approved estimate (tolerance: ±5%)
- Cannot allocate more than person's monthly capacity (warning, not hard block)
- Visual indicators: GREEN (100%), YELLOW (<100%), RED (>100%)
### Actuals Tracking Requirements
**Data Entry:**
- **Frequency**: Monthly aggregate, but can be updated incrementally (weekly)
- **Method**: Manual entry (no time-tracking tool integration for MVP)
**Calculations:**
- **Running utilization**: (Allocated hours YTD) / (Capacity YTD) × 100%
- **Overall utilization**: (Allocated hours this month) / (Capacity this month) × 100%
**Display Requirement:**
- Show utilization % alongside capacity view
### Reporting Requirements
**Core Reports:**
1. **Forecast Summary** (multi-period)
2. **Utilization Summary**
3. **Cost Summary**
**Critical Requirement:**
> All reports must be highly customizable with filters (team, person, project, status, date range, type)
**Additional Requirements:**
- Master data / taxonomy for configurable items (roles, statuses, types)
- Support for multi-tenancy (deferred to post-MVP)
---
## Technical Stack Decisions
### Backend: Why Laravel?
**Question Raised:** "I chose Laravel because of my PHP background. Debate me if that is not a good choice."
**Consideration:**
- Alternative: SvelteKit full-stack (single framework)
- Alternative: Next.js + Node.js
**Decision:** Laravel
- **Rationale**:
- You have PHP background (lower learning curve)
- Laravel is mature, robust for API development
- Rich ecosystem (Scribe for API docs, Pest for testing, Pint for linting)
- PostgreSQL support is excellent
- Redis integration is first-class
**No pushback from AI:** Laravel is a solid choice for this use case.
### Frontend: The Great Debate
**Initial Question:** "May be Laravel + Svelte? Or Sveltekit itself?"
**Options Presented:**
1. Laravel + Blade Templates (rejected: less interactive)
2. Laravel + Vue.js (recommended by AI: stay in Laravel ecosystem)
3. **Laravel API + SvelteKit (separate)** ← CHOSEN
4. Laravel API + React (rejected: more learning curve)
**Decision:** Laravel API + SvelteKit (separate projects)
- **Your choice:** "Sveltekit it is!"
- **AI concern:** "Adds deployment complexity for MVP"
- **Your response:** "I will choose this."
- **Outcome:** Two separate containers, clean separation
**Why SvelteKit?**
- Modern, reactive
- Great for data-heavy dashboards
- Smaller bundle sizes than React/Vue
- You're willing to learn it
### Database: PostgreSQL from Day 1
**Question:** "SQLite for local, PostgreSQL for production?"
**Decision:** PostgreSQL from the start
- **Rationale**:
- Avoid migration pain later
- Production-grade features (JSON operators, full-text search)
- Better for reporting queries
- Volume-mounted in Docker (portability maintained)
### Caching: Redis from Day 1
**Initial Recommendation:** "Start without caching, add in Phase 2 if slow"
**Your Response:** "Query caching and Response caching on Redis from Day 1. No need to sweat on refactoring it everywhere."
**Decision:** Redis caching from day 1
- **Rationale**: Prevents technical debt
- **Scope**: Query caching + Response caching
- **Implementation**: Laravel cache facade, automatic invalidation
### Authentication: JWT
**Question:** "Session-based or Token-based (JWT)?"
**AI Recommendation:** "Session-based is easier for same-origin setup"
**Your Choice:** "I will go with JWT."
**Rationale:**
- Token-based authentication
- Suitable for SPA frontend
- Easier to add mobile app later (if needed)
### UI Component Library
**Options Presented:**
- Shadcn/ui (headless, customizable)
- **DaisyUI** (Tailwind-based, fast) ← CHOSEN
- Svelte Material UI (full-featured)
- Build custom with Tailwind
**Decision:** DaisyUI
- **Rationale**: Faster to build dashboards, opinionated but fast
- **Your response:** "Daisy it is."
### Charts & Visualization
**Options Presented:**
- **Recharts** ← CHOSEN (AI recommendation)
- Chart.js
- Plotly
- Apache ECharts
**Decision:** Recharts
- **Rationale**: Good balance of power and simplicity
- **Your response:** "Agreed"
### Tables & Data Grid
**Options Presented:**
- **TanStack Table (React Table)** ← CHOSEN
- Svelte DataTable
- Build custom
**Decision:** TanStack Table
- **AI note:** "I am not familiar with this, but I will go with your recommendation."
- **Rationale**: Industry standard, powerful filtering/sorting, works with Svelte
### Forms & Validation
**Options Presented:**
- SvelteKit Form Actions + Superforms
- Direct API calls
**Additional Question:** "How about something like Superform or Zod?"
**Decision:** Superforms + Zod + SvelteKit Form Actions
- **Rationale**:
- Type-safe validation (Zod)
- Form state management (Superforms)
- Server-side handling (SvelteKit native)
- Single source of truth for validation
### API Documentation
**Question Raised:** "How about SwaggerUI documentation for APIs?"
**Decision:** Laravel Scribe (auto-generates SwaggerUI)
- **Implementation**: `composer require knuckleswtf/scribe`
- **Output**: `/api/documentation` endpoint with OpenAPI spec
- **Lift**: ~1 hour setup
- **Inclusion**: From day 1
### Testing Stack
**Backend:**
- PHPUnit (unit tests)
- Pest (feature tests)
**Frontend:**
- Vitest (unit tests)
- Playwright (E2E tests)
**Decision:** Include all from day 1
### Version Strategy
**Question:** Which versions to use?
**Decision:** Use latest versions across the stack
- **Laravel 12** (latest major version)
- **PHP 8.4** (compatible with Laravel 12)
- **All other dependencies:** Use `:latest` tags (PostgreSQL, Redis, Node, npm packages)
**Rationale:**
- Stay current with latest features and security patches
- Avoid version lock-in from the start
- Docker `:latest` tags ensure fresh installs get newest versions
---
## Architecture Decisions
### Containerization
**Requirement:** "From get go, everything must be containerised."
**Additional Constraint:** "Do not add any proxy manager (NPM, Caddy, or Traefik). My environment already runs an NPM."
**Decision:** Docker Compose with 4 containers
1. **Frontend**: SvelteKit (port 5173)
2. **Backend**: Laravel (port 3000)
3. **Database**: PostgreSQL (port 5432)
4. **Cache**: Redis (port 6379)
**Reverse Proxy:**
- Use existing Nginx Proxy Manager
- NPM routes `/api/*` → Laravel
- NPM routes `/*` → SvelteKit
### Multi-Tenancy
**Question:** "Should we build multi-tenant from day 1?"
**AI Recommendation:** "Start single-tenant. Add tenant_id column when needed."
**Your Response:** "AGREED"
**Rationale:** Reduces complexity, easy to add later
### Environment Configuration
**Question:** ".env files or Docker secrets?"
**AI Recommendation:** ".env files for local, Docker secrets in prod"
**Your Response:** ".env everywhere"
**Decision:** .env files in all environments
- Simpler configuration management
- Consistent across local/prod
### Development Environment
**Question:** "Docker Compose for local dev, or native setup?"
**AI Recommendation:** "Docker Compose from the start. Ensures prod parity."
**Your Response:** "100% agree. If possible, we should have at least the local dev avoid building after every change (may be code mounted)"
**Decision:** Docker Compose with code-mounted volumes
- Hot reload for both frontend and backend
- Avoid rebuilding containers on every change
- Volume mounts: `./frontend:/app`, `./backend:/var/www`
### Real-Time Updates
**Question:** "Do you need live updates (WebSockets), or is polling OK?"
**AI Recommendation:** "Start with polling. Add WebSockets if needed."
**Your Response:** "I dont think we need to sweat on it. Go with a basic implementation. Polling is good enough."
**Decision:** Polling (defer WebSockets to Phase 2)
### State Management (Frontend)
**Question:** "Svelte stores for UI state, or always fetch from API?"
**AI Recommendation:** "Use Svelte stores for UI state (filters, modals), API queries for data."
**Your Response:** "Agreed."
**Decision:** Minimal Svelte stores (UI state only)
### Report Exports
**Question:** "Will users need PDF/CSV exports?"
**AI Recommendation:** "Start with on-screen reports, add exports in phase 2."
**Your Initial Response:** "Good to have at this time."
**AI Clarification:** "Should exports be in MVP scope, or phase 2?"
**Final Decision:** Phase 2
- **Rationale**: Keeps MVP scope tight, adds 4 hours of work
- Interactive dashboard is primary value
### Caching Strategy
**Question Raised by You:** "Should we talk about a caching layer?"
**Options Discussed:**
1. Database Query Caching
2. API Response Caching
3. Full-page caching
**AI Recommendation:** "Start without caching, add Redis in Phase 2 if slow"
**Your Response:** "Query caching and Response caching on Redis from Day 1. No need to sweat on refactoring it everywhere."
**Decision:** Redis caching from day 1
- Query caching (expensive calculations)
- Response caching (GET endpoints)
- Automatic cache invalidation on mutations
- TTL: 1 hour (allocations), 15 min (reports), 24 hours (master data)
---
## Quality & Testing Decisions
### Project-Level Standing Instructions
**Your 5 Points (to be encoded in OpenSpec config.yml):**
1. **Every change must have unit tests, E2E test, regression tests** (whether prompted or not)
2. **Changes must end with code review** for style, standard, security
3. **Verification (`/opsx-verify`) must trigger checking of uncovered code** (code not tested)
4. **Commits must be granular** (one fix = one commit)
5. **Tests run in a progressive loop**:
- Test → Create issue in repo → Fix → Retest + Regression test
- Loop until all issues fixed
**AI Question:** "Is this for ALL tests, or specifically for E2E/integration tests?"
**Your Clarification:** "I agree. Let us go for a kill only in E2E and Integration."
**AI Concern:** "This workflow can slow velocity. For MVP, start with 'every test must pass before merge' and defer granular issue-loop to phase 2?"
**Your Response:** "Agreed"
**Final Decision:**
- **MVP**: All tests must pass, granular commits, code review
- **Phase 2**: Issue-driven test loop for E2E/integration failures
### Code Coverage Threshold
**AI Question:** "What code coverage % for /opsx-verify?"
**Your Response:** "Let us call it >70%"
**Decision:** >70% code coverage required
- Checked in `/opsx-verify`
- Blocks merge if below threshold
### Data Validation Rules
**AI Question:** "Should we document validation rules in OpenSpec?"
**Your Response:** "OpenSpec document must have all required data. I believe we need it there for verification and regression tests. Thoughts?"
**AI Agreement:** "Absolutely. Rules inform API implementation, test cases, and verification."
**Decision:** Create `validation-rules.md` in OpenSpec changes
- These rules drive Laravel validation
- Inform test case generation
- Used in `/opsx-verify`
### RBAC (Role-Based Access Control)
**AI Question:** "Can a Manager see only their projects, or all projects?"
**Your Clarification:** "Can see all projects. But not allocate to other team's members."
**Decision:** RBAC Matrix defined
| Persona | Can See | Can Modify |
|---------|---------|------------|
| Superuser | All | All |
| Manager | All projects (read-only for others') | Own projects, own team allocations |
| Developer | Own allocations, assigned projects | Own actuals only |
| Top Brass | All reports | Nothing (read-only) |
---
## Deferred Features
### Phase 2 Deferrals
| Feature | Reason for Deferral | Estimated Lift |
|---------|---------------------|----------------|
| **Notifications (WebSocket)** | Allocations are monthly, not time-critical | ~6 hours |
| **PDF/CSV Exports** | On-screen reports sufficient for MVP | ~4 hours |
| **Background Jobs** | No heavy processing in MVP, Laravel Queue ready | ~2 hours |
| **Audit Logging** | No compliance requirement for MVP | ~3 hours |
| **Advanced Caching (pre-calculated reports)** | Start with on-demand queries | ~4 hours |
| **API Versioning (`/api/v1/`)** | Not needed until breaking changes | ~2 hours |
| **Issue-driven test loop** | Slower velocity for MVP | ~8 hours |
### Notifications Deep-Dive
**AI Presented 3 Options:**
**Option A:** Include WebSocket + 1 notification PoC (~6 hours)
- Pros: Real-time updates, framework ready
- Cons: Adds complexity, delays other features by ~1 day
**Option B:** Skip notifications entirely for MVP
- Pros: Keeps scope tight, faster MVP
- Cons: Users must refresh to see changes
- **Debt accrual:** Low (easy to add later)
**Option C:** Polling-based notifications (~2 hours)
- SvelteKit polls every 30s
- Pros: Simple, users see changes quickly
- Cons: Not true real-time, more server load
**AI Recommendation:** Option B (skip for MVP)
**Your Question:** "Wont it become a technical debt? How big the lift will be to at least set up the wiring for notifications (websocket setup and one notification implemented as a proof of concept?)"
**AI Response:** "6 hours total lift. Not worth it for MVP - allocations are monthly, not time-critical."
**Your Decision:** "Ok. Option B."
---
## Rejected Options
### Options Considered but Not Chosen
| Option | Why Rejected |
|--------|--------------|
| **Laravel + Blade Templates** | Less interactive UI, harder to build dashboards |
| **Laravel + Vue.js** | You preferred learning Svelte over Vue |
| **Next.js + Node.js** | You have PHP background, prefer Laravel |
| **SQLite for local dev** | Avoid migration pain, PostgreSQL from start |
| **Session-based auth** | JWT chosen for future mobile support |
| **Multi-tenancy from day 1** | Adds complexity, defer to post-MVP |
| **WebSocket notifications in MVP** | Not time-critical, 6 hours of work |
| **PDF/CSV exports in MVP** | On-screen reports sufficient initially |
| **GraphQL** | REST is simpler for MVP |
| **Chart.js / Plotly / ECharts** | Recharts chosen (good balance) |
| **Shadcn/ui / Svelte Material UI** | DaisyUI chosen (faster development) |
| **Custom-built table component** | TanStack Table chosen (industry standard) |
---
## Open Questions (Resolved)
### 1. Over/Under Forecast Context
**Initial Confusion:** "Is over/under forecast about allocation vs approved estimate, or allocation vs capacity?"
**Your Clarification:** "In the project's context, yes. it is allocation vs approved. (For the future phases, there will be over/under forecast for resources - that will be based on individual's allocation vs their capacity. May be we can keep that aside for now.)"
**Example Correction:**
- **AI Example:** "Month 1 allocation: 80hrs → Under-forecast (OK)"
- **Your Correction:** "Not OK. Because this money is my salary! We always try to be on par - 100%. If it is under-forecast, call that out."
**Resolution:** Both over and under-forecast are flagged. Under is YELLOW, Over is RED.
### 2. Availability Model
**Initial Confusion:** "Is availability 1.0 = 8 hours/day, or is it a percentage?"
**Your Clarification:** "Hours per day must be configurable per project. 1 means, 100% of a productive day. .5 means half of that and so on. I dont want to make it too granular thats why I had stops on 1, .5 and 0. Then there are H - holidays and O- weekend offs."
**Resolution:** Availability is 0, 0.5, or 1.0 (not percentage). 0 = unavailable or PTO.
### 3. Untracked Resource Purpose
**Initial Confusion:** "Is this for contractors, or overhead?"
**Your Clarification:** "We might have some time allocated for DevOps team which is not part of my team but might out bill to another team. For that purpose."
**Resolution:** Untracked resource is for external team time (not billed in this system).
### 4. Team Structure
**Initial Confusion:** "Does 'Team' mean sub-teams?"
**Your Clarification:** "Yes. Read that as 'Role'."
**Resolution:** Team = Role (e.g., Frontend, Backend, QA, PM, Architect).
### 5. Manager Permissions
**Initial Confusion:** "Can a Manager allocate to projects outside their team?"
**Your Clarification:** "Can see. But not allocate to other team's members."
**Resolution:** Managers see all projects (read-only for others'), but can only allocate their own team members.
---
## Timeline
### Conversation Flow
**February 17, 2026:**
1. **Initial Problem Statement** (09:00-09:30)
- You described the spreadsheet nightmare
- Identified 4 personas
- Outlined capacity planning → allocation → actuals flow
2. **Requirements Deep-Dive** (09:30-11:00)
- Clarified capacity planning details (availability model)
- Defined project lifecycle states
- Detailed allocation matrix requirements
- Discussed reporting needs
3. **Technical Stack Discussion** (11:00-12:00)
- Debated Laravel vs alternatives → Laravel chosen
- Frontend: Vue vs Svelte → SvelteKit chosen
- Database: SQLite vs PostgreSQL → PostgreSQL chosen
- Authentication: Session vs JWT → JWT chosen
4. **Architecture Decisions** (12:00-13:00)
- Containerization approach (Docker Compose)
- Multi-tenancy deferral
- Caching strategy (Redis from day 1)
- Real-time updates (polling, defer WebSockets)
5. **Quality Standards** (13:00-13:30)
- Testing requirements (>70% coverage)
- Code review process
- Commit standards (granular)
- Issue-driven test loop (defer to Phase 2)
6. **Frontend Libraries** (13:30-14:00)
- UI components: DaisyUI chosen
- Charts: Recharts chosen
- Tables: TanStack Table chosen
- Forms: Superforms + Zod chosen
7. **Final Verification** (14:00-14:30)
- Reviewed complete architecture
- Confirmed no missing pieces
- Decided on API documentation (Scribe)
- Named the project: **Headroom**
8. **Documentation Request** (14:30-15:00)
- Request for comprehensive documentation
- Mermaid diagrams
- Word document for hardcopy
### Key Turning Points
**Moment 1: Naming the Project**
- You chose "Headroom" over "Margin"
- This crystallized the product's identity
**Moment 2: SvelteKit Decision**
- Despite AI recommending Laravel + Vue (easier)
- You chose SvelteKit (more learning, cleaner separation)
- This showed willingness to learn for better architecture
**Moment 3: Redis from Day 1**
- AI recommended deferring caching
- You insisted on Redis from day 1 (avoid refactoring debt)
- This showed pragmatic technical judgment
**Moment 4: "This money is my salary!"**
- Clarified that under-forecast is NOT acceptable
- Both over and under-forecast must be flagged
- This revealed the business criticality of accurate allocation
**Moment 5: "One last check before we lock in"**
- You paused before committing to the stack
- Requested comprehensive review
- This showed careful, deliberate decision-making
---
## Considerations & Trade-offs
### Decision Matrix
| Decision | Benefit | Cost | Rationale |
|----------|---------|------|-----------|
| **SvelteKit (separate)** | Clean separation, modern framework | Deployment complexity, learning curve | Better long-term architecture |
| **Redis from day 1** | No refactoring debt later | Slightly more upfront setup | Prevents future pain |
| **JWT over sessions** | Mobile-ready, stateless | More complex than sessions | Future-proofing |
| **PostgreSQL from day 1** | No migration later | Heavier than SQLite | Production-grade from start |
| **Defer notifications** | Faster MVP | Users must refresh | Not time-critical for monthly planning |
| **Defer exports** | Tighter scope | No PDF/CSV initially | On-screen reports are primary value |
| **TanStack Table** | Powerful, standard | Learning curve (you're unfamiliar) | Industry best practice |
| **DaisyUI** | Fast development | Opinionated | Speed > customization for MVP |
### Risk Assessment
**Low Risk:**
- Laravel choice (you have PHP background)
- PostgreSQL choice (mature, well-supported)
- Redis choice (simple, well-integrated with Laravel)
**Medium Risk:**
- SvelteKit choice (learning curve, but modern and well-documented)
- TanStack Table (unfamiliar to you, but powerful)
- Two-container deployment (more moving parts, but cleaner)
**Mitigated Risks:**
- **Over-complexity:** Deferred features to Phase 2 (notifications, exports, multi-tenancy)
- **Performance:** Redis caching from day 1
- **Testing debt:** >70% coverage enforced from day 1
---
## Success Metrics (Defined)
### MVP Success Criteria
**Functional Completeness:**
- ✅ Users can define team capacity
- ✅ Users can create projects with approved estimates
- ✅ Users can allocate resources month-by-month
- ✅ Users can log actual hours
- ✅ System validates allocations (over/under warnings)
- ✅ Users can view 5 core reports
- ✅ RBAC enforced (4 personas)
**Quality Metrics:**
- ✅ All tests passing (unit + E2E)
- ✅ Code coverage >70%
- ✅ Zero linting errors
- ✅ API documentation auto-generated
**Usability Metrics (Post-Launch):**
- Manager can complete monthly allocation in <30 minutes (vs 2+ hours in spreadsheet)
- Zero billing errors in first 3 months (over/under caught before invoicing)
- 90% of team members log actuals weekly
**AI Rationale:** "Fair but not too lenient. Manager time savings is measurable. Billing error prevention is critical. Adoption (90%) is achievable but requires discipline."
---
## Appendix: Conversation Highlights
### Most Insightful Moments
**On Under-Forecasting:**
> "Not OK. Because this money is my salary! We always try to be on par - 100%. If it is under-forecast, call that out."
**On Naming:**
> "Headroom. It's the word managers actually say ('do we have headroom for this?'), it immediately signals capacity planning, and it's memorable without being try-hard."
**On Caching:**
> "Query caching and Response caching on Redis from Day 1. No need to sweat on refactoring it everywhere."
**On Quality:**
> "I know this will be a time taking process. But I believe it will be worth it."
**On Final Review:**
> "Now this is the part I am most scared about. If I say yes, we need to stick to this rule book. Did I forget anything?"
### Your Leadership Style
**Observations from conversation:**
- **Pragmatic:** Willing to defer features to keep scope tight
- **Quality-focused:** Insisted on testing, code review, coverage from day 1
- **Deliberate:** Paused multiple times to verify decisions before committing
- **Learning-oriented:** Chose SvelteKit despite unfamiliarity, trusted AI recommendations on unfamiliar tools (TanStack Table)
- **Business-minded:** Constantly connected technical decisions to business impact (billing accuracy, manager time savings)
---
## Next Steps (Post-Documentation)
### Immediate Actions
1. **Review Documentation**
- Read Project Charter
- Review Architecture Document
- Verify Decision Log captures everything
2. **Formalize in OpenSpec**
- Create first change: `/opsx-new headroom-foundation`
- Document proposal, specs, design, tasks
- Begin implementation
3. **Project Setup**
- Initialize Laravel project
- Initialize SvelteKit project
- Create Docker Compose setup
- Configure PostgreSQL + Redis
4. **First Sprint (Week 1)**
- Database schema design
- Docker Compose working
- JWT authentication
- Basic CRUD for team members
---
**Document Control:**
- **Owner:** Santhosh J
- **Type:** Conversation Archive & Decision Log
- **Purpose:** Comprehensive record for future reference
- **Intended Audience:** Santhosh J, Associate
- **Format:** Markdown (for git), Word (for hardcopy)
---
*"This is my magnum opus project as of date."* — Santhosh J, February 17, 2026
---
*End of Decision Log*

637
docs/headroom-executive-summary.md Normal file
View File

@@ -0,0 +1,637 @@
# HEADROOM
## Resource Planning & Capacity Management System
**Executive Summary & Technical Specification**
---
**Project Owner:** Santhosh J
**Date:** February 17, 2026
**Version:** 1.0
**Status:** Approved for Development
---
## Table of Contents
1. [Executive Overview](#executive-overview)
2. [The Problem](#the-problem)
3. [The Solution](#the-solution)
4. [Technical Architecture](#technical-architecture)
5. [Core Features](#core-features)
6. [Quality Standards](#quality-standards)
7. [Timeline & Phases](#timeline--phases)
8. [Success Metrics](#success-metrics)
---
## Executive Overview
### What is Headroom?
Headroom is a web-based resource planning and capacity management tool designed to solve the allocation chaos faced by engineering managers juggling multiple projects and team members.
**The Name:** "Headroom" captures the central question managers ask daily: "Do we have headroom for this new work?"
### The Business Case
**Current State:** Managing 10-15 developers across 10-12 concurrent projects using spreadsheets
- Manual capacity calculations prone to errors
- No validation mechanisms
- Billing errors (over-allocation → overcharge, under-allocation → undercharge)
- No visibility into team capacity
- No audit trail
**Future State:** Structured system that:
- Automates capacity calculations
- Validates allocations against estimates
- Prevents billing errors before they happen
- Provides clear visibility into team headroom
- Tracks planned vs actual hours
**ROI:** Manager time savings: 2+ hours → <30 minutes per monthly allocation cycle
---
## The Problem
### Pain Points
**1. Capacity Calculation Chaos**
- Manual calculations across holidays, PTO, weekends
- No systematic way to track who's available when
- Hard to answer: "Who has capacity for new work?"
**2. Billing Errors**
- **Over-allocation:** More hours allocated than approved estimate → Overcharge client → Escalations
- **Under-allocation:** Fewer hours allocated than approved estimate → Undercharge → Revenue loss
- Both scenarios are unacceptable: "This money is my salary!"
**3. No Validation**
- Easy to over-allocate people or projects
- No warnings when allocations exceed capacity
- Spreadsheet formulas break, go unnoticed
**4. Visibility Gap**
- Can't easily see team utilization
- Hard to compare planned vs actual hours
- No forecasting capability
**5. No Audit Trail**
- Changes are invisible
- Can't track who changed what allocation when
---
## The Solution
### The Monthly Cycle
Headroom organizes work around monthly capacity planning cycles:
```
┌─────────────────────────────────────────────────────────┐
│ MONTHLY CYCLE │
├─────────────────────────────────────────────────────────┤
│ │
│ 1. CAPACITY PLANNING │
│ • Define team members (name, role, rate) │
│ • Mark holidays, PTO, weekends │
│ • Set daily availability (0, 0.5, 1.0) │
│ OUTPUT: Individual & team capacity, revenue potential│
│ │
│ 2. PROJECT SETUP │
│ • Track project status (lifecycle states) │
│ • Define approved estimate (billable hours) │
│ • Forecast effort across months │
│ OUTPUT: Month-wise forecast, over/under indicators │
│ │
│ 3. RESOURCE ALLOCATION │
│ • Allocate hours per person per project per month │
│ • Validate: allocation ≤ capacity, allocation = estimate│
│ • Track "untracked" resources (external teams) │
│ OUTPUT: Clear allocation view, RED/YELLOW flags │
│ │
│ 4. ACTUALS TRACKING │
│ • Team members log hours worked (monthly) │
│ • Calculate utilization (planned vs actual) │
│ OUTPUT: Running & overall utilization metrics │
│ │
└─────────────────────────────────────────────────────────┘
```
### Four Personas
| Persona | Primary Use Case |
|---------|------------------|
| **Superuser** | System setup, configuration, master data management |
| **Manager** | Resource planning, allocation, team oversight, approve estimates |
| **Developer** | View allocations, log hours, understand own workload |
| **Top Brass** | Executive reports, forecasts, budget visibility (read-only) |
### Key Validation Rules
**Over/Under Allocation Detection:**
- **GREEN:** Allocation = Approved estimate (100%)
- **YELLOW:** Under-allocated (<100%) → Will undercharge
- **RED:** Over-allocated (>100%) → Will overcharge
**Both under and over are flagged.** The goal: Always allocate 100% of approved estimate.
---
## Technical Architecture
### System Overview
```
┌─────────────────────────────────────────────────────────┐
│ ARCHITECTURE │
├─────────────────────────────────────────────────────────┤
│ │
│ FRONTEND (SvelteKit - Port 5173) │
│ • Tailwind CSS + DaisyUI (UI components) │
│ • Recharts (visualizations) │
│ • TanStack Table (data grids) │
│ • Superforms + Zod (form validation) │
│ • Vitest (unit tests) + Playwright (E2E tests) │
│ │
│ BACKEND (Laravel API - Port 3000) │
│ • Laravel 12 (latest, PHP 8.4) │
│ • Laravel API Resources (consistent JSON) │
│ • JWT Authentication (tymon/jwt-auth) │
│ • Laravel Scribe (SwaggerUI API docs) │
│ • PHPUnit + Pest (testing) │
│ │
│ DATA LAYER │
│ • PostgreSQL (latest) (primary database) │
│ • Redis (latest) (query + response caching) │
│ │
│ INFRASTRUCTURE │
│ • Docker Compose (4 containers) │
│ • Nginx Proxy Manager (reverse proxy) │
│ • Code-mounted volumes (hot reload) │
│ • .env configuration (all environments) │
│ │
└─────────────────────────────────────────────────────────┘
```
### Why These Choices?
**SvelteKit:**
- Modern, reactive framework
- Great for data-heavy dashboards
- Smaller bundle sizes
- Chosen over Vue/React for learning/modernization
**Laravel:**
- Project owner has PHP background
- Robust API development framework
- Rich ecosystem (Scribe, Pest, Pint)
- Excellent PostgreSQL support
**PostgreSQL:**
- Production-grade from day 1 (avoid SQLite migration)
- JSON operators for flexible queries
- Better for reporting queries
**Redis:**
- Caching from day 1 (avoid refactoring debt)
- Query caching + response caching
- Automatic cache invalidation
**JWT Authentication:**
- Token-based (suitable for SPA)
- Future-ready (easier mobile support later)
### Deployment Architecture
**Local Development:**
- 4 Docker containers (frontend, backend, postgres, redis)
- Code-mounted volumes (hot reload, no rebuild)
- Docker Compose orchestration
**Production:**
- Same containerized setup
- Nginx Proxy Manager routes:
- `/` → SvelteKit
- `/api/*` → Laravel API
---
## Core Features
### 1. Capacity Planning
**Inputs:**
- Team member: Name, role, hourly rate
- Calendar: Holidays, weekends
- PTO requests
- Daily availability: 0 (unavailable), 0.5 (half day), 1.0 (full day)
**Outputs:**
- Individual capacity (person-days per month)
- Team capacity (total available person-days)
- Possible revenue (if fully utilized)
**Key Insight:** Availability is per-person, per-day. "1.0" means 100% of a productive day (hours per day configurable).
---
### 2. Project Management
**Project Lifecycle:**
```
NA/Support → Initial → Gathering Estimates → Estimate Pending Approval
↓
Estimate Rework ←───────┘
↓
Estimate Approved → Funded → Scheduled → In-Progress
↓
Ready for Prod → Done
↓
[Optional: On-Hold, Cancelled]
```
**Key Attributes:**
- **Approved Estimate:** Total billable hours approved by client
- **Forecasted Effort:** Month-by-month breakdown of those hours
- **Type:** Project (billable) vs Support (ongoing ops)
**Validation:**
- Sum of forecasted effort must equal approved estimate (±5% tolerance)
- Alerts when monthly team allocation exceeds team capacity
---
### 3. Resource Allocation
**The Allocation Matrix:**
For a given month, view all projects vs all team members:
```
┌──────────────────────────────────────────────────────┐
│ Project │ Dev A │ Dev B │ Dev C │ Untracked │ Total│
├────────────┼───────┼───────┼───────┼───────────┼─────┤
│ Project X │ 40h │ 20h │ 0 │ 10h │ 70h │
│ Project Y │ 20h │ 40h │ 30h │ 0 │ 90h │
│ Project Z │ 0 │ 80h │ 60h │ 0 │140h │
├────────────┼───────┼───────┼───────┼───────────┼─────┤
│ Total │ 60h │ 140h │ 90h │ 10h │300h │
│ Capacity │ 160h │ 160h │ 120h │ ∞ │440h │
│ % Util │ 38% │ 88% │ 75% │ N/A │ 68% │
└──────────────────────────────────────────────────────┘
```
**Features:**
- Visual indicators: GREEN (100%), YELLOW (<100%), RED (>100%)
- "Untracked" resource for external team time (not billed)
- Inline editing
- Sortable, filterable
**Validation Rules:**
- Cannot allocate negative hours
- Cannot allocate more than person's capacity (warning)
- Sum of project allocations should equal approved estimate (±5%)
---
### 4. Actuals & Utilization
**Data Entry:**
- Team members log hours worked per project per month
- Manual entry (monthly aggregate, can update weekly incrementally)
- No time-tracking tool integration (MVP)
**Calculations:**
- **Running Utilization:** (Allocated hours YTD) / (Capacity YTD) × 100%
- **Overall Utilization:** (Allocated hours this month) / (Capacity this month) × 100%
- **Variance:** Actual hours - Allocated hours
**Display:**
- Utilization % shown alongside capacity view
- Color-coded (low, optimal, high utilization)
---
### 5. Reports & Analytics
**Core Reports:**
| Report | Purpose | Filters |
|--------|---------|---------|
| **Forecast Summary** | Multi-period view of allocations and revenue | Date range, team, project, status |
| **Utilization Summary** | Team and individual utilization trends | Date range, team member, role |
| **Cost Summary** | Revenue forecasts based on allocations × rates | Date range, project, client |
| **Allocation Report** | Who's allocated to what, month-by-month | Month, team, project |
| **Variance Report** | Planned vs Actual analysis | Date range, project, person |
**All reports:**
- Highly customizable filters
- On-screen display (PDF/CSV export deferred to Phase 2)
- Cached for performance (Redis)
---
### 6. Role-Based Access Control (RBAC)
**Permission Matrix:**
| Action | Superuser | Manager | Developer | Top Brass |
|--------|-----------|---------|-----------|-----------|
| View all projects | ✅ | ✅ (read-only for others') | ❌ (assigned only) | ✅ (read-only) |
| Create/edit projects | ✅ | ✅ (own projects) | ❌ | ❌ |
| Allocate resources | ✅ | ✅ (own team only) | ❌ | ❌ |
| View allocations | ✅ | ✅ | ✅ (own only) | ✅ |
| Log hours | ✅ | ✅ | ✅ | ❌ |
| View reports | ✅ | ✅ | ❌ | ✅ |
| Configure system | ✅ | ❌ | ❌ | ❌ |
---
## Quality Standards
### Testing Requirements
**Every change must include:**
1. **Unit tests** (backend: PHPUnit, frontend: Vitest)
2. **E2E tests** (Playwright)
3. **Regression tests** (full suite on each change)
**Coverage Target:** >70% (enforced in `/opsx-verify`)
**Test Loop (Phase 2):**
- E2E/Integration failure → Create GitHub issue → Fix → Retest → Close issue
- (MVP: Fix inline, no issue creation)
---
### Code Review Checklist
Before merge:
- ✅ **Style:** PSR-12 (PHP), Prettier (JS), ESLint (SvelteKit)
- ✅ **Standards:** Laravel conventions, SvelteKit best practices
- ✅ **Security:** Input validation, SQL injection prevention, XSS protection
- ✅ **Tests:** All tests passing, coverage >70%
- ✅ **API Docs:** Scribe auto-generated documentation up-to-date
---
### Commit Standards
**Granular commits:** One fix = one commit
**Format:**
```
[Type] Brief description (50 chars max)
Detailed explanation (optional, 72 char wrap)
Refs: openspec/changes/<change-name>
```
**Types:** `feat`, `fix`, `refactor`, `test`, `docs`, `chore`
---
## Timeline & Phases
### MVP (Phase 1) - 6-8 Weeks
**Sprint 1: Project Setup (1 week)**
- Docker Compose setup (4 containers)
- Laravel + SvelteKit scaffolding
- Database schema design
- JWT authentication
**Sprint 2: Capacity Planning (1.5 weeks)**
- Team member CRUD
- Holiday/PTO calendar
- Availability tracking
- Capacity calculations
**Sprint 3: Project Management (1.5 weeks)**
- Project CRUD
- Status state machine
- Approved estimate tracking
- Forecasted effort
**Sprint 4: Resource Allocation (2 weeks)**
- Allocation matrix UI
- Validation rules (over/under detection)
- Visual indicators (GREEN/YELLOW/RED)
- Untracked resource bucket
**Sprint 5: Actuals & Reporting (2 weeks)**
- Time logging interface
- Utilization calculations
- 5 core reports with filters
- Redis caching implementation
**Sprint 6: Testing & Polish (1 week)**
- E2E test coverage (Playwright)
- Code review
- Bug fixes
- API documentation (Scribe)
---
### Phase 2 - Enhancements (3-4 weeks)
**Deferred Features:**
- Notifications (WebSocket) - ~6 hours
- PDF/CSV exports - ~4 hours
- Background jobs (Laravel Queue) - ~2 hours
- Audit logging - ~3 hours
- Advanced caching (pre-calculated reports) - ~4 hours
- Issue-driven test loop - ~8 hours
- Bug fixes from production use
---
### Phase 3 - Scale & Optimize (TBD)
**Future Enhancements:**
- Multi-tenancy
- Mobile optimization
- AI-powered forecasting
- Integration APIs (time-tracking, accounting)
- Advanced resource-level over/under forecasting
---
## Success Metrics
### MVP Success Criteria
**Functional Completeness:**
- ✅ Users can define team capacity (members, holidays, PTO, availability)
- ✅ Users can create projects with approved estimates
- ✅ Users can allocate resources to projects month-by-month
- ✅ Users can log actual hours worked
- ✅ System validates allocations (over/under warnings)
- ✅ Users can view 5 core reports (forecast, utilization, cost, allocation, variance)
- ✅ RBAC enforced (4 personas: Superuser, Manager, Dev, Top Brass)
**Quality Metrics:**
- ✅ All tests passing (unit + E2E)
- ✅ Code coverage >70%
- ✅ Zero linting errors
- ✅ API documentation auto-generated (SwaggerUI)
- ✅ Docker Compose setup working (local dev)
**Usability Metrics (Post-Launch):**
- **Manager time savings:** Complete monthly allocation in <30 minutes (vs 2+ hours in spreadsheet)
- **Billing accuracy:** Zero billing errors in first 3 months (over/under caught before invoicing)
- **Adoption:** 90% of team members log actuals weekly
---
## Data Model (Simplified)
### Core Entities
**Team Member**
- Name, Role, Hourly Rate, Active status
**Project**
- Project Code, Title, Status, Type, Approved Estimate, Forecasted Effort
**Allocation**
- Project + Team Member + Month + Allocated Hours
**Actual**
- Project + Team Member + Month + Hours Logged
**Supporting Entities:**
- Roles, Project Statuses, Project Types, Holidays, PTO
### Key Relationships
```
TEAM_MEMBER ──< ALLOCATION >── PROJECT
│ │
└─< ACTUAL >────────────────┘
│
└─< PTO
```
---
## Master Data / Taxonomy
**Configurable Lists (Admin-managed):**
**Roles/Teams:**
- Frontend Developer
- Backend Developer
- QA Engineer
- DevOps Engineer
- UX Designer
- Project Manager
- Architect
**Project Statuses:**
- NA/Support, Initial, Gathering Estimates, Estimate Pending Approval, Estimate Rework, Estimate Approved, Funded, Scheduled, In-Progress, Ready for Prod, Done, On-Hold, Cancelled
**Project Types:**
- Project (billable)
- Support (ongoing ops)
**Availability Options:**
- 0 (unavailable/PTO)
- 0.5 (half day)
- 1.0 (full day)
---
## Explicitly Out of Scope
**Features NOT included:**
- Time-tracking tool integration (manual entry only)
- Mobile app (desktop web app only)
- Invoicing integration (billing forecasts only, not actual invoicing)
- Project task management (project-level tracking only, not task-level)
- Calendar sync (Google, Outlook) - manual PTO/holiday entry
- AI-powered forecasting (rule-based validation sufficient for MVP)
---
## Key Design Decisions
### Decision Log Summary
| Decision | Rationale |
|----------|-----------|
| **SvelteKit (separate from Laravel)** | Clean separation, modern framework, worth the learning curve |
| **Redis caching from day 1** | Prevents refactoring debt ("No need to sweat on refactoring it everywhere") |
| **JWT authentication** | Token-based, future-ready for mobile |
| **PostgreSQL from day 1** | Avoid migration pain, production-grade |
| **Defer notifications (WebSocket)** | Not time-critical for monthly planning, saves 6 hours |
| **Defer PDF/CSV exports** | On-screen reports sufficient for MVP, adds 4 hours |
| **>70% code coverage** | Fair but not too lenient, enforced from day 1 |
| **Granular commits** | One fix = one commit, better git history |
| **Both over and under-forecast flagged** | "This money is my salary!" - 100% allocation is goal |
---
## Project Philosophy
### Guiding Principles
1. **Quality over speed** - >70% test coverage, code review, security checks from day 1
2. **Prevent technical debt** - Redis from day 1, containerization from start
3. **100% allocation is the goal** - Both over and under-forecast are problems
4. **Manager time is valuable** - Reduce monthly allocation time from 2+ hours to <30 minutes
5. **Billing accuracy is critical** - Zero tolerance for over/under-charging clients
6. **Defer, don't compromise** - Features deferred to Phase 2, not cut or half-implemented
---
## Contact & Ownership
**Project Owner:** Santhosh J
**Project Type:** Magnum Opus ("This is my magnum opus project as of date.")
**Intended Users:** Self + Associate
**Timeline:** MVP in 6-8 weeks, Phase 2 in 3-4 weeks
---
## Appendix: Technology Stack Summary
### Backend
- Laravel 12 (latest, PHP 8.4-FPM)
- PostgreSQL (latest)
- Redis (latest)
- JWT Authentication (tymon/jwt-auth)
- Laravel Scribe (SwaggerUI)
- PHPUnit + Pest (testing)
### Frontend
- SvelteKit
- Tailwind CSS + DaisyUI
- Recharts (charts)
- TanStack Table (data grids)
- Superforms + Zod (forms & validation)
- Vitest + Playwright (testing)
### Infrastructure
- Docker Compose (4 containers)
- Nginx Proxy Manager (reverse proxy)
- .env configuration
- Code-mounted volumes (hot reload)
---
**Document Version:** 1.0
**Last Updated:** February 17, 2026
**Status:** Approved for Development
---
*"Headroom - Know your capacity, prevent billing errors, deliver on time."*
---
**END OF EXECUTIVE SUMMARY**

613
docs/headroom-project-charter.md Normal file
View File

@@ -0,0 +1,613 @@
# Headroom - Project Charter & Specifications
**Version:** 1.0
**Date:** February 17, 2026
**Status:** Approved for Development
---
## Executive Summary
**Headroom** is a resource planning and capacity management tool designed to solve the allocation chaos faced by engineering managers juggling multiple projects and team members. It replaces error-prone spreadsheets with a structured system that tracks capacity, forecasts utilization, prevents over/under-billing, and provides clear visibility into team allocation.
**Target Users:**
- Engineering managers (10-15 person teams)
- Managing 10-12 concurrent projects in various stages
- Need month-by-month capacity planning and allocation tracking
**Core Value Proposition:**
- Know exactly who has headroom for new work
- Prevent billing errors (over-allocation → overcharge, under-allocation → undercharge)
- Forecast revenue based on approved estimates and current allocations
- Track planned vs actual hours to understand team utilization
---
## Problem Statement
### Current Pain Points
**The Spreadsheet Nightmare:**
- Manual capacity calculations across holidays, PTO, weekends
- No validation (easy to over-allocate people or projects)
- Hard to see at a glance: "Who has capacity this month?"
- Billing forecasts require manual formula updates
- No audit trail of allocation changes
- Difficult to track planned vs actual hours
**Business Impact:**
- **Over-allocation:** Leads to overcharging clients → escalations, unhappy customers
- **Under-allocation:** Leads to undercharging → revenue loss, unhappy management
- **Resource conflicts:** Multiple managers allocating the same person without visibility
- **Forecast inaccuracy:** Can't reliably predict revenue or capacity needs
---
## Solution Overview
Headroom provides a structured workflow for capacity planning and resource allocation:
```
┌─────────────────────────────────────────────────────────────────┐
│ MONTHLY CAPACITY PLANNING CYCLE │
├─────────────────────────────────────────────────────────────────┤
│ │
│ STEP 1: CAPACITY PLANNING │
│ ──────────────────────────────────────────────────── │
│ • Define team members (name, role, hourly rate) │
│ • Mark holidays, PTO, weekends for the month │
│ • Set availability per day (1=full, 0.5=half, 0=unavailable)│
│ │
│ OUTPUT: │
│ • Individual capacity (person-days per month) │
│ • Team capacity (total available person-days) │
│ • Possible revenue (capacity × hourly rates) │
│ │
├─────────────────────────────────────────────────────────────────┤
│ STEP 2: PROJECT SETUP │
│ ──────────────────────────────────────────────────── │
│ • Track project status (Initial → Estimates → Funded → ...) │
│ • Define approved estimate (total billable hours) │
│ • Forecast effort distribution across months │
│ │
│ OUTPUT: │
│ • Month-wise project forecast │
│ • Alerts when forecast ≠ approved estimate │
│ │
├─────────────────────────────────────────────────────────────────┤
│ STEP 3: RESOURCE ALLOCATION │
│ ────────────────────────────────────────────────────────────│
│ • Allocate hours per person per project per month │
│ • Validation: total allocation ≤ team capacity │
│ • Validation: project allocation = approved estimate │
│ • "Untracked" bucket for external team time │
│ │
│ OUTPUT: │
│ • Clear view: who's allocated to what │
│ • Over/under allocation indicators (RED flags) │
│ • Running utilization % per person │
│ │
├─────────────────────────────────────────────────────────────────┤
│ STEP 4: ACTUALS TRACKING │
│ ────────────────────────────────────────────────────────────│
│ • Team members log hours worked (monthly aggregate) │
│ • Manual entry (no time-tracking tool integration for MVP) │
│ │
│ OUTPUT: │
│ • Running utilization (allocated vs capacity YTD) │
│ • Overall utilization (allocated % per month) │
│ • Variance: planned vs actual │
│ │
└─────────────────────────────────────────────────────────────────┘
```
---
## Complete Requirements
### 1. Capacity Planning
**Inputs:**
- Team member list (name, role/team, hourly rate)
- Calendar data per month (holidays, weekends)
- Individual PTO requests
- Daily availability (1.0 = full day, 0.5 = half day, 0 = unavailable)
**Calculations:**
- Individual capacity = Σ(working days × availability)
- Team capacity = Σ(individual capacities)
- Possible revenue = Σ(individual capacity × hourly rate)
**Outputs:**
- Individual capacity report (person-days per month)
- Team capacity summary
- Revenue potential (if fully utilized)
**Validation Rules:**
- Availability must be 0, 0.5, or 1.0
- Hourly rate must be > 0
- Working days must exclude holidays, weekends, PTO
---
### 2. Project Management
**Project Attributes:**
- Project ID (unique identifier)
- Project title
- Type: Project (billable) / Support (ongoing ops)
- Status (see state machine below)
- Approved estimate (total billable hours)
- Forecasted effort (month-by-month breakdown)
**Project Status State Machine:**
```
NA/Support → Initial → Gathering Estimates → Estimate Pending Approval
↓
Estimate Rework ←───────┘
↓
Estimate Approved → Funded → Scheduled → In-Progress
↓
Ready for Prod → Done
↓
[Optional: On-Hold, Cancelled]
```
**Outputs:**
- Month-wise forecast per project
- Alert when Σ(forecasted effort) ≠ approved estimate (RED flag)
- Alert when monthly team allocation > team capacity (RED flag)
**Validation Rules:**
- Approved estimate must be > 0
- Forecasted effort sum must equal approved estimate (±tolerance)
- Cannot allocate hours to projects in status "Done" or "Cancelled"
---
### 3. Resource Allocation
**Allocation Matrix:**
```
For selected month M:
┌────────────────────────────────────────────────────┐
│ Project │ Dev A │ Dev B │ Dev C │ Untracked │ │
├────────────┼───────┼───────┼───────┼───────────┼──┤
│ Project X │ 40h │ 20h │ 0 │ 10h │ │
│ Project Y │ 20h │ 40h │ 30h │ 0 │ │
│ Project Z │ 0 │ 80h │ 60h │ 0 │ │
├────────────┼───────┼───────┼───────┼───────────┼──┤
│ Total │ 60h │ 140h │ 90h │ 10h │ │
│ Capacity │ 160h │ 160h │ 120h │ ∞ │ │
│ % Util │ 38% │ 88% │ 75% │ N/A │ │
└────────────────────────────────────────────────────┘
```
**Features:**
- Allocate hours per person per project per month
- "Untracked" resource for external team time (no billing tracked)
- Visual indicators:
- GREEN: Allocation = Approved estimate (100%)
- YELLOW: Under-allocated (< 100%)
- RED: Over-allocated (> 100%)
**Outputs:**
- Allocation summary per month
- Per-project allocation % (allocated / approved estimate)
- Per-person utilization % (allocated / capacity)
- Over/under allocation flags
**Validation Rules:**
- Cannot allocate negative hours
- Cannot allocate more than person's monthly capacity (warning, not hard block)
- Cannot allocate to non-existent project or person
- Sum of project allocations should equal approved estimate (tolerance: ±5%)
---
### 4. Actuals & Utilization Tracking
**Data Entry:**
- Team members log hours worked per project per month
- Entry method: Manual (monthly aggregate)
- Updates: Can be incremental (weekly updates accumulate)
**Calculations:**
- **Running utilization:** (Allocated hours YTD) / (Capacity YTD) × 100%
- **Overall utilization:** (Allocated hours this month) / (Capacity this month) × 100%
- **Variance:** Actual hours - Allocated hours (per project, per person)
**Outputs:**
- Actuals vs Planned comparison
- Utilization metrics (running, overall)
- Variance reports (where did we over/under-deliver?)
**Validation Rules:**
- Cannot log negative hours
- Cannot log hours for future months
- Cannot log hours after project status = "Done" (configurable)
---
### 5. Reports & Analytics
**Core Reports:**
| Report | Description | Filters |
|--------|-------------|---------|
| **Forecast Summary** | Multi-period forecast of allocations and revenue | Date range, team, project, status |
| **Utilization Summary** | Team and individual utilization trends | Date range, team member, role |
| **Cost Summary** | Revenue forecasts based on allocations × hourly rates | Date range, project, client |
| **Allocation Report** | Who's allocated to what, month-by-month | Month, team, project |
| **Variance Report** | Planned vs Actual analysis | Date range, project, person |
**Report Features:**
- **Highly customizable filters** (team, person, project, status, date range, type)
- **Export capabilities:** Defer to Phase 2 (PDF/CSV)
- **Caching:** Redis caching for expensive queries
---
### 6. Role-Based Access Control (RBAC)
**Personas & Permissions:**
| Persona | Access Rights | Restrictions |
|---------|---------------|--------------|
| **Superuser** | Full access: setup, config, all projects, all teams | None |
| **Manager** | • Create/edit projects<br>• Allocate resources to own team<br>• View all projects (read-only for other teams)<br>• Approve estimates<br>• View team's utilization reports | • Cannot allocate other teams' members<br>• Cannot edit other managers' projects |
| **Developer** | • View own allocations<br>• Log own hours (actuals)<br>• View project details for assigned projects | • Cannot allocate resources<br>• Cannot change estimates<br>• Cannot view other developers' allocations |
| **Top Brass** | • View all reports (read-only)<br>• Forecast summaries<br>• Utilization dashboards<br>• Cost summaries | • Cannot modify anything<br>• Read-only access only |
**Access Control Implementation:**
- Laravel Policies for model-level authorization
- Middleware for route-level guards
- JWT tokens with role claims
---
## Data Validation Rules
**These rules drive API validation, tests, and verification:**
### Team Members
- Name: Required, max 255 chars
- Role/Team: Required, must exist in master data
- Hourly rate: Required, > 0, numeric (2 decimal places)
- Availability: Must be 0, 0.5, or 1.0
### Projects
- Project ID: Unique, required
- Title: Required, max 255 chars
- Type: Must be "Project" or "Support"
- Status: Must be valid state (see state machine)
- Approved estimate: Required if status ≥ "Estimate Approved", > 0
- Forecasted effort: Sum must equal approved estimate (±5% tolerance)
### Allocations
- Person ID: Must exist in team members
- Project ID: Must exist in projects
- Hours: >= 0, numeric (2 decimal places)
- Month: Valid date (YYYY-MM format)
- Sum of allocations per project ≤ approved estimate + 5%
- Sum of allocations per person ≤ capacity + 20% (warning threshold)
### Actuals
- Person ID: Must exist in team members
- Project ID: Must exist in projects
- Hours: >= 0, numeric (2 decimal places)
- Month: Must be current or past month (cannot log future hours)
- Cannot log hours if project status = "Cancelled" or "Done" (configurable)
### Holidays/PTO
- Date: Valid date
- Type: "Holiday" or "PTO"
- If PTO: must be associated with a team member
---
## Technical Stack
### Backend (Laravel API)
| Component | Technology | Rationale |
|-----------|------------|-----------|
| Framework | Laravel 12 (latest) | Robust PHP framework, rich ecosystem |
| Database | PostgreSQL | Production-grade, ACID compliant, great for reporting |
| Caching | Redis | Query + response caching from day 1 |
| Authentication | JWT (tymon/jwt-auth) | Token-based, suitable for SPA frontend |
| API Design | REST + Laravel API Resources | Standard, well-understood, consistent JSON |
| API Docs | Laravel Scribe (SwaggerUI) | Auto-generated from code comments |
| Testing | PHPUnit (unit) + Pest (feature) | Laravel standard |
| Code Style | PSR-12, Laravel conventions | Industry standard |
| Containerization | Docker (port 3000) | Isolated, reproducible |
| Environment | .env files | Simple configuration management |
### Frontend (SvelteKit)
| Component | Technology | Rationale |
|-----------|------------|-----------|
| Framework | SvelteKit | Modern, reactive, great for dashboards |
| Styling | Tailwind CSS + DaisyUI | Fast development, consistent theming |
| Charts | Recharts | Good balance of power and simplicity |
| Tables | TanStack Table (React Table) | Industry standard, powerful filtering/sorting |
| Forms | Superforms + Zod | Type-safe validation, seamless SvelteKit integration |
| Form Actions | SvelteKit native | Server-side form handling |
| State Management | Svelte stores (minimal) | UI state only (filters, modals) |
| HTTP Client | fetch (native) | No extra dependencies |
| Testing | Vitest (unit) + Playwright (E2E) | Fast, modern testing tools |
| Containerization | Docker (port 5173) | Isolated, hot-reload for dev |
### Infrastructure & Deployment
| Component | Technology | Rationale |
|-----------|------------|-----------|
| Local Dev | Docker Compose | Code-mounted volumes, hot reload |
| Reverse Proxy | Nginx Proxy Manager (existing) | Already running in environment |
| Database Volume | Mounted directory | Portability, easy backup |
| Secrets | .env files (all environments) | Simple, consistent across envs |
| Background Jobs | Laravel Queue + Redis (Phase 2) | Deferred for MVP, easy to add |
---
## Quality Standards & Testing Strategy
### Test Requirements (Per Change)
**Every OpenSpec change must include:**
1. **Unit tests** (backend + frontend)
- Coverage target: >70%
- PHPUnit (Laravel), Vitest (SvelteKit)
2. **E2E tests** (Playwright)
- Happy path + critical error cases
3. **Regression tests**
- Run full test suite on each change
### Code Review Checklist
Before merge, verify:
- **Style:** PSR-12 (PHP), Prettier (JS), ESLint (SvelteKit)
- **Standards:** Laravel conventions, SvelteKit best practices
- **Security:** Input validation, SQL injection prevention, XSS protection, CSRF tokens
- **Tests:** All tests passing, coverage >70%
### Verification Workflow
**`/opsx-verify` must check:**
- All tests passing
- Code coverage >70%
- No uncovered code (files without tests)
- API docs up-to-date (Scribe generation)
- No linting errors
### Commit Standards
- **Granular commits:** One fix = one commit
- **Commit message format:**
```
[Type] Brief description (50 chars max)
Detailed explanation (optional, 72 char wrap)
Refs: #issue-number (if applicable)
```
Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`
### Issue-Driven Test Loop (Phase 2)
For E2E/integration failures:
1. Test fails → Create GitHub issue
2. Fix implementation
3. Retest + regression test
4. Close issue when all tests pass
**For MVP:** Run tests, fix inline (no issue creation yet).
---
## Deferred Features (Phase 2+)
### Deferred to Phase 2
| Feature | Rationale for Deferral | Estimated Lift |
|---------|------------------------|----------------|
| **Notifications** (WebSocket) | Allocations are monthly - not time-critical. Users can refresh. | ~6 hours |
| **PDF/CSV Exports** | On-screen reports sufficient for MVP. Easy to add later. | ~4 hours |
| **Background Jobs** (async) | No heavy processing in MVP. Laravel Queue ready when needed. | ~2 hours |
| **Audit Logging** | No compliance requirement for MVP. | ~3 hours |
| **Advanced Caching** (pre-calculated reports) | Start with on-demand queries. Cache if slow. | ~4 hours |
| **API Versioning** (`/api/v1/`) | Not needed until breaking changes. | ~2 hours |
| **Multi-language Support** | English-only for MVP. | ~8 hours |
| **Resource Over-allocation (advanced)** | MVP shows RED flag. Phase 2: predictive warnings, auto-balancing. | ~6 hours |
### Explicitly Out of Scope
| Feature | Why Not Included |
|---------|------------------|
| **Time-tracking tool integration** | Manual entry sufficient. Integration adds vendor lock-in. |
| **Mobile app** | Desktop web app is primary use case. |
| **Invoicing integration** | Billing forecasts only. Actual invoicing is external. |
| **Project task management** | Project-level tracking only, not task-level. |
| **Calendar sync** (Google, Outlook) | Manual PTO/holiday entry is acceptable. |
| **AI-powered forecasting** | Rule-based validation is sufficient for MVP. |
---
## Considerations & Trade-offs
### Decision Log
| Decision | Option Chosen | Alternative Considered | Rationale |
|----------|---------------|------------------------|-----------|
| **Multi-tenancy** | Single-tenant MVP, add `tenant_id` later | Multi-tenant from day 1 | Reduces complexity, easy to add later |
| **Frontend framework** | SvelteKit | Laravel + Vue, React | Modern, reactive, great for dashboards |
| **Authentication** | JWT | Session-based | Suitable for SPA, easier mobile support later |
| **Caching** | Redis from day 1 | Add later if needed | Prevents refactoring technical debt |
| **Notifications** | Defer to Phase 2 | WebSocket PoC in MVP | Not time-critical, saves 6 hours |
| **Exports** | Defer to Phase 2 | Include in MVP | On-screen reports sufficient initially |
| **Issue-driven tests** | Phase 2 | From day 1 | Slower velocity for MVP, add when more tests exist |
| **API versioning** | Not included | `/api/v1/` from start | No breaking changes expected in MVP |
### Known Limitations (MVP)
1. **No real-time updates:** Users must refresh to see allocation changes
2. **Manual time entry:** No automated time-tracking integration
3. **Single organization:** No multi-tenancy support
4. **English only:** No i18n support
5. **No mobile optimization:** Desktop-first design
---
## Success Metrics
### MVP Success Criteria
**Functional Completeness:**
- ✅ Users can define team capacity (members, holidays, PTO, availability)
- ✅ Users can create projects with approved estimates
- ✅ Users can allocate resources to projects month-by-month
- ✅ Users can log actual hours worked
- ✅ System validates allocations (over/under warnings)
- ✅ Users can view 5 core reports (forecast, utilization, cost, allocation, variance)
- ✅ RBAC enforced (4 personas: Superuser, Manager, Dev, Top Brass)
**Quality Metrics:**
- ✅ All tests passing (unit + E2E)
- ✅ Code coverage >70%
- ✅ Zero linting errors
- ✅ API documentation auto-generated (SwaggerUI)
- ✅ Docker Compose setup working (local dev)
**Usability Metrics (Post-Launch):**
- Manager can complete monthly allocation in <30 minutes (vs 2+ hours in spreadsheet)
- Zero billing errors in first 3 months (over/under allocation caught before invoicing)
- 90% of team members log actuals weekly (adoption metric)
### Phase 2 Success Criteria
- ✅ Real-time notifications working (WebSocket)
- ✅ PDF/CSV exports available for all reports
- ✅ Background jobs processing heavy reports
- ✅ Audit logging capturing all changes
---
## Timeline & Phases
### MVP (Phase 1) - Core Functionality
**Target:** 6-8 weeks
**Sprints:**
1. **Project setup** (1 week)
- Docker Compose setup
- Laravel + SvelteKit scaffolding
- Database schema design
- Authentication (JWT)
2. **Capacity planning** (1.5 weeks)
- Team member CRUD
- Holiday/PTO calendar
- Availability tracking
- Capacity calculations
3. **Project management** (1.5 weeks)
- Project CRUD
- Status state machine
- Approved estimate tracking
- Forecasted effort
4. **Resource allocation** (2 weeks)
- Allocation matrix UI
- Validation rules
- Over/under indicators
- Untracked resource bucket
5. **Actuals & reporting** (2 weeks)
- Time logging interface
- Utilization calculations
- 5 core reports
- Filters & customization
6. **Testing & polish** (1 week)
- E2E test coverage
- Code review
- Bug fixes
- Documentation
### Phase 2 - Enhancements
**Target:** 3-4 weeks (post-MVP)
- Notifications (WebSocket)
- Exports (PDF/CSV)
- Background jobs
- Audit logging
- Advanced caching
- Bug fixes from production use
### Phase 3 - Scale & Optimize
**Target:** TBD (based on usage)
- Multi-tenancy
- Mobile optimization
- AI-powered forecasting
- Integration APIs (time-tracking, accounting)
---
## Appendix: Master Data & Taxonomy
**Configurable Lists (Admin-managed):**
1. **Roles/Teams:**
- Frontend Developer
- Backend Developer
- QA Engineer
- DevOps Engineer
- UX Designer
- Project Manager
- Architect
2. **Project Statuses:**
- NA/Support
- Initial
- Gathering Estimates
- Estimate Pending Approval
- Estimate Rework
- Estimate Approved
- Funded
- Scheduled
- In-Progress
- Ready for Prod
- Done
- On-Hold
- Cancelled
3. **Project Types:**
- Project (billable)
- Support (ongoing ops)
4. **Availability Options:**
- 0 (unavailable/PTO)
- 0.5 (half day)
- 1.0 (full day)
5. **Report Filters:**
- Date range (from/to)
- Team member
- Role/Team
- Project
- Project status
- Project type
---
**Document Control:**
- **Owner:** Santhosh J
- **Approver:** Santhosh J
- **Next Review:** Post-MVP completion
- **Change History:**
- v1.0 (2026-02-17): Initial charter approved
---
*End of Project Charter*