Documentation Index
Fetch the complete documentation index at: https://grantmaster.dev/llms.txt
Use this file to discover all available pages before exploring further.
Engineering reference: For service contracts, EventBus events, and data-layer details see src/features/users/users.md.
last_updated: 2026-02-22
HR & Users Subsystems
| Status | Updated | Covered Files |
|---|
| 🟢 Stable | 2026-02-22 | src/features/users/, src/features/users/contracts.ts, src/shared/auth/contracts.ts |
Overview
The Users feature is the largest feature module in GrantMaster, providing comprehensive human-resource management capabilities beyond basic user authentication. It manages the full employee lifecycle — from onboarding and role assignment through capacity planning, cost allocation, time-off tracking, training, and offboarding.
Collection gotcha: The Firestore collection is named employees but stores User documents. See src/core/firestoreCollections.ts.
Service Layer (16+ Services)
| Service | Responsibility |
|---|
UserService | Core CRUD — create, update, deactivate, search users |
UserPreferencesService | Theme, locale, notification, dashboard preferences |
UserDocumentsService | Upload/manage personal documents (contracts, IDs, certs) |
ContactService | Emergency contacts and external contact records |
CostAllocationService | Allocate employee cost across grants/projects by percentage |
EffortCertificationService | Generate and sign quarterly effort certifications (OMB Uniform Guidance) |
PayrollExportService | Export payroll data in CSV/Excel for external payroll systems |
StaffAllocationService | Assign staff to projects with FTE percentages and date ranges |
TrainingService | Training records, certifications, expiry tracking |
VolunteerService | Volunteer profiles, hours, and contribution tracking |
OrgChartService | Organizational hierarchy, reporting structure, and vacancy management |
ContractorService | Independent contractor profiles, contract lifecycle, and payment tracking |
UserDocumentsService | Personal document vault with compliance and expiry tracking |
timeOffService | Leave requests, balances, approval workflows |
teamMemberRequests | Staff requisition and onboarding requests |
userManagement | Bulk operations — invite, deactivate, role changes |
Selector Hooks (11)
All hooks are exported from UserContext and provide optimized, memoized access to user data:
| Hook | Returns |
|---|
useUser(id) | Single user by ID |
useUsers() | Full user context (list, loading, current user) |
useActiveUsers() | Only active (non-deactivated) users |
useCurrentUser() | Currently authenticated user’s profile |
useUsersByRole(role) | Users filtered by project role |
useUsersBySystemRole(role) | Users filtered by system role (Admin, Manager, etc.) |
useUsersByStatus(status) | Users by employment status |
useUsersByManager(managerId) | Direct reports for a manager |
useUserByEmail(email) | Lookup by email address |
useUsersByIds(ids) | Batch lookup by ID array |
useInvitedUsers() | Users in invited status (pending onboarding) |
Component Library (32+ Components)
Core Views
| Component | Description |
|---|
Users | Main user list with filters, search, and bulk actions |
UserDetail | Full user profile with tabbed sections |
UserProfile | Read-only public profile card |
UserPreferences | Settings page (theme, notifications, locale) |
UserFilters | Filter bar (role, status, department, manager) |
UserToolbar | Action toolbar (invite, export, bulk operations) |
Modals
| Component | Description |
|---|
InviteUserModal | Send invitation emails with role pre-assignment |
DeactivateUserModal | Offboarding confirmation with data retention options |
UserDetailsModal | Quick-view user details overlay |
UserProfileModal | Edit profile modal |
Subsystem Dashboards
| Component | Description |
|---|
StaffAssignmentPlanner | Drag-and-drop staff-to-project allocation |
StaffingOverview | Organization-wide staffing summary |
EffortCertificationDashboard | Quarterly effort cert generation and signing |
VolunteerManagement | Volunteer onboarding, hours, recognition |
TrainingDashboard | Training records, compliance, expiry alerts |
UserDocumentsDashboard | Personal document vault (contracts, IDs) |
OrgChartDashboard | Interactive organizational hierarchy (Tree, Matrix, and List views) |
ContractorsDashboard | Contractor profiles, contract management, and compliance |
UserDocumentsDashboard | Personal document vault with compliance status and alerts |
CapacityDashboard | Team capacity planning and FTE forecasting |
Subsystem Details
Cost Allocation
Distribute employee salary/fringe costs across multiple grants and projects:
interface CostAllocation {
employeeId: string;
allocations: {
grantId: string;
projectId?: string;
percentage: number; // Must sum to 100%
effectiveDate: string;
endDate?: string;
}[];
}
Effort Certification
Complies with OMB Uniform Guidance (2 CFR 200) requirements:
- System generates quarterly certification from journal (journal) data
- Employee reviews and electronically signs
- Supervisor countersigns
- Certification stored as auditable record
Staff Allocation
Allocation percentages are date-bounded and must not exceed 100% FTE at any point.
Time-Off Management
| Feature | Description |
|---|
| Leave balances | Accrue PTO, sick, personal days per policy |
| Request workflow | Employee requests → Manager approves/rejects |
| Calendar view | Team-wide leave calendar overlay |
| Carryover rules | Configurable year-end carryover limits |
Org-Chart & Vacancy Management
The Org-Chart system provides three distinct views for visualizing the organization:
- Tree View: Traditional hierarchical layout.
- Matrix View: Visualizes reporting lines and cross-functional teams.
- List View: Searchable, flat list for quick lookups.
Vacancy Management: Admins can mark positions as vacant and initiate the staff requisition workflow directly from the Org-Chart.
Contractor Management
Comprehensive tracking for independent contractors:
- Contract Lifecycle: Draft, Active, Expiring, and Terminated states.
- Compliance: Automatic tracking of mandatory documents (Insurance, NDAs, Licenses) with expiry alerts.
- Payment Metrics: Integrated view of contract value vs. payments made.
Key Files Reference
| File | Purpose |
|---|
src/features/users/index.ts | Barrel export — services, hooks, components |
src/features/users/UserContext.tsx | React context with 11 selector hooks |
src/features/users/services/UserService.ts | Core user CRUD |
src/features/users/services/CostAllocationService.ts | Grant cost allocation |
src/features/users/services/EffortCertificationService.ts | OMB effort certs |
src/features/users/services/StaffAllocationService.ts | Project staffing |
src/features/users/services/CapacityService.ts | Team capacity planning |
src/features/users/services/timeOffService.ts | Leave request management |
src/features/users/contracts.ts | User/Employee type definitions |
