Feature Phases: CORE vs ADD-ON

This document separates features into CORE (must-have for MVP) and ADD-ON (value-add features for later). The approach enables incremental delivery of working code while maintaining the enterprise architecture vision.

Note: Features are implemented as sequential phases. See Implementation Plan for phase structure.

Philosophy: Scalable Foundations, Incremental Delivery

Key Principle: Build scalable foundations from day one, but deliver features incrementally in working stages.

• ✅ Complete vertical slices: Each feature delivers fully working code (UI + Backend + Database)
• ✅ Scalable patterns from start: Multi-tenancy for product needs, simple RBAC for MVP
• ✅ No rewrites: Architecture supports future features without major refactoring
• ✅ Always deployable: Every feature results in production-ready code
• ✅ Add complexity when needed: Redis, BullMQ, advanced RBAC added when usage justifies

CORE Features (Months 1-4)

These are the must-have features that define an HRMS. Focus is on correctness, security, and AI-powered search as differentiator.

Note: All features are implemented as sequential phases. See Implementation Plan for phase structure.

1.1 Employee Management ✅ CORE

What: Complete employee lifecycle management

Features:

• Employee profiles (personal info, job details, contact)
• Organizational structure (departments, teams)
• Manager-employee relationships
• Basic org chart visualization
• Employee status (active, on leave, terminated)

Why CORE:

• Fundamental to any HRMS
• Required for all other features (time-off, documents, etc.)
• Multi-tenant isolation must work here first

Database:

• Employee, Department, Team tables
• Tenant isolation enforced via repository layer

1.2 Time-Off Tracking ✅ CORE

What: Leave request and approval system

Features:

• Leave requests (vacation, sick, personal)
• Approval workflow (employee → manager → approved/rejected)
• Balance management and accruals
• Calendar view of time-off
• Policy enforcement (min/max days, blackout dates)

Why CORE:

• Standard HRMS requirement
• Demonstrates approval workflows (reusable pattern)
• Tests RBAC system (who can approve?)

Database:

• Leave, LeaveBalance, LeavePolicy tables
• Status workflow: PENDING → APPROVED/REJECTED

1.3 Document Management + AI Search ✅ CORE

What: Upload HR documents with AI-powered search via RAG

Features:

• Upload documents (PDFs, Word docs)
• Store in Google Cloud Storage
• Access control (company-wide, team-only, private)
• AI-powered semantic search
• RAG embeddings in MongoDB

Why CORE:

• Key differentiator: AI-native search from day one
• Proves dual database architecture (PostgreSQL + MongoDB)
• Tests AI Service integration
• Practical value: "What's our parental leave policy?"

Database:

• PostgreSQL: Document table (metadata)
• MongoDB: rag_chunks collection (embeddings)

Simplified Design:

• ✅ 2 MongoDB collections (was 3)
• ✅ 3 visibility levels (was 6): private, team, company
• ❌ No hybrid search (vector-only is fine)
• ❌ No re-ranking (future optimization)

1.4 Authentication & Multi-Tenancy ✅ CORE

What: Secure login and tenant isolation

Features:

• Email/password authentication (Auth.js)
• Multi-tenant data isolation
• 3-level authorization:
  • Platform Admin (system-wide)
  • Tenant Admin (org-wide)
  • Tenant User (role-based)
• Basic RBAC with 3 roles: Admin, Manager, Employee

Why CORE:

• Security foundation for everything
• Multi-tenancy must work from day one
• RBAC structure enables ADD-ON features

Database:

• 7 auth tables (User, Tenant, UserTenant, Role, Permission, UserRole, RolePermission)
• Permission caching in Redis (TTL-based, added post-MVP)

1.5 Design System Setup ✅ CORE

What: Establish UI foundation before business entity development

Features:

• Complete design system documentation
• Configuration file specifications (Tailwind, CSS, shadcn)
• Component patterns (stats cards, content cards, buttons)
• AI governance rules to prevent UI drift
• Validation checklists

Why CORE:

• Without it, every AI agent makes different UI decisions
• Prevents "wireframe look" with plain white cards
• Ensures consistent dark mode support
• Source of truth for all future UI development

Deliverables:

• /docs/18-design-system/ documentation
• Phase 01.5 implementation guide
• AI agent UI constraints

1.6 Basic Analytics Dashboard ✅ CORE

What: Simple metrics for tenant admins

Features:

