VENI-AI

English

Tiếng Việt

English

Tiếng Việt

Appearance

Technical Specification: HRM Module ​

This document details the technical architecture, technology stack, and integration patterns for the HRM (Human Resource Management) module.

v1.0 — ApprovedPlatform: VENI-AI ShellStack: Bun/Ignis/Hono

1. High-Level Architecture ​

The HRM module is built as a SCS (Self-Contained System) within the VENI-AI ecosystem. It maintains its own database schema while relying on the Shell for Identity and Access Management.

Component Diagram ​

2. Technology Stack ​

Backend (API) ​

  • Runtime: Bun (High-performance JS runtime)
  • Framework: Ignis Framework (Internal IoC/DI wrapper)
  • Router: Hono (Ultrafast web framework)
  • ORM: Drizzle ORM (TypeScript-first SQL toolkit)
  • Database: PostgreSQL 15+

Frontend (UI) ​

  • Library: React 18
  • Build Tool: Vite
  • Integration: Webpack Module Federation (for Shell embedding)
  • Styling: Tailwind CSS v4 + ARDOR UI Kit
  • Charts: D3.js (for Org Chart)
  • Calendar: FullCalendar React

3. Integration Patterns ​

3.1 Authentication & Multi-tenancy ​

HRM is a multi-tenant application where isolation is strictly enforced at the database level using orgId.

  • JWT Verification: The API uses the Shell's public JWKS to verify the Platform JWT.
  • Tenant Context: The organizationId and userId are extracted from the JWT sub/claims and injected into the service context.

3.2 Authorization (RBAC) ​

Permission checks are performed using the @authorize() decorator in controllers, which interfaces with the Shell's Casbin-based RBAC service.

ScopeLogic
employees:readAllows listing and viewing public profiles.
employees:writeAllows creating/updating profiles (HR Admin).
leave_requests:approveAllows managers to act on pending leaves.

3.3 Object Storage ​

Employee profile photos and onboarding documents are stored in MinIO/S3.

  • Pathing: avatars/{orgId}/{employeeId}.jpg
  • Security: Files are served via signed URLs or a proxy with RBAC checks.

4. Key Implementation Logic ​

4.1 Leave Balance Calculation ​

Leave balances are updated atomically using database transactions.

  1. Check leave_balances for sufficient totalDays - usedDays.
  2. Insert leave_requests with status='pending'.
  3. On Approval: Increment usedDays in leave_balances.

4.2 Org Chart Generation ​

The org chart uses a recursive tree construction on the frontend:

  • Input: Flat array of employees with managerId.
  • Processing: D3.js stratify() transforms this into a hierarchical JSON.
  • Rendering: SVG-based tree with zoom/pan capabilities.

4.3 Onboarding Workflow ​

Triggered by an event-driven hook on employee creation.

  • If employee.jobTitle or a specific tag matches an onboarding_templates.roleTag, the system clones all onboarding_template_tasks into checklist_items for the new hire.

5. Security & Governance ​

  • Data Encryption: Sensitive fields (like emergency contact phone numbers) are encrypted at rest (planned for v1.1).
  • Audit Logging: Every change to an employee's status or a leave request's approval is logged with the actor's ID and timestamp.
  • Tenant Isolation: Cross-tenant data access is prevented by mandatory orgId filters in every SQL query.

Related Links

© 2025-2026 VENIZIA AI