Bluewoo HRMS
Live State Tracking

WHAT_EXISTS.md Template

Copy this template to inventory all built components

WHAT_EXISTS.md Template

Copy this template to your code repository root as WHAT_EXISTS.md.

Template

# What Exists - Component Inventory

**Last Updated:** YYYY-MM-DD
**Generated After:** Phase XX completion

---

## Database Models

| Model | Table | Key Fields | Relations | Phase |
|-------|-------|------------|-----------|-------|
| Tenant | tenants | id, name, domain, status | users, employees, departments | 01 |
| User | users | id, email, tenantId, systemRole | tenant, accounts, sessions | 01 |
| Account | accounts | id, userId, provider, providerAccountId | user | 01 |
| Session | sessions | id, sessionToken, userId, expires | user | 01 |
| Employee | employees | id, tenantId, firstName, lastName, email | user, department, teams | 02 |
| Department | departments | id, tenantId, name, parentId | tenant, employees, children | 03 |
| Team | teams | id, tenantId, name | tenant, members | 03 |

[Add models as phases complete...]

---

## API Endpoints

### Tenant Module (Phase 01)

| Method | Endpoint | Description | Guard | Pattern Source |
|--------|----------|-------------|-------|----------------|
| GET | /api/v1/tenant | Get current tenant | TenantGuard | - |
| GET | /api/v1/tenant/settings | Get tenant settings | TenantGuard | - |
| PATCH | /api/v1/tenant/settings | Update settings | TenantGuard, SYSTEM_ADMIN | - |

### Users Module (Phase 01)

| Method | Endpoint | Description | Guard | Pattern Source |
|--------|----------|-------------|-------|----------------|
| GET | /api/v1/users | List users | TenantGuard, HR_ADMIN+ | - |
| GET | /api/v1/users/:id | Get user by ID | TenantGuard | - |
| PATCH | /api/v1/users/:id/status | Update user status | TenantGuard, HR_ADMIN+ | - |
| PATCH | /api/v1/users/:id/role | Assign role | TenantGuard, SYSTEM_ADMIN | - |

### Employee Module (Phase 02)

| Method | Endpoint | Description | Guard | Pattern Source |
|--------|----------|-------------|-------|----------------|
| GET | /api/v1/employees | List employees | TenantGuard | tenant.controller |
| GET | /api/v1/employees/:id | Get employee | TenantGuard | tenant.controller |
| POST | /api/v1/employees | Create employee | TenantGuard, HR_ADMIN+ | tenant.controller |
| PATCH | /api/v1/employees/:id | Update employee | TenantGuard, HR_ADMIN+ | tenant.controller |
| DELETE | /api/v1/employees/:id | Soft delete employee | TenantGuard, HR_ADMIN+ | tenant.controller |

[Add endpoints as phases complete...]

---

## Frontend Routes

| Route | Component | Auth | Role | Phase | Status |
|-------|-----------|------|------|-------|--------|
| /login | LoginPage | No | - | 01 | ✅ |
| /dashboard | DashboardPage | Yes | Any | 01 | ✅ |
| /dashboard/settings | SettingsPage | Yes | SYSTEM_ADMIN | 01 | ✅ |
| /dashboard/employees | EmployeeListPage | Yes | Any | 02 | ✅ |
| /dashboard/employees/:id | EmployeeDetailPage | Yes | Any | 02 | ✅ |
| /dashboard/employees/new | EmployeeCreatePage | Yes | HR_ADMIN+ | 02 | ✅ |
| /dashboard/org | OrgChartPage | Yes | Any | 04 | ⏳ |
| /dashboard/timeoff | TimeOffPage | Yes | Any | 05 | ⏳ |

[Add routes as phases complete...]

---

## Established Patterns (COPY FROM THESE)

<Callout type="warning">
When creating new code, copy EXACTLY from these files. No variations.
</Callout>

### Backend Patterns

| Pattern | Example File | Copy For | Key Elements |
|---------|--------------|----------|--------------|
| Controller | `apps/api/src/tenant/tenant.controller.ts` | New controllers | @Controller, @UseGuards, @Get/@Post |
| Service | `apps/api/src/tenant/tenant.service.ts` | New services | @Injectable, constructor injection |
| Module | `apps/api/src/tenant/tenant.module.ts` | New modules | @Module, providers, controllers |
| DTO | `apps/api/src/users/dto/update-user-status.dto.ts` | New DTOs | class-validator decorators |
| Guard | `apps/api/src/common/guards/tenant.guard.ts` | New guards | @Injectable, CanActivate |
| Decorator | `apps/api/src/common/decorators/tenant.decorator.ts` | New decorators | createParamDecorator |

### Frontend Patterns

| Pattern | Example File | Copy For | Key Elements |
|---------|--------------|----------|--------------|
| Server Page | `apps/web/app/dashboard/page.tsx` | Server pages | async function, data fetching |
| Client Page | `apps/web/app/dashboard/settings/page.tsx` | Client pages | "use client", useState |
| Layout | `apps/web/app/dashboard/layout.tsx` | Layouts | children prop, providers |
| Data Hook | `apps/web/hooks/use-settings.ts` | Data fetching | useQuery, useMutation |
| Form | `apps/web/components/forms/SettingsForm.tsx` | Forms | react-hook-form, zod |
| List Component | `apps/web/components/employees/EmployeeList.tsx` | List views | DataTable, columns |

### API Client Pattern

