hrms-api-org/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is bma-ehr-organization - an HRMS (Human Resource Management System) API backend for a Thai healthcare organization. It manages personnel data, organizational structure, positions, and employee profiles for an Electronic Health Record (EHR) system.

• Type: RESTful API backend with WebSocket support
• Language: TypeScript/Node.js
• Database: MySQL with TypeORM
• API Framework: TSOA (TypeScript OpenAPI) with auto-generated routes and Swagger docs

Common Commands

Development

npm run dev          # Start development server with hot-reload (nodemon)
npm run build        # Build for production (runs tsoa spec-and-routes && tsc)
npm start            # Run production build (node ./dist/app.js)
npm run format       # Format code with Prettier
npm run check        # Type check without emitting (tsc --noEmit)

Database Migrations

CRITICAL: After generating any migration, you MUST run the cleanup script to remove FK/idx lines:

# Generate new migration (include descriptive name)
npm run migration:generate src/migration/update_table_0811202s

# CLEANUP: Remove FK_/idx_ lines from generated migration
node scripts/clean-migration-fk-idx.js

# Run migrations
npm run migration:run

The cleanup script replaces lines containing FK_ or idx_ with // removed FK_/idx_ auto-cleanup. This is required because TypeORM generates foreign key and index constraints that must be manually removed.

Local GitHub Actions Testing

# Test release workflow locally using act
act workflow_dispatch -W .github/workflows/release.yaml \
  --input IMAGE_VER=latest \
  -s DOCKER_USER=admin \
  -s DOCKER_PASS=FPTadmin2357 \
  -s SSH_PASSWORD=FPTadmin2357

Architecture

Application Entry Point

src/app.ts - Initializes the application:

1. Database connection (TypeORM MySQL)
2. In-memory caches (LogMemoryStore, OrgStructureCache with 30min TTL)
3. WebSocket server for real-time updates
4. Express middleware and TSOA routes
5. Cronjobs (scheduled tasks)
6. RabbitMQ message queue consumer

Controllers (src/controllers/)

Handle HTTP requests. Main controllers include:

• OrganizationController - Organizational structure management
• CommandController - Workflow and command processing
• ProfileSalaryController - Salary and tenure management
• Controllers for positions, employees, auth, etc.

Cronjob logic is embedded in controllers (not separate services).

Services (src/services/)

Business logic and external integrations:

• OrganizationService.ts - Core organizational logic
• rabbitmq.ts - RabbitMQ consumer for async processing
• webSocket.ts - Real-time updates to clients

Entities (src/entities/)

TypeORM database models for MySQL. Key entities:

• Organization hierarchy (OrgRoot, OrgChild1-4)
• Position management (Position, PosType, PosLevel, PosExecutive)
• Employee profiles and related data
• Command/Workflow entities

Middlewares (src/middlewares/)

• auth.ts - Keycloak Bearer token authentication
• authWebService.ts - API key authentication (X-API-Key header)
• role.ts - Role-based authorization
• logs.ts - Request logging
• error.ts - Global error handling
• user.ts - User context extraction

TSOA Configuration

src/routes.ts is auto-generated by TSOA from controller decorators. Regenerated by npm run build.

• Swagger docs available at /api-docs
• Dual authentication: Keycloak bearer tokens and API keys
• API tags organized by domain (Organization, Position, Employee, etc.)

Scheduled Cronjobs

All times in Bangkok timezone (UTC+7):

Schedule	Task	Controller
0 0 3 * * *	Daily revision processing	OrganizationController.cronjobRevision()
0 0 2 * * *	Daily command processing	CommandController.cronjobCommand()
0 0 1 10 *	Monthly retirement status update (10th of month)	CommandController.cronjobUpdateRetirementStatus()
0 0 0 * * *	Daily tenure updates	ProfileSalaryController (multiple tenure methods)

External Dependencies

• Keycloak - Authentication and authorization
• RabbitMQ - Message queue for async operations
• WebSocket (Socket.IO) - Real-time updates
• Elasticsearch - Logging
• Redis - Caching layer
• TypeORM - Database ORM

Code Style

• Prettier: 2 spaces, 100 char width, trailing commas
• TypeScript: Strict mode enabled
• Comments: Mixed Thai and English
• Date handling: Custom DateSerializer for local timezone serialization

Important Notes

1. Migration cleanup is mandatory - TypeORM generates FK and index constraints that break the migration system. Always run node scripts/clean-migration-fk-idx.js after migration:generate.

2. Organization caching - OrgStructureCache provides in-memory caching of org structure (30 min TTL) for performance.

3. Graceful shutdown - Application handles SIGTERM/SIGINT to close database connections, caches, and HTTP server properly.

4. Dual auth system - Most endpoints use Keycloak bearer tokens, but some web service endpoints use X-API-Key header authentication.

5. Thai localization - The system is primarily for Thai users; documentation and some content is in Thai, but code is in English.