ralphacoba/staffsync-hr

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.