# rcstrue/rcs_hrms architecture

> Architecture diagram of the GitHub repository rcstrue/rcs_hrms, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rcstrue/rcs_hrms
- Repository: https://github.com/rcstrue/rcs_hrms

## Overview

1. **System shape**
   - This repository is a three-part HRMS: a classic PHP admin portal, a separate PHP REST API for employee self-service, and a React/Vite SPA that consumes that API.
   - The key architectural split is **admin/session-authenticated backend** versus **employee/JWT-authenticated SPA backend**.

2. **HRMS Admin application (`php_payroll/`)**
   - The largest subsystem is the legacy-style PHP application that handles payroll, HR, compliance, reports, and master data.
   - It is organized by domain modules such as `employee`, `attendance`, `payroll`, `compliance`, `leave`, `loan`, `notifications`, `settings`, `report`, and `portal`.
   - Shared PHP infrastructure lives in `includes/`, `templates/`, `config/`, and `modules/api/` for AJAX-style endpoints used by the admin UI.

3. **ESS REST API (`api/ess/`)**
   - This is the backend boundary for the employee self-service experience.
   - Endpoints cover login/refresh, PIN management, attendance, leaves, payslips, notifications, tasks, helpdesk, expenses, announcements, manpower status, unit visits, designations, employees, and admin notification actions.
   - The API is PHP-based, uses `.htaccess` routing, and is explicitly separated from the admin app’s session-based endpoints.

4. **ESS SPA (`RCS_ESS/`)**
   - The SPA is a React + Vite + Bun application that provides the employee-facing UI.
   - It has a feature-driven component structure under `src/components/ess/`, plus admin-oriented components under `src/components/admin/`, shared UI primitives under `src/components/ui/`, and route-level pages in `src/pages/`.
   - The SPA also includes PWA-like UX pieces such as install prompts, pull-to-refresh, mobile hooks, and bottom navigation.

5. **Client-side data access**
   - The SPA’s service layer is separated under `src/lib/`, with dedicated API clients for ESS and admin-facing data, plus auth helpers and typed models.
   - Feature hooks such as attendance, dashboard, notifications, export CSV, PWA install, and pull-to-refresh encapsulate API interaction and UI state.
   - This means most business logic on the React side is orchestrated through hooks and service modules rather than directly inside pages.

6. **Shared database and schema**
   - Both backend systems ultimately target the same MySQL data store, with schema evolution tracked in `database/migrations/`.
   - The migrations indicate shared core entities for employees, roles, app status, and other HRMS records.
   - This shared database is the main integration point between the admin portal and ESS API.

7. **Authentication boundaries**
   - The PHP admin app uses traditional server/session authentication.
   - The ESS API uses JWT-based authentication, including token refresh and PIN-related flows.
   - That separation is important for the diagram: two different auth models, two different frontends, one underlying HRMS dataset.

8. **Document, file, and report generation**
   - Both sides generate operational documents such as payslips, registration PDFs, visit reports, and spreadsheets.
   - In the SPA, PDF and Excel helpers live under `src/lib/pdf/` and `src/lib/excel/`.
   - In the PHP admin app, there are many print/report modules for payroll, statutory filings, employee forms, and compliance exports.

9. **Functional domains**
   - Core HR domains in the admin app include employee lifecycle, attendance entry, payroll processing, compliance filings, statutory reports, leave/loan/advance management, asset and requisition tracking, and notifications.
   - The ESS app focuses on employee self-service tasks: attendance, profile, payslips, leave requests, notifications, helpdesk, expenses, tasks, holidays, directory, unit visits, and manpower status.
   - This makes the admin portal the system-of-record operator interface and the SPA the employee consumption interface.

10. **Operational/deployment layout**
   - The repo is set up for separate deployment of the PHP admin app and the ESS stack, with GitHub Actions workflows for PHP and ESS deployment.
   - `Caddyfile` files and `.htaccess` support indicate different hosting/runtime assumptions for the PHP services and the SPA build output.
   - The SPA is built locally into `dist/`, while the PHP apps are served directly by the web server.

11. **What to draw in an architecture diagram**
   - Show two browser-facing clients: the admin portal and the employee SPA.
   - Route the admin portal to the PHP admin application and the SPA to the ESS REST API.
   - Place MySQL as the shared persistence layer underneath both backends.
   - Add separate arrows for session auth on the admin side and JWT auth on the ESS side, plus file-generation/reporting outputs as side services of both backend domains.

