Documentation Map

This guide helps you navigate the HRMS documentation efficiently. Not everything needs to be read upfront - most docs are reference material you'll consult when needed.

Quick Decision: Which Doc Do I Need?

┌─────────────────────────────────────────────────────────────┐
│                    WHAT ARE YOU DOING?                       │
└─────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
   First time?          Starting a            Need specific
   Never read docs?     dev session?          information?
        │                     │                     │
        ▼                     ▼                     ▼
   ┌─────────┐         ┌─────────────┐       ┌──────────────┐
   │ READ:   │         │ READ:       │       │ SEARCH:      │
   │ 01-03   │         │ State files │       │ 04-14 for    │
   │ + this  │         │ + Phase XX  │       │ architecture │
   │ guide   │         │ spec        │       │ details      │
   └─────────┘         └─────────────┘       └──────────────┘

Documentation Categories

Category 1: One-Time Read (Before Starting)

Read these once to understand the project. Don't need to memorize - just absorb the vision.

Section	What It Covers	Time
01-Product Vision	What we're building and why	15 min
02-Tech Stack	Locked technologies and versions	10 min
03-Domain Model	Core concepts (Tenant, Employee, Org)	10 min

Total: ~35 minutes one-time investment

Category 2: Reference Only (When Needed)

These are detailed architecture docs. Don't read upfront - consult when:

AI asks a specific question
You need implementation details
Something isn't working

Section	When to Reference
04-Database	Schema questions, RLS policies
05-API Design	REST conventions, response formats
06-Backend Architecture	NestJS structure, modules
07-Frontend Architecture	Next.js patterns, components
08-Multi-Tenancy	Tenant isolation, RLS details
09-Authentication	Auth.js setup, session handling
10-AI Service	RAG, embeddings, AI tools
11-Development Standards	Code style, naming conventions
12-Testing	Test patterns, coverage requirements
13-Deployment	CI/CD, environments
14-Extension Guide	Adding new features

Category 3: Active Use (Every Session)

These are your working documents. Use them every development session.

Section	Purpose	When
15-Implementation Plan	Phase specs, step-by-step guides	Start of each phase
16-AI Coding Agents	Patterns, constraints, workflow	Every session
19-Live State Tracking	State file templates, rituals	Session start/end
20-Getting Started	Setup, troubleshooting	When stuck

Category 4: UI Development Context

Provide these to AI when building frontend/UI features.

Section	Purpose	When
17-UI Screenshots	Visual reference for each page	UI implementation
18-Design System	Components, tokens, patterns	Any frontend work

What to Give to AI (Context Loading)

Context Limits

AI tools have context limits. Don't upload everything - be selective.

Always Provide (Every Session)

These files live in your CODE repository (not docs):

hrms/
├── PROJECT_STATE.md    ← Current progress
├── WHAT_EXISTS.md      ← What's built
└── CLAUDE.md           ← AI instructions (auto-loaded by Claude)

Provide Per Phase

Phase	Required Docs	Optional
00: Empty Shell	`phase-00-empty-shell.mdx`, `boilerplate-definition.mdx`	`technology-stack.mdx`
01: Auth	`phase-01-multi-tenant-auth.mdx`, `patterns.mdx`	`database-schema.mdx`
01.5: Design	`phase-01.5-design-system.mdx`, `18-design-system/*`	`17-ui-screenshots/*`
02: Employee	`phase-02-employee-entity.mdx`, `patterns.mdx`, `service-patterns.mdx`	`employee.mdx` (reference)
03: Org Structure	`phase-03-org-structure.mdx`, `patterns.mdx`, `service-patterns.mdx`	`domain-models.mdx`
04: Org Viz	`phase-04-org-visualization.mdx`, `18-design-system/*`	`17-ui-screenshots/*`
05: Time Off	`phase-05-time-off.mdx`, `patterns.mdx`	-
06: Documents	`phase-06-document-management.mdx`, `patterns.mdx`	`documents.mdx` (reference)
07: Tags	`phase-07-tags-custom-fields.mdx`, `patterns.mdx`	`custom-fields.mdx`
08: Dashboard	`phase-08-dashboard.mdx`, `dashboard-system.mdx`	`17-ui-screenshots/*`
09: AI	`phase-09-ai-integration.mdx`, `ai-integration.mdx`	`10-ai-service/*`

Section-by-Section Guide

15-Implementation Plan (Your Roadmap)

15-implementation-plan/
├── index.mdx                 ← Overview and current status
├── boilerplate-definition.mdx ← What's in the starter template
├── building-blocks/
│   ├── phase-00-*.mdx        ← Empty shell setup
│   ├── phase-01-*.mdx        ← Auth + multi-tenancy
│   ├── phase-01.5-*.mdx      ← Design system
│   ├── phase-02-*.mdx        ← Employee CRUD
│   ├── ...                   ← Phases 03-09
│   └── use-cases/            ← User stories reference

How to use: Read the phase spec BEFORE starting that phase. Each phase has:

Prerequisites (what must be done first)
Steps with gates (verification criteria)
Completion checklist

16-AI Coding Agents (AI Instructions)

16-ai-coding-agents/
├── index.mdx                 ← Overview + CLAUDE.md template
├── foundations/              ← Architecture, schema, models
├── development/
│   ├── patterns.mdx          ← Code patterns to copy EXACTLY
│   ├── constraints.mdx       ← NEVER violate these
│   ├── workflow.mdx          ← Session rituals
│   └── service-patterns.mdx  ← Service implementation patterns
├── features/                 ← Feature-specific guides
└── references/               ← Entity-specific details

How to use:

Read patterns.mdx at every session start
Copy code patterns exactly (no "improvements")
Check constraints.mdx when unsure if something is allowed

18-Design System (UI Guide)

18-design-system/
├── index.mdx                 ← Overview
├── design-tokens.mdx         ← Colors, spacing, typography
├── components/               ← Button, Card, Form patterns
├── layouts.mdx               ← Page layouts
├── ai-rules.mdx              ← Rules for AI when building UI
└── validation-checklist.mdx  ← Before marking UI complete

How to use: Provide to AI when building any frontend component.

19-Live State Tracking (Session Management)

19-live-state-tracking/
├── index.mdx                 ← Why and how
├── project-state-template.mdx ← Copy to PROJECT_STATE.md
└── what-exists-template.mdx  ← Copy to WHAT_EXISTS.md

How to use:

Copy templates to your code repo root ONCE
Update PROJECT_STATE.md after EVERY step
Update WHAT_EXISTS.md after each phase

Quick Reference Card

Before First Session

□ Read 01-03 (one-time, 35 min)
□ Copy templates from 19-live-state-tracking to code repo
□ Set up CLAUDE.md from 16-ai-coding-agents/index.mdx

Starting Any Session

□ AI reads: PROJECT_STATE.md, WHAT_EXISTS.md
□ You provide: Current phase spec
□ AI states understanding, you approve

When Building UI

□ Provide: 18-design-system/* and 17-ui-screenshots/*
□ AI follows: design tokens, component patterns

When Stuck

□ Check: 20-getting-started/troubleshooting.mdx
□ Reference: Relevant 04-14 architecture doc
□ Ask AI: "What does [X] doc say about this?"

Next Steps

Now that you understand the documentation structure:

AI Session Guide - Step-by-step workflow with copy-paste prompts
Troubleshooting - Common issues and solutions

Documentation Map

On this page