Getting Started with HRMS

This guide will help you set up the HRMS development environment and get the system running locally.

Prerequisites

Before you begin, ensure you have the following installed:

Quick Start Path

Follow these phases in order to get a working HRMS system:

After Phase 01, you'll have a working HRMS with:

• Multi-tenant database with RLS
• Google SSO authentication
• SystemRole-based access control
• Protected API endpoints
• Basic dashboard

Google OAuth Setup

Step 1: Create Google Cloud Project

1. Go to Google Cloud Console
2. Create a new project named "HRMS Dev"
3. Select the project from the dropdown

Step 2: Configure OAuth Consent Screen

1. Go to APIs & Services → OAuth consent screen
2. Select External user type
3. Fill in required fields:
   • App name: HRMS Dev
   • User support email: Your email
   • Developer contact: Your email
4. Skip scopes (defaults are fine)
5. Add your email as a test user
6. Save and continue

Step 3: Create OAuth Credentials

1. Go to APIs & Services → Credentials
2. Click Create Credentials → OAuth client ID
3. Select Web application
4. Name: HRMS Web Client
5. Add Authorized redirect URI:

   http://localhost:3000/api/auth/callback/google

6. Click Create
7. Copy the Client ID and Client Secret

Step 4: Configure Environment

Create apps/web/.env.local:

# Generate with: npx auth secret
AUTH_SECRET="your-generated-secret-here"

# From Google Cloud Console
GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="your-client-secret"

Generate AUTH_SECRET:

cd apps/web && npx auth secret

Environment Variables Reference

For the complete list of environment variables, see:

• Bootstrap Artifacts - Full .env.example template

Minimum Required Variables

Verification Checklist

After completing Phase 00 and Phase 01, verify:

# Services running
docker compose ps              # PostgreSQL healthy
curl http://localhost:3000     # Next.js serving
curl http://localhost:3001/health  # NestJS connected to DB

# Authentication working
# 1. Go to http://localhost:3000/login
# 2. Sign in with Google
# 3. Should redirect to /dashboard
# 4. Dashboard shows tenantId and systemRole

What's Next?

After Phase 01, continue with:

See Implementation Plan for full roadmap.

Working with AI Assistants

This project is designed for AI-assisted development using Cursor or Claude Code.

Essential Guides

Quick Start for AI Development

1. One-time setup: Copy state file templates to your code repo
2. Each session: AI reads PROJECT_STATE.md + WHAT_EXISTS.md
3. Before coding: AI states understanding, you approve
4. During work: 30-minute checkpoints to prevent drift
5. End session: AI updates state files, you commit

See the AI Session Guide for detailed prompts and workflows.

Troubleshooting

Having issues? See the Troubleshooting Guide for common problems and solutions.

Deployment

Ready to deploy? See the Deployment Guide:

Live Example: https://docs.hrms.bluewoo.com

Additional Resources

• Technology Stack - Version constraints and packages
• Architecture Principles - Design decisions
• AI Coding Agents Guide - For AI-assisted development
• Live State Tracking - Session management for AI coding
• Deployment - Production infrastructure setup