155-step implementation guide for HRMS with exact commands, code, and verification gates

HRMS Micro-Step Build Plan

This document defines the complete implementation plan for the HRMS system using a micro-step approach. Each step is designed to be completed in under 60 minutes with clear verification.

Two Repositories

This plan involves TWO separate repositories:

Repository	Purpose	What Happens Here
`hrms-docs`	Documentation	Create phase files with detailed steps
`hrms`	Code	Execute the steps, build the actual HRMS

Workflow Between Repositories

hrms-docs (this repo)              hrms (code repo)
─────────────────────              ─────────────────
                                   
1. Create phase-00.mdx ──────────► 2. Execute Steps 01-08
   (detailed instructions)            (follow instructions exactly)
                                      
3. Update status to ✅  ◄────────── 4. All gates pass
   Delete old building blocks         Commit code changes
                                      
5. Create phase-01.mdx ──────────► 6. Execute Steps 09-24
   ...                                ...

Git & Deployment Workflow

All changes follow the branch protection workflow:

Feature Branch → PR (Preview) → Merge → Staging → [Manual] → Production

See Development Workflow for complete guide.

Commit Messages & Versioning

All commits must use Conventional Commits format:

<type>: <description>

Type	Version Bump	Example
`feat`	Minor (0.X.0)	`feat: add employee dashboard`
`fix`	Patch (0.0.X)	`fix: resolve login timeout`
`docs`	Patch	`docs: update API guide`
`chore`	Patch	`chore: update dependencies`

Versions are auto-bumped on merge to main via semantic-release. Non-conforming commits are rejected by CI.

See Constraints for full details.

Philosophy

Core Principles

One step = One thing that works and can be verified in under 60 minutes
If a step takes more than 60 minutes → stop, something is wrong
If a gate fails → fix it before moving on. No exceptions.
All code uses our documented schema from Database Schema

Step Structure

Every step has exactly four components:

Component	Description
Input	What must exist before starting this step
Task	Exactly what to build (specific files, specific code)
Gate	How to verify it works (specific command, specific output)
Lock	What files become untouchable after this step

Rules

❌ Never skip a gate
❌ Never start the next step until current gate passes
❌ Never modify locked files without following the Correction Protocol
✅ Always fix issues found during gate verification
✅ Always document deviations using the Correction Protocol

Correction Protocol

If during ANY step you discover that our documented approach doesn't work:

Schema model doesn't fit the use case
Library doesn't work as expected
Architecture pattern causes issues
Technology choice is wrong

DO NOT:

Hack around it
Create workarounds
Continue with a broken foundation
Make undocumented changes

INSTEAD, Follow These 6 Steps:

1. STOP

Halt current step immediately
Document what doesn't work and why
Do not write any more code

2. DECIDE

Discuss the correct approach
Consider impact on existing steps
Agree on the new solution
Create ADR (Architecture Decision Record) if significant

3. DOCUMENT FIRST

Update the relevant documentation:
- database-schema.mdx for schema changes
- service-patterns.mdx for pattern changes
- technology-stack.mdx for library changes
- Use case files if behavior changes
Documentation is the source of truth
No code changes until docs are updated

4. VALIDATE PREVIOUS STEPS

Review ALL completed steps (01 → current)
For each step, ask: "Does this change affect this step?"
Mark affected steps for re-execution
Create list of steps to redo

5. REDO AFFECTED STEPS

Re-execute each affected step in order
Update code to match new documentation
Run gate verification again
Update lock list if files changed

6. CONTINUE

Only after all affected steps pass their gates
Resume from the step where issue was discovered
Use the newly documented approach

Correction Log Format

When a correction happens, log it:

## Correction Log