| Pattern | Example File | Copy For |
|---------|--------------|----------|
| API Function | `apps/web/lib/api/tenant.ts` | New API calls |
| Type Export | `apps/web/lib/api/types.ts` | Shared types |

---

## Guards and Decorators

| Name | Type | Purpose | File |
|------|------|---------|------|
| TenantGuard | Guard | Validates X-Tenant-ID header | `apps/api/src/common/guards/tenant.guard.ts` |
| RoleGuard | Guard | Validates user role | `apps/api/src/common/guards/role.guard.ts` |
| @TenantId() | Decorator | Extracts tenant ID from request | `apps/api/src/common/decorators/tenant.decorator.ts` |
| @CurrentUser() | Decorator | Gets current user from session | `apps/api/src/common/decorators/current-user.decorator.ts` |
| @Roles() | Decorator | Specifies required roles | `apps/api/src/common/decorators/roles.decorator.ts` |

---

## Environment Variables

| Variable | Service | Purpose | Phase | Required |
|----------|---------|---------|-------|----------|
| DATABASE_URL | API, Web | PostgreSQL connection | 00 | Yes |
| AUTH_SECRET | Web | Auth.js session secret | 01 | Yes |
| GOOGLE_CLIENT_ID | Web | Google OAuth | 01 | Yes |
| GOOGLE_CLIENT_SECRET | Web | Google OAuth | 01 | Yes |
| NEXTAUTH_URL | Web | Auth.js callback URL | 01 | Yes |
| API_URL | Web | Backend API URL | 01 | Yes |
| RESEND_API_KEY | API | Email service | 10.5 | Optional |

---

## NPM Packages (Installed)

| Package | Version | Purpose | Phase | Service |
|---------|---------|---------|-------|---------|
| @prisma/client | 6.x | Database ORM | 00 | All |
| prisma | 6.x | CLI and migrations | 00 | Dev |
| next | 15.x | Frontend framework | 00 | Web |
| @nestjs/core | 10.x | Backend framework | 00 | API |
| next-auth | 5.0.0-beta.x | Authentication | 01 | Web |
| @auth/prisma-adapter | 2.x | Auth.js Prisma adapter | 01 | Web |
| class-validator | latest | DTO validation | 01 | API |
| class-transformer | latest | DTO transformation | 01 | API |
| @tanstack/react-query | 5.x | Data fetching | 01 | Web |
| zod | 4.x | Schema validation | 01 | All |
| tailwindcss | 3.x | CSS framework | 01.5 | Web |

---

## File Structure Overview

```
hrms/
├── apps/
│   ├── api/                      # NestJS Backend
│   │   └── src/
│   │       ├── common/           # Shared guards, decorators
│   │       │   ├── guards/       # TenantGuard, RoleGuard
│   │       │   └── decorators/   # @TenantId, @CurrentUser
│   │       ├── tenant/           # Tenant module (Phase 01)
│   │       ├── users/            # Users module (Phase 01)
│   │       ├── employees/        # Employee module (Phase 02)
│   │       └── main.ts
│   └── web/                      # Next.js Frontend
│       ├── app/
│       │   ├── (auth)/           # Auth pages
│       │   ├── (dashboard)/      # Protected pages
│       │   └── api/              # API routes (auth)
│       ├── components/
│       │   ├── ui/               # shadcn components
│       │   └── [feature]/        # Feature components
│       ├── hooks/                # Custom hooks
│       └── lib/
│           ├── api/              # API client functions
│           └── utils/            # Utilities
└── packages/
    └── database/                 # Prisma schema
        └── prisma/
            ├── schema.prisma
            └── migrations/
```

---

## Modules by Phase

### Phase 01 Modules (Auth)
- `TenantModule` - Tenant settings and info
- `UsersModule` - User management
- `AuthModule` - Authentication (Auth.js)

### Phase 02 Modules (Employee)
- `EmployeesModule` - Employee CRUD

### Phase 03 Modules (Org Structure)
- `DepartmentsModule` - Department hierarchy
- `TeamsModule` - Team management

[Add modules as phases complete...]

Update Rules

Update WHAT_EXISTS.md after each phase completion:

  1. Add new database models

    • Include all fields
    • Document relations

  2. Add new API endpoints

    • Include method, path, description, guard
    • Reference pattern source

  3. Add new frontend routes

    • Include component, auth requirement, role

  4. Add new patterns (if first of kind)

    • Only add if this is a new pattern type
    • Include example file path

  5. Add new env variables

    • Only if new ones added

  6. Add new packages

    • Only if new ones installed

Usage: Before Creating New Code

Example: Creating TimeOffController

  1. Check WHAT_EXISTS.md for similar endpoints:

    • Found: EmployeesModule endpoints follow tenant.controller pattern

  2. Check WHAT_EXISTS.md for pattern source:

    • Pattern source: apps/api/src/tenant/tenant.controller.ts

  3. Copy pattern exactly:

    • Same import structure
    • Same decorator usage
    • Same error handling
    • Same response format

  4. Update WHAT_EXISTS.md after phase complete:

    • Add TimeOff endpoints to API Endpoints section
    • Add TimeOffModule to Modules section

PROJECT_STATE.md Template

Copy this template to track project state for AI context

UI Screenshots

Visual reference for the HRMS application interface

On this page

WHAT_EXISTS.md TemplateTemplateUpdate RulesUsage: Before Creating New CodeExample: Creating TimeOffController