Employee Attendance & Field Mission Management System

Project overview

A Flutter employee application and Laravel/Filament administration system for location-validated attendance, leave, field missions, reporting, and optional CRM synchronization.

My role

Sole Mobile & Backend Developer

The problem

An employee attendance event must represent an allowed business transition with usable location evidence. Field missions also need an explicit tracking lifecycle, while administrators need reports, review tools, and integration with an existing CRM.

What I delivered

• Independently delivered the mobile application and backend, including authentication, employee workflows, API contracts, administration, and reporting.
• Built a Persian RTL Flutter interface with secure session storage, Jalali dates, attendance status, event history, leave workflows, and field mission controls.
• Implemented server-authoritative attendance transitions, employee row locking, transactional event persistence, and invalid-location audit records.
• Developed GPS sample collection, clustering and outlier handling, accuracy checks, freshness validation, and configurable office geofencing.
• Connected Flutter to a Kotlin Android foreground service with ongoing notifications, bounded persistent location queues, batched uploads, and status reporting.
• Implemented registered device keys, challenge-bound signatures, device approval/revocation/rotation controls, and configurable Android Play Integrity evaluation.
• Built Filament employee, device, office, attendance, mission and rejection-log management, together with monthly reporting and CSV/XLSX exports.
• Developed optional CRM employee mapping and queued attendance synchronization with retries and synchronization logs.

How the system fits together

Flutter delivery and native platform boundaries

The Dart application separates repositories, API transport, secure session storage, device context, location collection, and UI state. Shared Flutter screens support Android and iOS, with Persian RTL layouts and Jalali formatting. Platform channels connect the shared application to native device signing and Android mission tracking. The Android tracking implementation is a distinct Kotlin service; equivalent background behavior on iOS is not assumed.

GPS validation and configurable geofencing

The client collects multiple position samples and selects a usable cluster while rejecting poor accuracy and preserving mock-location signals. The backend independently evaluates the payload, sample integrity, and sample freshness. Server challenge time supplies a clock offset so a misconfigured phone clock does not automatically make a freshly collected sample appear stale. Geofence evaluation uses Haversine distance to the nearest active office and that office’s configured radius. Enforcement and integrity policies are configurable; collecting coordinates alone does not establish physical presence.

Attendance state and transactional consistency

Outside, Working, and Hourly Leave states are derived from valid events. The backend rejects duplicate check-ins and invalid transitions such as checking out during hourly leave. AttendanceService locks the employee row inside a database transaction before checking state and writing the event. Event time comes from the server, while device time and context remain audit inputs. Invalid location attempts have their own rejection records, and CRM work is dispatched after the attendance transaction commits.

Android field mission tracking

Starting a mission explicitly starts a foreground location service through a Flutter platform channel. The Kotlin service owns its notification, location listeners, bounded persistent queue, upload batching, and status file. A watchdog restarts stale listeners; the Flutter interface reads native tracking status without owning the service lifecycle. Removing the Flutter UI task is deliberately separated from ending the mission. Network failures can leave points queued for a later upload, but the bounded queue and Android permission, battery, and force-stop behavior prevent any claim of unlimited retention or uninterrupted tracking on every device.

Authentication and device integrity

Laravel Sanctum provides employee API sessions, with login throttling, active-employee checks, registered device context, and token revocation. Native EC keys sign a message bound to the attendance challenge, device UUID, and platform. The backend verifies the signature against the registered key and exposes administrative approval, revocation, and key rotation workflows. Android Play Integrity adds request-bound evaluation and audit records. The inspected request flow treats its verdicts as audit evidence; production blocking based on those verdicts is not claimed. These are layered controls, not a guarantee that all spoofed locations or compromised devices can be detected.

Filament reporting and CRM synchronization

The administration panel manages employees, devices, allowed office locations, attendance events, missions, and rejected location attempts. Reports use Jalali month selection and Tehran time, with employee filters, daily detail, work/leave/mission summaries, and CSV/XLSX exports. CRM employee mapping and attendance synchronization are optional integrations. Attendance jobs carry a stable event identifier, use retry/backoff, and record attempts and errors; end-to-end exactly-once delivery and production CRM availability are not claimed.

Validation and evidence

Focused source review and locally executed automated tests support the implementation described here.

• 81 Laravel feature tests passed with 337 assertions, including attendance transitions, geofencing, challenges, device keys, location validation, reporting, and authentication.
• Four additional Laravel unit tests passed with five assertions.
• 23 Flutter tests passed, including GPS sample resolution, challenge clock offset, device-signing channel contracts, repository payloads, and date formatting.

Scope of verification

• Local tests do not establish production scale, multi-process database concurrency behavior, or delivery to a live CRM.
• Native Android tracking and Play Integrity require platform/device validation; browser-rendered screenshots do not exercise those integrations.

Engineering challenges

• Avoiding contradictory attendance transitions when requests arrive close together.
• Distinguishing inaccurate or stale GPS samples from usable position evidence without relying only on the device clock.
• Separating a long-running Android mission service from the lifetime of the Flutter interface.
• Keeping native device-key and integrity features explicit across platforms and deployment configurations.
• Integrating attendance with CRM operations while keeping transaction completion independent from remote HTTP success.

Technical decisions

• Keep attendance state and location policy enforcement in Laravel, with employee-level locking around the write path.
• Use server challenge timing alongside raw sample evidence, rather than trusting the phone’s wall clock alone.
• Let the native Android foreground service own mission location collection and its bounded retry queue.
• Keep device and geofence enforcement configurable, record Play Integrity evidence, and distinguish implemented integrations from activated production behavior.
• Queue attendance synchronization after commit and retain integration logs for operational review.