### Correction #1 (Step XX)
- **Issue**: [What didn't work]
- **Root Cause**: [Why it didn't work]
- **Decision**: [What we decided]
- **Docs Updated**: [List of files]
- **Steps Redone**: [List of step numbers]
- **ADR**: [Link if created]
- **Date**: [When]

Important: This Plan Replaces Building Blocks

The 10 phase files will COMPLETELY REPLACE the current 17 building block files.

Why Replace?

Current Building Blocks (17 files)	New Micro-Step Phases (10 files)
Theoretical checklists	Exact commands and code to copy
Vague "implement X" tasks	Step-by-step with verification
No verification gates	Every step has a testable gate
Overlapping content	Sequential, no overlap
Easy to get lost	60-minute max = clear progress
Files can be modified anytime	Locked files prevent regressions

Legacy Files Status

Deleted (replaced by phase files):

✅ 01-database-setup.mdx → phase-00
✅ 02-authentication.mdx → phase-01
✅ 03-rbac-implementation.mdx → phase-01
✅ 04-multi-tenancy.mdx → phase-01
✅ 05-api-foundation.mdx → phase-00, phase-02
✅ 06-frontend-foundation.mdx → phase-00, phase-02
✅ 07-ai-service-setup.mdx → phase-09
✅ 11-employee-management.mdx → phase-02, phase-03
✅ 12-time-off-tracking.mdx → phase-05
✅ 13-document-management.mdx → phase-06
✅ 14-analytics-dashboard.mdx → phase-08

Kept (not covered by phases):

08-deployment.mdx → Separate concern
09-redis-caching.mdx → Future enhancement (Month 2)
10-bullmq-events.mdx → Future enhancement (Month 4)
11-notifications-audit.mdx → Future enhancement (Post-MVP)
15-team-communication.mdx → ADD-ON feature (Month 5)
16-goals-okr.mdx → ADD-ON feature (Month 5-6)
17-advanced-rbac.mdx → ADD-ON feature (Month 6)

How to Use This Plan

Workflow: One Phase at a Time

┌─────────────────────────────────────────────────────────────────┐
│  For each phase (0 → 9):                                        │
│                                                                 │
│  1. CREATE detailed phase file (e.g., phase-00-empty-shell.mdx) │
│     └── Full Input/Task/Gate/Lock for every step                │
│     └── Exact code to copy-paste                                │
│     └── Specific verification commands                          │
│                                                                 │
│  2. EXECUTE in hrms code repository                             │
│     └── Follow each step exactly                                │
│     └── Run gate verification after each step                   │
│     └── Do NOT proceed if gate fails                            │
│                                                                 │
│  3. VERIFY phase completion gate                                │
│     └── All services running                                    │
│     └── All endpoints responding                                │
│                                                                 │
│  4. DELETE old building block files that phase replaces         │
│                                                                 │
│  5. COMMIT and move to next phase                               │
└─────────────────────────────────────────────────────────────────┘

Current Status

Phase	Status	Detailed File	Steps
00	✅ Documented	`phase-00-empty-shell.mdx`	01-08
01	✅ Documented	`phase-01-multi-tenant-auth.mdx`	01-16
01.5	✅ Documented	`phase-01.5-design-system.mdx`	01-08
02	✅ Documented	`phase-02-employee-entity.mdx`	01-18
03	✅ Documented	`phase-03-org-structure.mdx`	01-20
04	✅ Documented	`phase-04-org-visualization.mdx`	01-10
05	✅ Documented	`phase-05-time-off.mdx`	01-20
06	✅ Documented	`phase-06-document-management.mdx`	01-16
07	✅ Documented	`phase-07-tags-custom-fields.mdx`	01-14
08	✅ Documented	`phase-08-dashboard.mdx`	01-16
09	✅ Documented	`phase-09-ai-integration.mdx`	01-17
10	✅ Documented	`phase-10-platform-admin.mdx`	01-10
10.5	✅ Documented	`phase-10.5-pre-launch.mdx`	01-10
11	✅ Documented	`phase-11-production-deployment.mdx`	01-20

Note: Each phase uses its own step numbering (01, 02, 03...). Reference as "Phase 02.3" for Phase 2, Step 3.

Next Action

All phases documented! Ready to execute in hrms code repo.

Execute Phase 00: Begin implementation in hrms code repo.

Phase 0: Empty Shell (Steps 01-08)

Goal: Three applications that start and connect. Nothing works yet except "hello world" level responses.

Completion Gate: All three services running, health endpoint returns JSON with database connection status.

Step	Title	Gate
01	Create monorepo structure	`ls apps/web apps/api packages/database` shows all folders
02	Create Next.js app shell	`npm run dev` shows Next.js default page
03	Create NestJS app shell	`curl localhost:3001` returns "HRMS API Running"
04	Create database package with Prisma	`cat prisma/schema.prisma` shows HealthCheck model
05	Create Docker Compose for PostgreSQL	`docker compose ps` shows hrms-postgres running
06	Connect Prisma to PostgreSQL	`npx prisma studio` opens and shows HealthCheck table
07	Connect API to database	API starts without database connection errors
08	Create health endpoint	`curl localhost:3001/health` returns `{"status":"ok","database":"connected"}`

Locked Files After Phase 0:

package.json (workspaces configuration)
docker-compose.yml
apps/api/nest-cli.json
apps/api/tsconfig.json
apps/api/src/prisma/*
apps/api/src/health/*
packages/database/package.json

Phase 1: Multi-Tenant Auth (Steps 09-24)

Goal: Full authentication with SystemRole-based access control per our documented schema.

Completion Gate: User can login via Google, session contains tenantId and systemRole, API endpoints are protected by tenant and role guards.

Step	Title	Gate
09	Add Tenant model to schema	Prisma studio shows Tenant table with TenantStatus enum
10	Add User model with SystemRole enum	User table with SYSTEM_ADMIN/HR_ADMIN/MANAGER/EMPLOYEE
11	Add Auth.js tables (Account, Session, VerificationToken)	All auth tables exist in database
12	Install Auth.js in Next.js	`npm run dev` starts without errors
13	Configure Auth.js with Google provider	`curl localhost:3000/api/auth/providers` returns JSON
14	Create login page	`/login` shows Google sign-in button
15	Create protected dashboard layout	`/dashboard` redirects to `/login` if not authenticated
16	Add logout functionality	Logout button clears session and redirects
17	Create tenant on first login	New user automatically gets tenant with role=SYSTEM_ADMIN
18	Add tenant and systemRole to session	`session.user.tenantId` and `session.user.systemRole` exist
19	Display tenant info on dashboard	Dashboard shows organization name and user role
20	Add TenantId decorator to API	`@TenantId()` extracts tenant from X-Tenant-ID header
21	Add TenantGuard to API	Requests without X-Tenant-ID header return 400
22	Add SystemRoleGuard to API	Endpoints can require specific roles
23	Create tenant endpoint	`curl -H "X-Tenant-ID: ..." localhost:3001/tenant` returns tenant info
24	Connect frontend to API with tenant header	Dashboard shows "API Status: Connected"

Locked Files After Phase 1:

All Phase 0 locks, plus:
packages/database/prisma/schema.prisma (Tenant, User, Auth.js tables)
apps/web/auth.ts
apps/web/app/api/auth/[...nextauth]/route.ts
apps/web/types/next-auth.d.ts
apps/web/lib/db.ts
apps/web/lib/api.ts
apps/api/src/tenant/*

Phase 2: Employee Entity (Steps 25-42)

Goal: Full Employee CRUD with our documented schema (all enums, soft delete, tenant isolation).

Completion Gate: Complete CRUD operations work via API and frontend, employee data is tenant-isolated.

Step	Title	Gate
25	Add EmploymentType enum	FULL_TIME, PART_TIME, CONTRACT, INTERN in schema
26	Add WorkMode enum	ONSITE, REMOTE, HYBRID in schema
27	Add EmployeeStatus enum	ONBOARDING, ACTIVE, ON_LEAVE, TERMINATED in schema
28	Add Employee model (full schema)	All fields from database-schema.mdx
29	Link User to Employee (optional 1:1)	User.employeeId relation works
30	Run migration	`npm run db:push` succeeds, Employee table exists
31	Create CreateEmployeeDto	class-validator decorators for all required fields
32	Create UpdateEmployeeDto	PartialType with all optional fields
33	Create EmployeeRepository	Tenant-filtered queries with soft delete support
34	Create EmployeeService	CRUD operations with NotFoundException handling
35	Create EmployeeController	GET/POST/PUT/DELETE with TenantGuard
36	Register EmployeeModule	`npm run build` succeeds in API
37	Test Employee CRUD via curl	Create, read, update, delete all return expected responses
38	Create employee list page (frontend)	`/dashboard/employees` shows table with employees
39	Create employee form component	Form with all Employee fields
40	Create new employee page	`/dashboard/employees/new` form submits and creates employee
41	Create edit employee page	`/dashboard/employees/[id]` loads data and updates work
42	Add delete functionality	Soft delete removes employee from list

Locked Files After Phase 2:

All Phase 1 locks, plus:
Employee model in schema.prisma
apps/api/src/employees/*
apps/web/app/dashboard/employees/*

Phase 3: Org Structure (Steps 43-62)

Goal: Flexible organizational relationships per domain model (multi-manager support, teams, departments).

Completion Gate: Employees can have primary manager, dotted-line managers, belong to multiple departments and teams.

Step	Title	Gate
43	Add Department model	With departmentHeadId, parentDepartmentId
44	Add Team model	With teamLeadId
45	Add OrgRole model	Job roles within tenant
46	Add EmployeeOrgRelations model	Primary manager, primary department, primary team
47	Add EmployeeDottedLine model	Secondary reporting relationships
48	Add EmployeeAdditionalManager model	Third-level manager assignments
49	Add EmployeeDepartment junction	Many-to-many with isPrimary flag
50	Add EmployeeTeam junction	Many-to-many with teamRole
51	Add EmployeeRole junction	Many-to-many with assignedAt
52	Run migration for org structure	All junction tables exist
53	Create DepartmentRepository	CRUD with tenant filtering
54	Create DepartmentService	With hierarchy validation (no cycles)
55	Create DepartmentController	GET/POST/PUT/DELETE endpoints
56	Create Team Repository/Service/Controller	Full Team CRUD
57	Create OrgService getDirectReports	Returns employee's direct reports
58	Create OrgService getManagers	Returns all managers (primary + dotted + additional)
59	Create OrgService setManager	With circular reference prevention
60	Create manager assignment endpoint	POST /employees/:id/manager works
61	Create department assignment endpoint	POST /employees/:id/departments works
62	Create team assignment endpoint	POST /employees/:id/teams works

Locked Files After Phase 3:

All Phase 2 locks, plus:
All org models in schema.prisma
apps/api/src/departments/*
apps/api/src/teams/*
apps/api/src/org/*

Phase 4: Org Visualization (Steps 63-72)

Goal: Interactive org chart visualization using React Flow.

Completion Gate: Org chart renders, supports zoom/pan, clicking shows employee details, drag-and-drop reassigns managers.

Step	Title	Gate
63	Install React Flow	Package installed and importable
64	Create org chart data fetcher	API endpoint returns hierarchical org data
65	Create EmployeeNode component	Card renders with name, title, avatar
66	Create OrgChart component	Renders employee tree structure
67	Add org chart to dashboard	`/dashboard/org` displays org chart
68	Add zoom and pan controls	User can navigate large org structures
69	Add click-to-view employee	Clicking node opens employee profile
70	Add drag-to-reassign manager	Dragging employee to new manager updates relationship
71	Add department filter	Can filter org chart by department
72	Add search in org chart	Can find and highlight employee in tree

Locked Files After Phase 4:

All Phase 3 locks, plus:
apps/web/app/dashboard/org/*
apps/web/components/org-chart/*

Phase 5: Time-Off System (Steps 73-92)

Goal: Complete time-off management per domain model (policy → balance → request → approval).

Completion Gate: Employees can request time-off, managers can approve/reject, balances update correctly.

Step	Title	Gate
73	Add TimeOffType enum	VACATION, SICK, PERSONAL, PARENTAL, BEREAVEMENT, etc.
74	Add LeaveType enum	PAID, UNPAID, SPECIAL
75	Add AccrualSchedule enum	ANNUAL, MONTHLY, NONE
76	Add RequestStatus enum	PENDING, APPROVED, REJECTED, CANCELLED
77	Add TimeOffPolicy model	With all fields from schema
78	Add TimeOffBalance model	Per employee per policy per year
79	Add TimeOffRequest model	With approverId, comments, dates
80	Run migration	All time-off tables exist
81	Create TimeOffPolicyRepository	CRUD operations
82	Create TimeOffPolicyService	With validation rules
83	Create TimeOffPolicyController	Admin-only endpoints
84	Create TimeOffBalanceService	Calculate available = total - used - pending
85	Create TimeOffRequestRepository	With status filtering
86	Create TimeOffRequestService	Submit, approve, reject with balance updates
87	Create TimeOffRequestController	Employee and manager endpoints
88	Create time-off request form (frontend)	Select policy, start/end dates
89	Create my requests page	List user's own time-off requests
90	Create pending approvals page	Manager sees team's pending requests
91	Add approve/reject actions	Manager can approve or reject with comments
92	Create leave calendar view	Visual calendar showing team time-off

Locked Files After Phase 5:

All Phase 4 locks, plus:
All time-off models in schema.prisma
apps/api/src/time-off/*
apps/web/app/dashboard/time-off/*

Phase 6: Documents (Steps 93-108)

Goal: Document management with visibility levels and access control per use cases.

Completion Gate: Users can upload documents, set visibility, share with specific users/teams, access control enforced.

Step	Title	Gate
93	Add DocumentCategory enum	POLICY, CONTRACT, PERSONAL, TEMPLATE, etc.
94	Add DocumentVisibility enum	PRIVATE, TEAM, DEPARTMENT, MANAGERS, COMPANY, CUSTOM
95	Add AccessType enum	USER, TEAM, DEPARTMENT, ROLE
96	Add DocumentPermission enum	VIEW, DOWNLOAD, EDIT
97	Add Document model	With all fields from schema
98	Add DocumentAccess model	Fine-grained sharing with expiration
99	Run migration	Document tables exist
100	Setup GCS bucket	Bucket created and accessible from API
101	Create upload service	Uploads files to GCS, returns signed URL
102	Create DocumentRepository	Queries filtered by visibility
103	Create DocumentAccessService	Check canView, canDownload, canEdit
104	Create DocumentService	CRUD + access control enforcement
105	Create DocumentController	Upload, list, share, download endpoints
106	Create document upload page (frontend)	Form with file input, visibility selector
107	Create document list page	Shows documents user can access
108	Create share document modal	Grant access to users/teams/departments

Locked Files After Phase 6:

All Phase 5 locks, plus:
All document models in schema.prisma
apps/api/src/documents/*
apps/web/app/dashboard/documents/*

Phase 7: Tags & Custom Fields (Steps 109-122)

Goal: Flexible categorization and tenant-defined metadata fields.

Completion Gate: Tags can be created, assigned to employees/documents. Custom fields can be defined and values stored.

Step	Title	Gate
109	Add TagCategory model	With assetTypes array (employee, document, goal)
110	Add Tag model	With category relation
111	Add TagStatus enum	ACTIVE, ARCHIVED
112	Add TagPermission model	Role-based tag assignment permissions
113	Add EmployeeTag junction	Tag employees with assignedBy
114	Add DocumentTag junction	Tag documents with assignedBy
115	Run migration	Tag tables exist
116	Create TagService	With permission checking
117	Create TagController	CRUD + assign/remove endpoints
118	Add CustomFieldDefinition model	Field schema per entity type
119	Add CustomFieldValue model	Actual values per entity
120	Add FieldType, FieldVisibility enums	TEXT, NUMBER, DROPDOWN, etc.
121	Create CustomFieldService	CRUD definitions + get/set values
122	Add custom fields to employee form	Dynamic fields render based on definitions

Locked Files After Phase 7:

All Phase 6 locks, plus:
All tag/custom field models in schema.prisma
apps/api/src/tags/*
apps/api/src/custom-fields/*

Phase 8: Dashboard System (Steps 123-138)

Goal: Widget-based customizable dashboards per dashboard-system.mdx specification.

Completion Gate: Users can create dashboards, add widgets, drag-and-drop layout, layouts persist.

Step	Title	Gate
123	Add DashboardType enum	SYSTEM, PERSONAL, SHARED
124	Add ShareType, SharePermission enums	USER, TEAM, DEPARTMENT / VIEW, EDIT
125	Add Dashboard model (no relations)	With config JSON column
126	Add DashboardShare model	Sharing configuration
127	Add DashboardLayout model + ALL relations	Relations to Dashboard, User, Tenant
128	Run migration	Dashboard tables exist
129	Create widget registry types	Types + registry class
130	Create DashboardService	CRUD + sharing logic
131	Create DashboardController	`/api/v1/dashboards` endpoints
132	Install react-grid-layout	Package installed
133	Create DashboardContainer component	Main orchestrator + queries
134	Create GridLayout wrapper	Drag-and-drop with responsive breakpoints
135	Create WidgetGallery component	Modal to browse and add widgets
136	Create HeadcountWidget	First real widget + definitions
137	Create layout persistence	Auto-save to localStorage + API
138	Create dashboard page	List + detail pages

Locked Files After Phase 8:

All Phase 7 locks, plus:
All dashboard models in schema.prisma
apps/api/src/dashboards/*
apps/web/features/dashboard/*
apps/web/app/dashboard/dashboards/*
apps/web/lib/queries/dashboards.ts

Phase 9: AI Integration (Steps 139-155)

Goal: AI service with RAG for document search and chat tools.

Completion Gate: AI chat widget works, can search documents, explain org structure, check time-off balance.

Step	Title	Gate
139	Create AI service (separate Express app)	Starts on port 3002
140	Setup MongoDB for AI	Connection works
141	Install LangChain	Package installed
142	Create document chunking service	Splits documents for RAG
143	Create embedding service	Generates embeddings via OpenAI
144	Create vector store service	Stores and queries embeddings
145	Create RAG query endpoint	POST /ai/query returns relevant docs
146	Create chat tools registry	Tool definitions for AI
147	Implement employee_search tool	Find employees by query
148	Implement document_search tool	RAG-powered doc search
149	Implement org_explain tool	Explain org relationships
150	Implement timeoff_balance tool	Get user's time-off balance
151	Create chat endpoint	POST /ai/chat with tool use
152	Create AI chat widget (frontend)	Floating chat button
153	Create chat message components	User and assistant messages
154	Create tool result renderers	Info cards, confirmation cards
155	Integrate chat with dashboard	Chat available on all dashboard pages

Locked Files After Phase 9:

All Phase 8 locks, plus:
apps/ai/*
apps/web/features/ai-chat/*

Summary

Phase	Steps	Features	Est. Time
00	8	Monorepo, Next.js, NestJS, Prisma, Docker	4-6 hours
01	16	Auth, Tenant, SystemRole, Guards	8-12 hours
01.5	8	Design System Setup	6-8 hours
02	18	Employee CRUD (full schema)	8-12 hours
03	20	Org structure (multi-manager)	10-14 hours
04	10	Org chart (React Flow)	5-8 hours
05	20	Time-off (policy/balance/request)	10-14 hours
06	16	Documents (visibility/access)	8-12 hours
07	14	Tags + Custom Fields	7-10 hours
08	16	Dashboard (widget system)	8-12 hours
09	17	AI (RAG/chat)	10-14 hours
10	10	Platform Admin	12-14 hours
10.5	10	Pre-Launch (email, onboarding)	17-24 hours
11	20	Production Deployment (GCP)	12-16 hours
TOTAL	~203	Complete HRMS + Deployment	~127-176 hours

✅ Phase 00: phase-00-empty-shell.mdx ✅ Phase 01: phase-01-multi-tenant-auth.mdx ✅ Phase 01.5: phase-01.5-design-system.mdx ✅ Phase 02: phase-02-employee-entity.mdx ✅ Phase 03: phase-03-org-structure.mdx ✅ Phase 04: phase-04-org-visualization.mdx ✅ Phase 05: phase-05-time-off.mdx ✅ Phase 06: phase-06-document-management.mdx ✅ Phase 07: phase-07-tags-custom-fields.mdx ✅ Phase 08: phase-08-dashboard.mdx ✅ Phase 09: phase-09-ai-integration.mdx ✅ Phase 10: phase-10-platform-admin.mdx ✅ Phase 10.5: phase-10.5-pre-launch.mdx ✅ Phase 11: phase-11-production-deployment.mdx

All phases documented. Ready for implementation.

Next (Code - hrms repo)

Execute Phases 00-10.5 in the hrms code repository
- Follow each step exactly
- Run gate after each step
- Do NOT proceed if gate fails

Database Schema - Complete Prisma models
Service Patterns - OrgService implementation
Dashboard System - Widget architecture
Use Cases - Feature requirements
Boilerplate Definition - Tech stack rules

Micro-Step Build Plan

On this page