How rcstrue/rcs_hrms works
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: modules HR modules · components/ess ESS features · index.php Portal entry · api/ess ESS endpoints
Components 24
Browser clients
User-facing entry points for admin staff and employees.
- Admin portal · Session-authenticated browser used by HR/admin users.
- ESS web app · Employee-facing SPA consumed by staff on desktop and mobile.
PHP admin app
Legacy HRMS admin portal and server-rendered operational modules.
- Portal entry · Main PHP front controller for the admin application.
php_payroll/index.php - Session auth · Traditional login/logout flow for the admin portal.
php_payroll/modules/auth/login.php - HR modules · Domain modules for employee, attendance, payroll, leave, loan, compliance, reports, and settings.
php_payroll/modules - Admin APIs · Internal AJAX-style endpoints used by the admin UI.
php_payroll/modules/api - Shared PHP infra · Database, auth, notification, payroll, compliance, and Excel/PDF helper classes.
php_payroll/includes - Templates · Common header and footer templates for server-rendered pages.
php_payroll/templates
ESS API
Employee self-service PHP REST boundary.
- ESS API entry · REST boundary for employee self-service requests.
api/ess/login.php - ESS endpoints · Attendance, leaves, payslips, notifications, tasks, helpdesk, expenses, announcements, visits, and related actions.
api/ess - JWT auth · Token login, refresh, PIN, and security header flow for ESS.
api/ess/refresh.php - API 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 · Main React/Vite application shell.
RCS_ESS/src/main.tsx - ESS features · Employee-facing screens for attendance, dashboard, profile, leaves, payslips, helpdesk, tasks, notifications, and visits.
RCS_ESS/src/components/ess - Admin screens · React admin UI for employee, role, designation, notification, and salary operations.
RCS_ESS/src/components/admin - API layer · Client-side API wrappers, auth helpers, and typed data access for ESS and admin data.
RCS_ESS/src/lib/api - Feature hooks · Attendance, dashboard, notifications, export, PWA install, and pull-to-refresh orchestration.
RCS_ESS/src/components/ess/hooks - PDF/Excel · 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 · Common HRMS database used by both backend systems.
- Migrations · Shared database migration history for core entities and status/role changes.
database/migrations
Delivery
Build and deployment support for the separate runtimes.
- PHP deploy · GitHub Actions workflow for the PHP admin stack.
.github/workflows/deploy-php.yml - ESS deploy · GitHub Actions workflow for the ESS stack.
.github/workflows/deploy-ess.yml - PHP host config · Caddy configuration for serving the admin PHP application.
php_payroll/Caddyfile - SPA host config · Caddy configuration for serving the built ESS SPA.
RCS_ESS/Caddyfile
Connections 25
- 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.