# ralphacoba/staffsync-hr architecture

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

- Interactive diagram: https://gitdiagram.com/ralphacoba/staffsync-hr
- Repository: https://github.com/ralphacoba/staffsync-hr

## Overview

1. This repository is a Base44-backed React single-page application for workforce operations: attendance/biometrics, scheduling, employees, and payroll. The architecture is split between a Vite front end in `src/` and a Base44 backend definition in `base44/`.

2. The front end is the presentation and interaction layer. `src/main.jsx`, `src/App.jsx`, and `src/pages/*` define routed application screens such as Dashboard, Employees, Schedule, Payroll, BiometricAttendance, and DTRReview. `ProtectedRoute` and `AuthContext` indicate authentication-gated access to most of the app.

3. Domain functionality is organized by feature area under `src/components/`. The main clusters are:
   - `biometric/` for log import, manual entry, settings, review tables, and punch history
   - `employees/` for employee CRUD and CSV import
   - `schedule/` for shifts, templates, and shift CSV import
   - `payroll/` for deductions, tax/overtime settings, holiday/service charge management, payroll summaries, audit logs, and remittance reporting
   - `dashboard/` for high-level operational widgets
   This organization maps closely to the backend entities.

4. The Base44 backend data model lives in `base44/entities/*.jsonc`. The core persistent objects are `Employee`, `Shift`, `ShiftTemplate`, `PunchEvent`, `TimeEntry`, `BiometricLog`, `BiometricSettings`, `PayrollRun`, `PayrollAuditLog`, `Deduction`, `Holiday`, `OvertimeSettings`, `TaxSettings`, `ServiceChargePool`, `DailyRevenue`, and `User`. These entities form the system-of-record for operational data and payroll calculations.

5. Data flow starts from user interaction in the React UI, then goes through `src/api/base44Client.js` to the Base44 backend. That client is the main boundary between browser state and persisted application data. The app likely uses `query-client.js` for caching/refreshing server state, which is important because many screens appear to render live operational records.

6. There are two backend functions in `base44/functions/`, both focused on ingestion/synchronization:
   - `importBiometricLogs` handles biometric log import, likely transforming raw attendance exports into stored logs/events.
   - `syncShiftFromShiftSync` keeps shift data synchronized from an external or upstream shift source.
   These functions represent server-side processing boundaries for bulk data import and integration logic.

7. Attendance processing is a multi-step subsystem. Biometric logs and punch events are captured, reviewed, and then turned into attendance records/time entries. The UI includes import and review components (`BiometricImport`, `DTRImport`, `AttendanceReviewTable`, `PunchEventsTable`, `BiometricHistoryView`, `BiometricManualEntry`), suggesting a workflow of ingest → inspect/clean → finalize into usable timekeeping data.

8. Scheduling is a separate but connected subsystem. `Shift`, `ShiftTemplate`, and the schedule UI indicate reusable templates and shift instances. `ShiftCSVImport` and the `syncShiftFromShiftSync` function imply that schedules can be loaded in bulk or synchronized from another system, then consumed by attendance and payroll logic.

9. Payroll is driven by the operational data above plus policy/configuration entities. `Deductions`, `TaxSettings`, `OvertimeSettings`, `Holiday`, and `ServiceChargePool` influence payroll calculations, while `PayrollRun` and `PayrollAuditLog` capture executed payroll periods and traceability. The payroll UI includes summary, employee breakdown, history, statutory remittance, and settings cards, which suggests a calculation-and-review workflow rather than a simple report page.

10. The dashboard is an aggregation layer rather than a source-of-truth layer. Widgets like attendance alerts, labor cost charts, recent payroll, and today’s schedule pull from multiple domains to provide operational visibility. This is the main cross-domain read path in the app.

11. Export/document generation is handled locally in `src/utils/`. `generatePayslipPdf.js` and `exportAttendanceReport.js` indicate that some reporting artifacts are generated on the client side from fetched domain data, rather than being fully delegated to the backend.

12. The UI stack is a reusable component system layered over domain screens. The many files in `src/components/ui/` suggest a shared design-system approach, while Tailwind/PostCSS and Vite handle styling and build/runtime concerns. This means the architecture is primarily feature/domain-driven, with a common UI foundation beneath it.