Main entry points: [`php_payroll/modules`](https://github.com/rcstrue/rcs_hrms/tree/main/php_payroll/modules) (HR modules), [`RCS_ESS/src/components/ess`](https://github.com/rcstrue/rcs_hrms/tree/main/RCS_ESS/src/components/ess) (ESS features), [`php_payroll/index.php`](https://github.com/rcstrue/rcs_hrms/blob/main/php_payroll/index.php) (Portal entry), [`api/ess`](https://github.com/rcstrue/rcs_hrms/tree/main/api/ess) (ESS endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Browser clients"]
  node_admin_browser(("Admin portal<br/>browser client"))
  node_employee_browser(("ESS web app<br/>browser client"))
end

subgraph group_php_admin["PHP admin app"]
  node_admin_entry["Portal entry<br/>php entrypoint<br/>[index.php]"]
  node_admin_auth["Session auth<br/>php auth<br/>[login.php]"]
  node_admin_core["HR modules<br/>php modules"]
  node_admin_api["Admin APIs<br/>php ajax api"]
  node_admin_infra["Shared PHP infra<br/>php support"]
  node_admin_templates["Templates<br/>php view layer"]
end

subgraph group_ess_api["ESS API"]
  node_ess_entry["ESS API entry<br/>php api entrypoint<br/>[login.php]"]
  node_ess_routes["ESS endpoints<br/>php rest endpoints"]
  node_ess_auth["JWT auth<br/>php auth<br/>[refresh.php]"]
  node_ess_support["API support<br/>php support<br/>[helpers.php]"]
end

subgraph group_spa["ESS SPA"]
  node_spa_entry["SPA entry<br/>react app<br/>[main.tsx]"]
  node_spa_ess["ESS features<br/>react features"]
  node_spa_admin["Admin screens<br/>react admin views"]
  node_spa_lib["API layer<br/>react services"]
  node_spa_hooks["Feature hooks<br/>react hooks"]
  node_spa_docs["PDF/Excel<br/>react export"]
end

subgraph group_data["Shared data"]
  node_db[("MySQL<br/>shared datastore")]
  node_migrations["Migrations<br/>schema evolution"]
end

subgraph group_delivery["Delivery"]
  node_deploy_php["PHP deploy<br/>ci workflow<br/>[deploy-php.yml]"]
  node_deploy_ess["ESS deploy<br/>ci workflow<br/>[deploy-ess.yml]"]
  node_caddy_php["PHP host config<br/>web server config"]
  node_caddy_ess["SPA host config<br/>web server config"]
end

node_admin_browser -->|"uses"| node_admin_entry
node_admin_entry -->|"login"| node_admin_auth
node_admin_entry -->|"routes to"| node_admin_core
node_admin_core -->|"shares"| node_admin_infra
node_admin_core -->|"renders"| node_admin_templates
node_admin_core -->|"calls"| node_admin_api
node_admin_infra -->|"reads/writes"| node_db
node_ess_entry -->|"serves"| node_ess_routes
node_ess_entry -->|"authenticates"| node_ess_auth
node_ess_routes -->|"uses"| node_ess_support
node_ess_routes -->|"reads/writes"| node_db
node_employee_browser -->|"loads"| node_spa_entry
node_spa_entry -->|"composes"| node_spa_ess
node_spa_entry -->|"composes"| node_spa_admin
node_spa_ess -->|"fetches via"| node_spa_lib
node_spa_admin -->|"fetches via"| node_spa_lib
node_spa_ess -->|"orchestrates"| node_spa_hooks
node_spa_ess -->|"generates"| node_spa_docs
node_spa_lib -->|"calls"| node_ess_routes
node_spa_lib -.->|"ultimately reads/writes"| node_db
node_migrations -->|"evolves"| node_db
node_deploy_php -->|"deploys"| node_caddy_php
node_deploy_ess -->|"deploys"| node_caddy_ess
node_caddy_php -->|"serves"| node_admin_entry
node_caddy_ess -->|"serves"| node_spa_entry

click node_admin_entry "https://github.com/rcstrue/rcs_hrms/blob/main/php_payroll/index.php"
click node_admin_auth "https://github.com/rcstrue/rcs_hrms/blob/main/php_payroll/modules/auth/login.php"
click node_admin_core "https://github.com/rcstrue/rcs_hrms/tree/main/php_payroll/modules"
click node_admin_api "https://github.com/rcstrue/rcs_hrms/tree/main/php_payroll/modules/api"
click node_admin_infra "https://github.com/rcstrue/rcs_hrms/tree/main/php_payroll/includes"
click node_admin_templates "https://github.com/rcstrue/rcs_hrms/tree/main/php_payroll/templates"
click node_ess_entry "https://github.com/rcstrue/rcs_hrms/blob/main/api/ess/login.php"
click node_ess_routes "https://github.com/rcstrue/rcs_hrms/tree/main/api/ess"
click node_ess_auth "https://github.com/rcstrue/rcs_hrms/blob/main/api/ess/refresh.php"
click node_ess_support "https://github.com/rcstrue/rcs_hrms/blob/main/api/ess/helpers.php"
click node_spa_entry "https://github.com/rcstrue/rcs_hrms/blob/main/RCS_ESS/src/main.tsx"
click node_spa_ess "https://github.com/rcstrue/rcs_hrms/tree/main/RCS_ESS/src/components/ess"
click node_spa_admin "https://github.com/rcstrue/rcs_hrms/tree/main/RCS_ESS/src/components/admin"
click node_spa_lib "https://github.com/rcstrue/rcs_hrms/tree/main/RCS_ESS/src/lib/api"
click node_spa_hooks "https://github.com/rcstrue/rcs_hrms/tree/main/RCS_ESS/src/components/ess/hooks"
click node_spa_docs "https://github.com/rcstrue/rcs_hrms/tree/main/RCS_ESS/src/lib/pdf"
click node_migrations "https://github.com/rcstrue/rcs_hrms/tree/main/database/migrations"
click node_deploy_php "https://github.com/rcstrue/rcs_hrms/blob/main/.github/workflows/deploy-php.yml"
click node_deploy_ess "https://github.com/rcstrue/rcs_hrms/blob/main/.github/workflows/deploy-ess.yml"
click node_caddy_php "https://github.com/rcstrue/rcs_hrms/tree/main/php_payroll/Caddyfile"
click node_caddy_ess "https://github.com/rcstrue/rcs_hrms/tree/main/RCS_ESS/Caddyfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_admin_browser,node_employee_browser toneBlue
class node_admin_entry,node_admin_auth,node_admin_core,node_admin_api,node_admin_infra,node_admin_templates toneAmber
class node_ess_entry,node_ess_routes,node_ess_auth,node_ess_support toneMint
class node_spa_entry,node_spa_ess,node_spa_admin,node_spa_lib,node_spa_hooks,node_spa_docs toneRose
class node_db,node_migrations toneIndigo
class node_deploy_php,node_deploy_ess,node_caddy_php,node_caddy_ess toneTeal
```

## Components

### Browser clients

User-facing entry points for admin staff and employees.

- **Admin portal**: browser client · Session-authenticated browser used by HR/admin users.
- **ESS web app**: browser client · Employee-facing SPA consumed by staff on desktop and mobile.

### PHP admin app

Legacy HRMS admin portal and server-rendered operational modules.

- [Portal entry](https://github.com/rcstrue/rcs_hrms/blob/main/php_payroll/index.php): php entrypoint · Main PHP front controller for the admin application. · `php_payroll/index.php`
- [Session auth](https://github.com/rcstrue/rcs_hrms/blob/main/php_payroll/modules/auth/login.php): php auth · Traditional login/logout flow for the admin portal. · `php_payroll/modules/auth/login.php`
- [HR modules](https://github.com/rcstrue/rcs_hrms/tree/main/php_payroll/modules): php modules · Domain modules for employee, attendance, payroll, leave, loan, compliance, reports, and settings. · `php_payroll/modules`
- [Admin APIs](https://github.com/rcstrue/rcs_hrms/tree/main/php_payroll/modules/api): php ajax api · Internal AJAX-style endpoints used by the admin UI. · `php_payroll/modules/api`
- [Shared PHP infra](https://github.com/rcstrue/rcs_hrms/tree/main/php_payroll/includes): php support · Database, auth, notification, payroll, compliance, and Excel/PDF helper classes. · `php_payroll/includes`
- [Templates](https://github.com/rcstrue/rcs_hrms/tree/main/php_payroll/templates): php view layer · Common header and footer templates for server-rendered pages. · `php_payroll/templates`

### ESS API

Employee self-service PHP REST boundary.

- [ESS API entry](https://github.com/rcstrue/rcs_hrms/blob/main/api/ess/login.php): php api entrypoint · REST boundary for employee self-service requests. · `api/ess/login.php`
- [ESS endpoints](https://github.com/rcstrue/rcs_hrms/tree/main/api/ess): php rest endpoints · Attendance, leaves, payslips, notifications, tasks, helpdesk, expenses, announcements, visits, and related actions. · `api/ess`
- [JWT auth](https://github.com/rcstrue/rcs_hrms/blob/main/api/ess/refresh.php): php auth · Token login, refresh, PIN, and security header flow for ESS. · `api/ess/refresh.php`
- [API support](https://github.com/rcstrue/rcs_hrms/blob/main/api/ess/helpers.php): php support · CORS, filters, helpers, and shared response/security code for the ESS API. · `api/ess/helpers.php`

### ESS SPA

React/Vite employee frontend.

- [SPA entry](https://github.com/rcstrue/rcs_hrms/blob/main/RCS_ESS/src/main.tsx): react app · Main React/Vite application shell. · `RCS_ESS/src/main.tsx`
- [ESS features](https://github.com/rcstrue/rcs_hrms/tree/main/RCS_ESS/src/components/ess): react features · Employee-facing screens for attendance, dashboard, profile, leaves, payslips, helpdesk, tasks, notifications, and visits. · `RCS_ESS/src/components/ess`
- [Admin screens](https://github.com/rcstrue/rcs_hrms/tree/main/RCS_ESS/src/components/admin): react admin views · React admin UI for employee, role, designation, notification, and salary operations. · `RCS_ESS/src/components/admin`
- [API layer](https://github.com/rcstrue/rcs_hrms/tree/main/RCS_ESS/src/lib/api): react services · Client-side API wrappers, auth helpers, and typed data access for ESS and admin data. · `RCS_ESS/src/lib/api`
- [Feature hooks](https://github.com/rcstrue/rcs_hrms/tree/main/RCS_ESS/src/components/ess/hooks): react hooks · Attendance, dashboard, notifications, export, PWA install, and pull-to-refresh orchestration. · `RCS_ESS/src/components/ess/hooks`
- [PDF/Excel](https://github.com/rcstrue/rcs_hrms/tree/main/RCS_ESS/src/lib/pdf): react export · Client-side helpers for payslip, registration, and visit-report document generation. · `RCS_ESS/src/lib/pdf`

### Shared data

Database and schema evolution shared by both backend stacks.

- **MySQL**: shared datastore · Common HRMS database used by both backend systems.
- [Migrations](https://github.com/rcstrue/rcs_hrms/tree/main/database/migrations): schema evolution · Shared database migration history for core entities and status/role changes. · `database/migrations`

### Delivery

Build and deployment support for the separate runtimes.

- [PHP deploy](https://github.com/rcstrue/rcs_hrms/blob/main/.github/workflows/deploy-php.yml): ci workflow · GitHub Actions workflow for the PHP admin stack. · `.github/workflows/deploy-php.yml`
- [ESS deploy](https://github.com/rcstrue/rcs_hrms/blob/main/.github/workflows/deploy-ess.yml): ci workflow · GitHub Actions workflow for the ESS stack. · `.github/workflows/deploy-ess.yml`
- [PHP host config](https://github.com/rcstrue/rcs_hrms/tree/main/php_payroll/Caddyfile): web server config · Caddy configuration for serving the admin PHP application. · `php_payroll/Caddyfile`
- [SPA host config](https://github.com/rcstrue/rcs_hrms/tree/main/RCS_ESS/Caddyfile): web server config · Caddy configuration for serving the built ESS SPA. · `RCS_ESS/Caddyfile`

## Connections

- Admin portal → Portal entry: uses · Admin users access the session-authenticated PHP portal.
- Portal entry → Session auth: login · Portal entry delegates authentication to the login flow.
- Portal entry → HR modules: routes to · Requests are handled by the domain module tree.
- HR modules → Shared PHP infra: shares · Modules rely on common database, payroll, compliance, and export helpers.
- HR modules → Templates: renders · Server-rendered pages reuse common templates.
- HR modules → Admin APIs: calls · Admin UI uses internal AJAX endpoints for edits and uploads.
- Shared PHP infra → MySQL: reads/writes · The PHP admin app persists HRMS data to MySQL.
- ESS API entry → ESS endpoints: serves · The ESS API exposes feature endpoints behind routing rules.
- ESS API entry → JWT auth: authenticates · Login and refresh flow establishes JWT-based access.
- ESS endpoints → API support: uses · Endpoint handlers share helpers, filters, and security code.
- ESS endpoints → MySQL: reads/writes · Employee self-service operations target the shared database.
- ESS web app → SPA entry: loads · Employees open the React/Vite SPA.
- SPA entry → ESS features: composes · The app shell assembles employee-facing feature pages.
- SPA entry → Admin screens: composes · The same SPA also contains admin-oriented views.
- ESS features → API layer: fetches via · ESS screens use the service layer for API access.
- Admin screens → API layer: fetches via · Admin screens also go through shared client wrappers.
- ESS features → Feature hooks: orchestrates · Feature hooks manage UI state and backend interaction.
- ESS features → PDF/Excel: generates · The SPA includes client-side document export helpers.
- API layer → ESS endpoints: calls · Client services talk to the ESS PHP API.
- API layer → MySQL: ultimately reads/writes · SPA data access is mediated by the API against the shared database.
- Migrations → MySQL: evolves · Schema migrations define the shared persistence structure.
- PHP deploy → PHP host config: deploys · PHP deployment aligns with the PHP host configuration.
- ESS deploy → SPA host config: deploys · ESS deployment aligns with the SPA host configuration.
- PHP host config → Portal entry: serves · Web server configuration exposes the PHP admin application.
- SPA host config → SPA entry: serves · Web server configuration exposes the SPA build output.
