Development Standards

Core Philosophy

Build enterprise architecture from day one, deliver features incrementally.

Complex patterns (RBAC, multi-tenancy, dual DB) prevent costly refactors
Simple features built on top of solid architecture
Each feature follows established patterns

Guiding Principles

Principle	Meaning
Boring > Clever	Use proven tech, not clever solutions
Simple > Optimal	Good enough beats over-optimized
Independent > DRY	Duplicate code over service coupling
Now > Future	Build for current needs, not hypotheticals
Direct > Abstracted	Minimal layers (only for security)
Explicit > Implicit	No magic, clear code paths
One Way	One pattern per problem
Stable Versions	LTS only, no beta/experimental

Documentation Index

ADR Guide - How to create Architecture Decision Records

Code Style

Rule	Convention
Indentation	2 spaces
Quotes	Single quotes
Semicolons	No semicolons
Commas	Trailing commas
Formatting	Prettier
Linting	ESLint

Naming Conventions

Type	Convention	Example
Classes, Interfaces	PascalCase	`EmployeeService`
Variables, Functions	camelCase	`getEmployee`
Constants	UPPER_CASE	`MAX_RETRIES`
Files	kebab-case	`employee-service.ts`

TypeScript Rules

Strict mode enabled (strict: true)
No any types - use proper types or unknown
Explicit return types on all functions
Interfaces for object shapes
Type guards instead of type assertions

Project Structure

hrms/
├── apps/
│   ├── api/        # NestJS API
│   └── web/        # Next.js App
├── packages/
│   ├── database/   # Shared Prisma
│   └── hrms-ai/    # Express AI Service
└── docs/           # Documentation

Complexity Budget

Area	Limit
Services	Max 3 (HRMS, AI, analytics)
Caching	1 layer (Redis), 5-min TTL default
Auth tables	7 tables for multi-tenant RBAC
API endpoints	Max 10 per resource
Abstraction layers	Max 4 (Controller → Service → Repository → Prisma)

Code Review Checklist

Decision Framework

When making technical decisions, ask:

Is it boring (proven tech)? → Go ahead
Is it simple enough? → Go ahead
Does it add coupling? → Duplicate instead
Do we need it now? → If not, skip it
Is it explicit? → No magic allowed
Does it match existing patterns? → Use existing pattern
Is it stable (LTS/released)? → Go ahead

When in doubt: Choose the simpler option.

Git Workflow

Branch Naming

feature/ABC-123-short-description
bugfix/ABC-123-short-description
hotfix/ABC-123-critical-fix
refactor/ABC-123-cleanup
docs/ABC-123-documentation

Commit Messages

Use Conventional Commits:

<type>(<scope>): <subject>

<body>

<footer>

Types:

feat: - New feature
fix: - Bug fix
docs: - Documentation changes
refactor: - Code refactoring (no behavior change)
test: - Adding/updating tests
chore: - Build, CI, dependencies

Examples:

git commit -m "feat(employees): add bulk import API endpoint"
git commit -m "fix(time-off): calculate balance correctly for partial days"
git commit -m "docs(api): add authentication endpoint examples"

Pull Request Process

Create branch from main

git checkout -b feature/ABC-123-description

Make changes following coding standards
Write tests for new functionality

Push and create PR

git push -u origin feature/ABC-123-description

PR Requirements:
- Descriptive title (follows commit message format)
- Description with context and screenshots (if UI)
- Link to issue/ticket
- All CI checks pass
- At least 1 approval from code owner
Squash merge to main
- Keeps history clean
- PR title becomes commit message

Protected Branches

Branch	Rules
`main`	Require PR, 1 approval, CI pass
`staging`	Require PR, CI pass

Release Process

Tag main with semantic version: git tag v1.2.3
Push tags: git push --tags
CI deploys to production on tag push

Specific conventions to be refined during development

Development Standards

On this page