AI Development GuideFoundations
Technology Stack
Locked technology stack for HRMS - do not deviate
Technology Stack (LOCKED)
This technology stack is finalized. AI agents must not suggest alternatives or upgrades without an approved ADR.
Backend
Framework: NestJS 10.x
Runtime: Node.js 20+ (LTS)
ORM: Prisma 5.x (Stable)
Database: PostgreSQL 17.x
Cache: Redis 7.x (Phase 2)
Auth: Auth.js (NextAuth v5) with Google SSO
AI Vectors: MongoDB Atlas (AI service only)Version Requirements
| Package | Version | Notes |
|---|---|---|
| NestJS | 10.x | Stable, well-documented |
| Prisma | 5.x | Stable and battle-tested |
| Express | 4.x | NOT 5.x (beta) |
| Node.js | 20+ LTS | Current LTS version |
| PostgreSQL | 17.x | Latest stable |
| Redis | 7.x | For caching (Phase 2) |
Frontend
Framework: Next.js 15.x (App Router)
UI: Shadcn/ui + Tailwind CSS 3.4
State: React Query (TanStack Query v5)
Forms: React Hook Form + Zod
Org Chart: React FlowVersion Requirements
| Package | Version | Notes |
|---|---|---|
| Next.js | 15.x | App Router required |
| React | 19.x | Latest stable |
| Tailwind CSS | 3.4 | Latest stable |
| TanStack Query | v5 | For server state |
| Zod | 3.x | For validation |
Infrastructure
Cloud: Google Cloud Platform
Container: Docker + Cloud Run
CI/CD: GitHub Actions
Monitoring: Google Cloud Operations
Storage: Google Cloud StorageForbidden Technologies
These are explicitly NOT allowed:
| Technology | Reason |
|---|---|
| GraphQL | Too complex for our scale |
| Redux/MobX | Use React Query instead |
| Microservices | Monolith is simpler |
| Event Sourcing | No customers to validate |
| Custom ORMs | Prisma is sufficient |
| Alternative DBs | PostgreSQL only |
Package Installation
When installing packages, use exact versions:
# Backend packages
npm install @nestjs/core@10.x @nestjs/common@10.x
npm install prisma@5.x @prisma/client@5.x
npm install zod@3.x
# Frontend packages
npm install next@15.x react@19.x react-dom@19.x
npm install tailwindcss@3.4
npm install @tanstack/react-query@5.xEnvironment Variables
Required environment variables:
# Database
DATABASE_URL=postgresql://user:pass@host:5432/hrms
# Auth
NEXTAUTH_URL=https://app.example.com
NEXTAUTH_SECRET=your-secret-key
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
# AI Service
AI_SERVICE_URL=http://localhost:3001
OPENAI_API_KEY=your-openai-key
MONGODB_URI=mongodb+srv://...
# Storage
GCS_BUCKET=hrms-documents
GCS_PROJECT_ID=your-project-idAdding New Technologies
To add a new technology:
- Create an ADR explaining why it's needed
- Get approval from project lead
- Update this document
- Update boilerplate definition
- Communicate to team
Without an approved ADR, new technologies are forbidden.