Bluewoo HRMS - Initial Boilerplate Definition

Version: 1.0
Date: 2025-11-23
Status: ✅ Approved (DO NOT CHANGE without ADR)
Context: Solo Developer + AI (Claude Code & Cursor)

Core Technologies (FIXED - No Changes)

These technologies are locked and cannot be changed without an Architecture Decision Record (ADR):

• Node.js 20.x LTS
• TypeScript 5.7.x
• Next.js 15.x
• NestJS 10.x
• Prisma 5.x
• PostgreSQL 17.x
• Express 4.x
• Auth.js 5.x
• Tailwind CSS 3.4
• Zod 3.x

Initial Boilerplate (Month 1-2)

Included ✅

• ✅ Authentication (Auth.js + Prisma)

  • Email/password authentication
  • JWT token generation
  • Multi-tenant auth isolation
  • Platform admin support

• ✅ Database (Prisma + PostgreSQL)

  • Prisma schema with multi-tenant models
  • Migration system
  • Seed data scripts
  • Connection pooling via Prisma

• ✅ API (NestJS REST)

  • REST API with /api/v1/ prefix
  • Controller → Repository pattern (skip Service for simple CRUD)
  • DTOs with class-validator
  • Standardized error responses

• ✅ Frontend (Next.js + Tailwind)

  • Next.js 15 App Router
  • Tailwind CSS 3.4
  • TypeScript strict mode
  • Basic component structure

• ✅ Multi-tenancy (tenantId isolation)

  • Tenant isolation at repository layer
  • Tenant guards and decorators
  • Data isolation verification

• ✅ Basic error handling

  • Standardized error responses
  • Error logging
  • Error boundaries in frontend

• ✅ Basic logging

  • Console logging for development
  • Structured logging format
  • Error logging

NOT Included ❌ (Add Later)

• ❌ Redis caching (Add Month 2)

  • Permission caching will use in-memory cache initially
  • Redis added in future-enhancements

• ❌ BullMQ job queue (Optional - Add when needed)

  • Background jobs not needed in initial boilerplate
  • Add when background processing is required (emails, reports, file processing)
  • NOT for event-driven architecture (use direct function calls)

• ❌ Advanced monitoring (Optional - Add Month 6)

  • Basic logging sufficient initially
  • Monitoring added when needed

Development Approach

Configuration

• Dev Mode: Use .env.local files for local development (gitignored)
• Production: Use environment variables in deployment platform (Railway/GCP)
• Config Validation: Use Zod schemas for all configuration
• Secrets: Never commit secrets, use platform secrets management

Code Organization

• Backend: NestJS modules (feature-based structure)
• Frontend: Next.js App Router (route-based structure)
  • Auth Exception: apps/web connects to DB only for Auth.js (NextAuth). All other data access must go through apps/api.
• Shared: Type definitions, utilities
• Pattern: Controller → Prisma directly (skip Service/Repository for simple CRUD)
  • Use Service when: Multiple data source calls, business logic, transactions, external APIs
  • Skip Service when: Simple CRUD operations, single entity operations, no business logic
  • All data access enforces tenant isolation via tenantId filter

Database

• Migrations: Run via Prisma CLI (npx prisma migrate dev)
• Seeds: Separate seed scripts (npx prisma db seed)
• Connection: Connection pooling via Prisma (no custom pooling)
• Schema: Code-first approach with Prisma

API

• Versioning: /api/v1/ prefix for all endpoints
• Errors: Standardized error responses with error codes
• Validation: DTOs with class-validator decorators
• Authentication: JWT tokens in HTTP-only cookies

Frontend

• Rendering: SSR for most pages, SSG for static content
• State: React Context for auth state (no external state management initially)
• Styling: Tailwind CSS only (no component library initially)
• Forms: react-hook-form with Zod validation

Technology Addition Rules

Rule 1: No Mid-Development Additions

• ❌ Cannot add new major technology while building a feature
• ✅ Must complete current building block first
• ✅ Create ADR for technology addition
• ✅ Add as separate building block

Rule 2: Planned Technology Additions

• Month 2: Redis caching
• Month 4: BullMQ + Event-driven architecture
• Month 6: Advanced monitoring (separate building block)

Rule 3: Technology Addition Process

When adding a planned technology:

1. Create ADR explaining why the technology is needed
2. Define new building block with full specification
3. Complete through all gates (Build → Test → Review → Document → Commit)
4. Update boilerplate definition to include new technology
5. Update .cursorrules and CLAUDE.md with new patterns

Boilerplate Lock Period

Months 1-2: Boilerplate is LOCKED

No changes allowed:

• ❌ No new technologies
• ❌ No architecture changes
• ❌ No major pattern changes

Focus:

• ✅ Core features only
• ✅ Follow established patterns
• ✅ Complete building blocks sequentially

After Month 2: Can Add Planned Technologies

Allowed changes:

• ✅ Add Redis caching (Month 2)
• ✅ Add BullMQ + Events (Month 4)
• ✅ Add monitoring (Month 6)

Requirements:

• Must follow technology addition process
• Must create ADR
• Must update documentation
• Must complete as separate building block

Architecture Decisions Made

All architecture decisions are documented in ADRs. Key decisions:

• Configuration: .env.local for dev, platform env vars for production
• Database: Prisma 5.x with PostgreSQL 17.x
• API: REST only, no GraphQL
• Auth: Auth.js 5.x with JWT tokens
• Frontend: Next.js 15 App Router
• Styling: Tailwind CSS 3.4

See docs/architecture/decisions/ for complete ADR list. Use the ADR Guide to create new ones.

Success Criteria

The boilerplate is considered complete when:

• ✅ All core technologies integrated
• ✅ Authentication working end-to-end
• ✅ Database migrations working
• ✅ API endpoints responding
• ✅ Frontend rendering pages
• ✅ Multi-tenancy isolation verified
• ✅ All tests passing
• ✅ Documentation complete

Next Steps

1. Complete Phases 00-01 (Foundation) using this boilerplate
2. After Month 2, add Redis caching
3. After Month 4, add BullMQ + Events
4. Continue adding features following phase pattern