From e76e3619811ef18df6779f4f12b4ea1391ba229e Mon Sep 17 00:00:00 2001 From: waruneeauy Date: Wed, 4 Feb 2026 16:18:45 +0700 Subject: [PATCH] init claude overview project --- CLAUDE.md | 137 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..1db8de32 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,137 @@ +# 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 +```bash +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: + +```bash +# 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 +```bash +# 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.