Components
Laravel API (server/)
| Module | Responsibility |
|---|---|
app/Models | Eloquent definitions and relationships. |
app/Http/Controllers/Api/V1 | Versioned REST controllers. Thin; delegate to services. |
app/Http/Requests | FormRequest classes — validation and policy-based authorization. |
app/Http/Resources | Response shaping. |
app/Services/Attendance | PunchIngestService, AttendanceProcessor, AttendanceRecalculator, AttendanceLocker. |
app/Services/Roster | Roster build, locum insertion, conflict detection. |
app/Services/Flags | Red-flag rule evaluation and policy (allow / block / require approval). |
app/Services/Geo | Geo-fence haversine checks and violation detection. |
app/Services/Devices | Device registration, approval, fingerprint validation. |
app/Services/Export | CSV / XLSX / PDF generators (queued jobs). |
app/Jobs | Queue jobs invoked from services. |
app/Policies | Per-resource authorization. |
app/Filament | SystemAdmin back-office panel resources. |
routes/api.php | All public REST routes, versioned under /api/v1. |
React Web UI (ui/)
| Area | Responsibility |
|---|---|
src/app/routes.tsx | Route table with role guards. |
src/app/layouts/AppShell.tsx | Role-aware shell (sidebar, topbar, tenant switcher). |
src/features/auth | Login, token storage, token refresh. |
src/features/orgs | Organization and unit CRUD. |
src/features/employees | Employee CRUD, transfers, category. |
src/features/shifts | Shift CRUD and unit assignment. |
src/features/roster | Monthly roster grid editor. |
src/features/attendance | Daily + monthly views, edit, export. |
src/features/leave | Leave inbox for managers, request form for employees. |
src/features/reports | Filter panel, preview, export. |
src/lib/api | Axios instance + generated types from OpenAPI. |
src/lib/auth | Token persistence, refresh, role introspection. |
Flutter Mobile App (app/)
| Layer | Responsibility |
|---|---|
lib/core/network | Dio client, interceptors, retry, offline queue. |
lib/core/storage | Secure storage for tokens, device ID, offline punches. |
lib/core/geo | Geolocator wrapper, permission flow, distance calc. |
lib/core/device | Device fingerprinting (platform + model + install ID). |
lib/features/auth | Login, OTP, device registration. |
lib/features/attendance | Check-in/out, status, offline buffer. |
lib/features/leave | Leave request and status. |
lib/features/regularization | Correction request. |
lib/features/profile | Employee profile, shift for today. |
Telegram Bot (post-MVP)
- Laravel webhook at
/telegram/webhook. - Maintains
employee_telegram_linkstable. - Commands:
/login,/in,/out,/status,/leave. - Re-uses
PunchIngestService— Telegram is just another channel.
Background Workers (Horizon)
| Queue | Purpose |
|---|---|
punches | Process raw punches into attendance rows. |
recalc | Recalculate attendance after regularization or roster change. |
notifications | Push + email + Telegram notifications. |
exports | Long-running CSV / XLSX / PDF generation. |
audit | Write audit logs asynchronously when safe. |
Datastores
- MySQL 8 — primary OLTP store.
- Redis — queues (Horizon), cache (policy decisions, roster lookups), rate limiters.
- S3-compatible object storage — export artefacts, employee photos.