13. Deployment and configuration are Base44-centric. The README shows required environment variables for `VITE_BASE44_APP_ID` and `VITE_BASE44_APP_BASE_URL`, so the app is configured to connect to a specific Base44 backend instance. That makes the backend platform part of the runtime boundary, even though the repository contains both client and schema/function definitions.

14. For an architecture diagram, the clearest decomposition is: browser UI and routing on the left, Base44 data model and server functions on the right, with the main business flows running through attendance import/review, schedule management, payroll calculation, and dashboard/reporting reads across shared entities.

Main entry points: [`src/api/base44Client.js`](https://github.com/ralphacoba/staffsync-hr/blob/main/src/api/base44Client.js) (Base44 client), [`src/components/layout/AppLayout.jsx`](https://github.com/ralphacoba/staffsync-hr/blob/main/src/components/layout/AppLayout.jsx) (App layout), [`src/components/dashboard`](https://github.com/ralphacoba/staffsync-hr/tree/main/src/components/dashboard) (Dashboard widgets), [`base44/entities/PunchEvent.jsonc`](https://github.com/ralphacoba/staffsync-hr/blob/main/base44/entities/PunchEvent.jsonc) (Attendance model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_main(("App entry<br/>bootstrap<br/>[main.jsx]"))
  node_app["Root app<br/>routing-shell<br/>[App.jsx]"]
  node_auth["Auth context<br/>session-state<br/>[AuthContext.jsx]"]
  node_protected["Protected route<br/>route-guard<br/>[ProtectedRoute.jsx]"]
  node_layout["App layout<br/>shell-layout<br/>[AppLayout.jsx]"]
  node_dashboard["Dashboard page<br/>overview-screen<br/>[Dashboard.jsx]"]
  node_employees["Employees page<br/>hr-screen<br/>[Employees.jsx]"]
  node_schedule["Schedule page<br/>planning-screen<br/>[Schedule.jsx]"]
  node_attendance["Attendance page<br/>timekeeping-screen"]
  node_review["DTR review<br/>timekeeping-screen<br/>[DTRReview.jsx]"]
  node_payroll["Payroll page<br/>compensation-screen<br/>[Payroll.jsx]"]
  node_dashboardwidgets["Dashboard widgets<br/>summary-widgets"]
  node_biometricfeatures["Biometric tools<br/>attendance-workflow"]
  node_employeefeatures["Employee tools<br/>employee-workflow"]
  node_schedulefeatures["Schedule tools<br/>schedule-workflow"]
  node_payrollfeatures["Payroll tools<br/>payroll-workflow"]
end

subgraph group_backend["Base44 Backend"]
  node_attendanceentity[("Attendance model<br/>entity<br/>[PunchEvent.jsonc]")]
  node_scheduleentity[("Schedule model<br/>entity<br/>[Shift.jsonc]")]
  node_employeeentity[("People model<br/>entity<br/>[Employee.jsonc]")]
  node_payrollentity[("Payroll model<br/>entity<br/>[PayrollRun.jsonc]")]
  node_settingsentity[("Settings model<br/>entity")]
  node_importlogs{{"Import logs<br/>server-function<br/>[entry.ts]"}}
  node_syncshifts{{"Sync shifts<br/>server-function<br/>[entry.ts]"}}
end

subgraph group_shared["Shared UI"]
  node_base44client["Base44 client<br/>data-access<br/>[base44Client.js]"]
  node_queryclient["Query client<br/>cache-layer<br/>[query-client.js]"]
  node_exportutils["Reports utils<br/>client-export"]
end

node_main -->|"starts"| node_app
node_app -->|"uses"| node_auth
node_app -->|"guards"| node_protected
node_protected -->|"renders"| node_layout
node_layout -->|"navigates to"| node_dashboard
node_layout -->|"navigates to"| node_employees
node_layout -->|"navigates to"| node_schedule
node_layout -->|"navigates to"| node_attendance
node_layout -->|"navigates to"| node_payroll
node_layout -->|"navigates to"| node_review
node_dashboard -->|"composes"| node_dashboardwidgets
node_attendance -->|"uses"| node_biometricfeatures
node_employees -->|"uses"| node_employeefeatures
node_schedule -->|"uses"| node_schedulefeatures
node_payroll -->|"uses"| node_payrollfeatures
node_biometricfeatures -->|"reads/writes"| node_base44client
node_employeefeatures -->|"reads/writes"| node_base44client
node_schedulefeatures -->|"reads/writes"| node_base44client
node_payrollfeatures -->|"reads/writes"| node_base44client
node_dashboardwidgets -->|"refreshes via"| node_queryclient
node_base44client -->|"syncs"| node_attendanceentity
node_base44client -->|"syncs"| node_scheduleentity
node_base44client -->|"syncs"| node_employeeentity
node_base44client -->|"syncs"| node_payrollentity
node_base44client -->|"syncs"| node_settingsentity
node_importlogs -->|"produces"| node_attendanceentity
node_syncshifts -->|"produces"| node_scheduleentity
node_exportutils -->|"exports"| node_payrollentity
node_exportutils -->|"exports"| node_attendanceentity
node_dashboardwidgets -->|"reads"| node_attendanceentity
node_dashboardwidgets -->|"reads"| node_scheduleentity
node_dashboardwidgets -->|"reads"| node_payrollentity
node_payrollfeatures -->|"depends on"| node_attendanceentity
node_payrollfeatures -->|"depends on"| node_scheduleentity

click node_main "https://github.com/ralphacoba/staffsync-hr/blob/main/src/main.jsx"
click node_app "https://github.com/ralphacoba/staffsync-hr/blob/main/src/App.jsx"
click node_auth "https://github.com/ralphacoba/staffsync-hr/blob/main/src/lib/AuthContext.jsx"
click node_protected "https://github.com/ralphacoba/staffsync-hr/blob/main/src/components/ProtectedRoute.jsx"
click node_layout "https://github.com/ralphacoba/staffsync-hr/blob/main/src/components/layout/AppLayout.jsx"
click node_dashboard "https://github.com/ralphacoba/staffsync-hr/blob/main/src/pages/Dashboard.jsx"
click node_employees "https://github.com/ralphacoba/staffsync-hr/blob/main/src/pages/Employees.jsx"
click node_schedule "https://github.com/ralphacoba/staffsync-hr/blob/main/src/pages/Schedule.jsx"
click node_attendance "https://github.com/ralphacoba/staffsync-hr/blob/main/src/pages/BiometricAttendance.jsx"
click node_review "https://github.com/ralphacoba/staffsync-hr/blob/main/src/pages/DTRReview.jsx"
click node_payroll "https://github.com/ralphacoba/staffsync-hr/blob/main/src/pages/Payroll.jsx"
click node_dashboardwidgets "https://github.com/ralphacoba/staffsync-hr/tree/main/src/components/dashboard"
click node_biometricfeatures "https://github.com/ralphacoba/staffsync-hr/tree/main/src/components/biometric"
click node_employeefeatures "https://github.com/ralphacoba/staffsync-hr/tree/main/src/components/employees"
click node_schedulefeatures "https://github.com/ralphacoba/staffsync-hr/tree/main/src/components/schedule"
click node_payrollfeatures "https://github.com/ralphacoba/staffsync-hr/tree/main/src/components/payroll"
click node_base44client "https://github.com/ralphacoba/staffsync-hr/blob/main/src/api/base44Client.js"
click node_queryclient "https://github.com/ralphacoba/staffsync-hr/blob/main/src/lib/query-client.js"
click node_exportutils "https://github.com/ralphacoba/staffsync-hr/tree/main/src/utils"
click node_attendanceentity "https://github.com/ralphacoba/staffsync-hr/blob/main/base44/entities/PunchEvent.jsonc"
click node_scheduleentity "https://github.com/ralphacoba/staffsync-hr/blob/main/base44/entities/Shift.jsonc"
click node_employeeentity "https://github.com/ralphacoba/staffsync-hr/blob/main/base44/entities/Employee.jsonc"
click node_payrollentity "https://github.com/ralphacoba/staffsync-hr/blob/main/base44/entities/PayrollRun.jsonc"
click node_settingsentity "https://github.com/ralphacoba/staffsync-hr/blob/main/base44/entities/BiometricSettings.jsonc"
click node_importlogs "https://github.com/ralphacoba/staffsync-hr/blob/main/base44/functions/importBiometricLogs/entry.ts"
click node_syncshifts "https://github.com/ralphacoba/staffsync-hr/blob/main/base44/functions/syncShiftFromShiftSync/entry.ts"

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_main,node_app,node_auth,node_protected,node_layout,node_dashboard,node_employees,node_schedule,node_attendance,node_review,node_payroll,node_dashboardwidgets,node_biometricfeatures,node_employeefeatures,node_schedulefeatures,node_payrollfeatures toneBlue
class node_attendanceentity,node_scheduleentity,node_employeeentity,node_payrollentity,node_settingsentity,node_importlogs,node_syncshifts toneAmber
class node_base44client,node_queryclient,node_exportutils toneMint
```

## Components

### Frontend

React SPA, routing, feature screens, and shared UI

- [App entry](https://github.com/ralphacoba/staffsync-hr/blob/main/src/main.jsx): bootstrap · Vite startup and app mounting · `src/main.jsx`
- [Root app](https://github.com/ralphacoba/staffsync-hr/blob/main/src/App.jsx): routing-shell · Top-level routing and page composition · `src/App.jsx`
- [Auth context](https://github.com/ralphacoba/staffsync-hr/blob/main/src/lib/AuthContext.jsx): session-state · Authentication and user session state · `src/lib/AuthContext.jsx`
- [Protected route](https://github.com/ralphacoba/staffsync-hr/blob/main/src/components/ProtectedRoute.jsx): route-guard · Access control for authenticated screens · `src/components/ProtectedRoute.jsx`
- [App layout](https://github.com/ralphacoba/staffsync-hr/blob/main/src/components/layout/AppLayout.jsx): shell-layout · Global navigation and page chrome · `src/components/layout/AppLayout.jsx`
- [Dashboard page](https://github.com/ralphacoba/staffsync-hr/blob/main/src/pages/Dashboard.jsx): overview-screen · Operational summary and cross-domain widgets · `src/pages/Dashboard.jsx`
- [Employees page](https://github.com/ralphacoba/staffsync-hr/blob/main/src/pages/Employees.jsx): hr-screen · Employee management screen · `src/pages/Employees.jsx`
- [Schedule page](https://github.com/ralphacoba/staffsync-hr/blob/main/src/pages/Schedule.jsx): planning-screen · Shift planning and schedule management screen · `src/pages/Schedule.jsx`
- [Attendance page](https://github.com/ralphacoba/staffsync-hr/blob/main/src/pages/BiometricAttendance.jsx): timekeeping-screen · Biometric attendance and review screen · `src/pages/BiometricAttendance.jsx`
- [DTR review](https://github.com/ralphacoba/staffsync-hr/blob/main/src/pages/DTRReview.jsx): timekeeping-screen · Daily time record review workflow · `src/pages/DTRReview.jsx`
- [Payroll page](https://github.com/ralphacoba/staffsync-hr/blob/main/src/pages/Payroll.jsx): compensation-screen · Payroll calculation, settings, and reporting screen · `src/pages/Payroll.jsx`
- [Dashboard widgets](https://github.com/ralphacoba/staffsync-hr/tree/main/src/components/dashboard): summary-widgets · Attendance alerts, labor cost, recent payroll, and today schedule cards · `src/components/dashboard`
- [Biometric tools](https://github.com/ralphacoba/staffsync-hr/tree/main/src/components/biometric): attendance-workflow · Import, manual entry, review, history, and settings for attendance processing · `src/components/biometric`
- [Employee tools](https://github.com/ralphacoba/staffsync-hr/tree/main/src/components/employees): employee-workflow · Employee CRUD and CSV import components · `src/components/employees`
- [Schedule tools](https://github.com/ralphacoba/staffsync-hr/tree/main/src/components/schedule): schedule-workflow · Shift forms, templates, and CSV import components · `src/components/schedule`
- [Payroll tools](https://github.com/ralphacoba/staffsync-hr/tree/main/src/components/payroll): payroll-workflow · Deductions, settings, summaries, audit, and remittance components · `src/components/payroll`

### Base44 Backend

Persistent entities and server-side ingestion/sync functions

- [Attendance model](https://github.com/ralphacoba/staffsync-hr/blob/main/base44/entities/PunchEvent.jsonc): entity · Biometric logs, punch events, and time entries · `base44/entities/PunchEvent.jsonc`
- [Schedule model](https://github.com/ralphacoba/staffsync-hr/blob/main/base44/entities/Shift.jsonc): entity · Shifts and reusable shift templates · `base44/entities/Shift.jsonc`
- [People model](https://github.com/ralphacoba/staffsync-hr/blob/main/base44/entities/Employee.jsonc): entity · Employees and user access records · `base44/entities/Employee.jsonc`
- [Payroll model](https://github.com/ralphacoba/staffsync-hr/blob/main/base44/entities/PayrollRun.jsonc): entity · Payroll runs, audit logs, deductions, and policy settings · `base44/entities/PayrollRun.jsonc`
- [Settings model](https://github.com/ralphacoba/staffsync-hr/blob/main/base44/entities/BiometricSettings.jsonc): entity · Attendance, tax, overtime, holiday, and service charge configuration · `base44/entities/BiometricSettings.jsonc`
- [Import logs](https://github.com/ralphacoba/staffsync-hr/blob/main/base44/functions/importBiometricLogs/entry.ts): server-function · Transforms raw biometric exports into stored attendance data · `base44/functions/importBiometricLogs/entry.ts`
- [Sync shifts](https://github.com/ralphacoba/staffsync-hr/blob/main/base44/functions/syncShiftFromShiftSync/entry.ts): server-function · Synchronizes shifts from an upstream source · `base44/functions/syncShiftFromShiftSync/entry.ts`

### Shared UI

Reusable UI primitives and client-side helpers

- [Base44 client](https://github.com/ralphacoba/staffsync-hr/blob/main/src/api/base44Client.js): data-access · Browser boundary to the Base44 backend · `src/api/base44Client.js`
- [Query client](https://github.com/ralphacoba/staffsync-hr/blob/main/src/lib/query-client.js): cache-layer · Server-state caching and refresh coordination · `src/lib/query-client.js`
- [Reports utils](https://github.com/ralphacoba/staffsync-hr/tree/main/src/utils): client-export · Client-side payroll and attendance document generation · `src/utils`

## Connections

- App entry → Root app: starts · Bootstraps the SPA
- Root app → Auth context: uses · Reads session state for routing and access
- Root app → Protected route: guards · Wraps authenticated pages
- Protected route → App layout: renders · Places pages inside the shared shell
- App layout → Dashboard page: navigates to · Primary landing screen
- App layout → Employees page: navigates to · HR management screen
- App layout → Schedule page: navigates to · Scheduling screen
- App layout → Attendance page: navigates to · Attendance capture and review screen
- App layout → Payroll page: navigates to · Payroll operations screen
- App layout → DTR review: navigates to · DTR review screen
- Dashboard page → Dashboard widgets: composes · Aggregates cross-domain operational cards
- Attendance page → Biometric tools: uses · Attendance import and review workflow
- Employees page → Employee tools: uses · Employee maintenance workflow
- Schedule page → Schedule tools: uses · Shift planning workflow
- Payroll page → Payroll tools: uses · Payroll calculation and reporting workflow
- Biometric tools → Base44 client: reads/writes · Persists biometric data and settings
- Employee tools → Base44 client: reads/writes · Persists employee records
- Schedule tools → Base44 client: reads/writes · Persists shifts and templates
- Payroll tools → Base44 client: reads/writes · Loads payroll data and settings
- Dashboard widgets → Query client: refreshes via · Relies on cached server-state queries
- Base44 client → Attendance model: syncs · Biometric logs, punch events, and time entries
- Base44 client → Schedule model: syncs · Shift and template records
- Base44 client → People model: syncs · Employee and user records
- Base44 client → Payroll model: syncs · Payroll runs, deductions, and audit trail
- Base44 client → Settings model: syncs · Biometric and payroll policy settings
- Import logs → Attendance model: produces · Creates or updates attendance records from imports
- Sync shifts → Schedule model: produces · Keeps shifts aligned with upstream source
- Reports utils → Payroll model: exports · Builds payslips and attendance reports from fetched data
- Reports utils → Attendance model: exports · Uses attendance data for reporting artifacts
- Dashboard widgets → Attendance model: reads · Attendance alerts and operational stats
- Dashboard widgets → Schedule model: reads · Today schedule view
- Dashboard widgets → Payroll model: reads · Recent payroll and labor cost signals
- Payroll tools → Attendance model: depends on · Payroll calculations consume timekeeping data
- Payroll tools → Schedule model: depends on · Payroll and summaries use schedule context