• Headcount (total, active, on leave)
• Pending approvals count
• Recent activity (employees added, leaves requested)
• Department breakdown

Why CORE:

• Validates dashboard quickly
• Shows data aggregation patterns
• Tests caching strategy

Database:

• Aggregation queries on existing tables
• Cache dashboard stats (5-min TTL)

1.7 Platform Admin ✅ CORE

What: Platform Admin tenant management for SaaS operators

Features:

• Platform Admin dashboard UI
• Tenant CRUD API (/api/v1/admin/tenants)
• Direct Tenant Admin assignment
• Tenant status management (TRIAL/ACTIVE/SUSPENDED)

Why CORE:

• Required for B2B SaaS operation
• Enables manual tenant provisioning
• Supports enterprise sales model

Database:

• Existing Tenant, User tables
• @PlatformAdminOnly() guard for SYSTEM_ADMIN role

Deliverables:

• Platform Admin guard and controller
• /admin/tenants UI pages
• Assign admin flow

---

ADD-ON Features (Months 5-6)

These features add significant value but aren't required for basic HRMS functionality. They're strategic differentiators but more complex to build.

2.1 Team Communication Feed 🎯 ADD-ON

What: Instagram-style social feed for company communication

Features:

• Posts (text + images)
• Likes and comments
• Company/department/team visibility
• AI-generated post summaries
• @mentions and notifications

Why ADD-ON:

• Not core HR functionality
• Competes with Slack/Teams - risky
• Significant complexity (media uploads, notifications, comment threads)
• High engagement potential but not essential

Database:

• TeamPost, PostLike, PostComment tables
• Media storage in Google Cloud Storage
• Denormalized counters (with transactions)

Simplified Design:

• ✅ Text posts + images only
• ✅ Flat comments (no nested threads)
• ✅ Simple AI summaries
• ❌ No video/voice posts (future)
• ❌ No complex notification system

2.2 Goals / OKR Tracking 🎯 ADD-ON

What: Basic goal tracking with AI suggestions

Features:

• Create goals (personal, team, company)
• Progress tracking (0-100%)
• Optional key results
• AI goal suggestions based on role
• Manager review of team goals

Why ADD-ON:

• Not essential for HRMS
• Competes with dedicated OKR tools (Lattice, 15Five)
• AI suggestions require understanding industry benchmarks
• Can be simplified to plain text "notes" field

Database:

• Goal, KeyResult tables
• Status tracking

Simplified Design:

• ✅ Basic goal CRUD
• ✅ Simple progress bar
• ✅ AI suggestions (based on job title only)
• ❌ No alignment/cascading goals
• ❌ No performance review integration

2.3 Advanced RBAC Permissions 🎯 ADD-ON

What: Granular resource:action:scope permissions

Features:

• Custom role creation
• Permission assignment (employees:read:team, leaves:approve:department)
• Scope-based filtering (own, team, department, company)

Why ADD-ON:

• CORE features use 3 fixed roles (Admin, Manager, Employee)
• Most 100-employee companies don't need custom roles
• Adds UI complexity (role builder)

Implementation:

• Backend already supports this (built in foundation)
• Just needs frontend UI for role management

Future Features

These are long-term enhancements that require CORE and ADD-ON foundation:

3.1 Advanced Features

• Performance reviews and 1-on-1s
• Compensation management
• Learning & development
• Recruiting integration
• Advanced analytics and reporting

3.2 AI Enhancements

• AI workflow suggestions ("You should approve this leave")
• Predictive analytics ("High turnover risk in Engineering")
• AI-generated performance reviews
• Document question answering with citations

3.3 Infrastructure

• Video/voice posts in team feed
• Nested comment threads
• Hybrid search (vector + text)
• Advanced caching (pattern-based, version-based invalidation)
• High Availability (HA) setup
• Multi-region deployment

Decision Matrix: CORE vs ADD-ON

Timeline Summary

Note: Phases are executed sequentially. See Implementation Plan for complete details.

Key Takeaways

1. CORE features define the MVP: Employee management, time-off, documents with AI search
2. ADD-ON features are differentiators: Team feed and OKR tracking add value but aren't essential
3. Always working code: Each feature delivers production-ready code
4. Enterprise architecture from day one: Multi-tenancy, RBAC, dual DB built correctly in foundation
5. No rewrites: Architecture supports future features without major refactoring

Next: See Implementation Plan for phase structure and timeline.