Attendance & Workforce Deployment Management System

Purpose

This document defines the functional and non-functional requirements for a system designed to capture, manage, and report attendance of manpower deployed across multiple organizations and their respective units.

The system serves as a central attendance data platform that feeds external payroll and billing systems — it does not itself calculate salaries, generate slips, or produce invoices.

At a Glance

The platform has three consumer surfaces over a single API-first backend:

• Laravel API (server/) — source of truth, REST + Sanctum tokens, RBAC, queues, Filament SystemAdmin panel.
• React web UI (ui/) — role-scoped dashboards for HR, ShiftManager, OrgAdmin, SuperAdmin.
• Flutter mobile app (app/) — employee check-in/out, leave requests, regularization, geo-fenced.
• Telegram bot (planned) — alternative attendance channel for low-bandwidth regions.

High-Level Data Flow

Employee (mobile/web/telegram)
        │
        ▼
   Raw punch ──► PunchIngestService ──► queue ──► AttendanceProcessor
        │                                             │
        └──────────────── flags, rules ◄──────────────┘
                           │
                           ▼
                    attendances table ──► Reports / Payroll export

Document Structure

The documentation is organized into ten parts:

1. Introduction — purpose, scope, glossary.
2. Requirements — functional, non-functional, constraints.
3. Architecture — components, deployment, tech stack.
4. Data Model — ERD, schema, relationships.
5. API — authentication, endpoints, errors, integration.
6. Workflows — attendance, roster, leave, regularization, locum.
7. RBAC & Security — roles, permissions, scopes.
8. Attendance Engine — rules, red flags, geo-fencing, device binding, locking.
9. Execution Plan — phases, roadmap, sprints, team, risks.
10. Operations — deployment, monitoring, testing.