PeopleSync — Employee Attendance System (MVP)

PeopleSync is a mobile & web-based employee attendance application designed as an HRIS MVP with a focus on data accuracy, auditability, and backend scalability.

🚀 Key Features

✅ Implemented (Admin Panel - Filament v4)

Kelola Karyawan (Employee Management)

Menu	Description	Status
Data Karyawan	Employee CRUD with department assignment, soft delete support	✅

Kelola Kehadiran (Attendance Management)

Menu	Description	Status
Kehadiran Harian	Daily attendance with manual entry, late/early detection	✅
Review Kehadiran (Harian)	Daily attendance review with permission-based access	✅
Review Kehadiran (Bulanan)	Monthly attendance review/recap	✅
Hari Libur	Holiday management for attendance calculation	✅
Jadwal Kerja	Work schedule per day of week (pre-seeded, edit only)	✅
Lokasi Kehadiran	Geofencing locations with interactive map & radius	✅

Other Modules

Menu	Description	Status
Department	Department hierarchy with parent-child structure	✅
Leave	Leave/time-off requests with approval workflow	✅
Overtime	Overtime requests with approval workflow	✅

Pengaturan (Settings)

Menu	Description	Status
Data Admin	Admin user management (role-based visibility)	✅

🔜 Planned (Mobile App - Flutter)

Feature	Description
Clock-in / Clock-out	GPS & photo-based attendance via mobile
Attendance History	View personal attendance records
Leave Request	Submit leave/time-off requests
Overtime Request	Submit overtime requests

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    Flutter (Mobile App)                      │
│                  people-sync-mobile [Planned]                │
└─────────────────────────────────────────────────────────────┘
                              ↓ HTTPS + JWT
┌─────────────────────────────────────────────────────────────┐
│              Laravel 12 API (JWT + Spatie RBAC)             │
│                   /api/v1/* [Implemented]                    │
├─────────────────────────────────────────────────────────────┤
│               Filament v4 Admin Panel                        │
│                   /admin [Implemented]                       │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                        PostgreSQL                            │
│                      [Implemented]                           │
└─────────────────────────────────────────────────────────────┘

Repository Structure

Repository	Purpose	Status
`people-sync`	Backend API + Admin Panel (Laravel + Filament)	✅ Current
`people-sync-mobile`	Mobile App for Employees (Flutter)	🔜 Planned

📡 Mobile API (v1)

Base URL: /api/v1

Authentication

Method	Endpoint	Description
`POST`	`/auth/login`	Login with email & password
`GET`	`/auth/me`	Get current user + employee data
`POST`	`/auth/refresh`	Refresh JWT token
`POST`	`/auth/logout`	Invalidate token

Attendance

Method	Endpoint	Description
`GET`	`/attendances`	List attendance history (paginated)
`GET`	`/attendances/today`	Get today's attendance status
`GET`	`/attendances/summary`	Monthly summary
`POST`	`/attendances/clock-in`	Clock in with GPS + photo
`POST`	`/attendances/clock-out`	Clock out with GPS + photo

Leave

Method	Endpoint	Description
`GET`	`/leaves`	List my leave requests
`POST`	`/leaves`	Submit new leave request
`GET`	`/leaves/{id}`	Get leave detail
`DELETE`	`/leaves/{id}`	Cancel pending leave

Overtime

Method	Endpoint	Description
`GET`	`/overtimes`	List my overtime requests
`POST`	`/overtimes`	Submit new overtime request
`GET`	`/overtimes/{id}`	Get overtime detail
`DELETE`	`/overtimes/{id}`	Cancel pending overtime

Supporting Data

Method	Endpoint	Description
`GET`	`/locations`	Get active attendance locations
`GET`	`/holidays`	Get holidays (for calendar)
`GET`	`/work-schedules`	Get work schedule config

📄 Full API specification: docs/api/api-spec.md

🎯 Key Architectural Decisions

Stateless JWT authentication — Token-based API auth
Server-side RBAC — Roles & permissions resolved server-side using Spatie
Separation of User vs Employee — User for auth, Employee for business data
Soft delete semantics — With partial unique indexes for data integrity
Strong database constraints — Over application-level trust
Geofencing support — Haversine formula for location validation

🔐 Authentication & Authorization

Aspect	Implementation
Auth Method	JWT (tymon/jwt-auth)
RBAC	Spatie Laravel Permission
Role Resolution	Server-side (not embedded in token)
Soft-deleted Users	Treated as inactive
Admin Panel Auth	Filament built-in

📊 Database Schema (Implemented)

Core Tables

users ──────────┐
                ├── employees ─── departments (self-referential)
                │       │
                │       ├── attendances
                │       ├── leaves
                │       └── overtimes
                │
permission_tables (Spatie)

Additional Tables

Table	Purpose
`work_schedules`	Work hours per day of week
`holidays`	Public holidays for attendance calculation
`locations`	Geofencing with lat/lng/radius

Key Indexes & Constraints

-- Partial unique index for soft delete
CREATE UNIQUE INDEX users_email_unique ON users(email) WHERE deleted_at IS NULL;
CREATE UNIQUE INDEX employees_number_unique ON employees(employee_number) WHERE deleted_at IS NULL;

-- Attendance lookup optimization
CREATE INDEX attendances_employee_date ON attendances(employee_id, date);

🛠️ Tech Stack

Layer	Technology	Version
Backend	Laravel	12.x
Database	PostgreSQL	-
Auth (API)	JWT (tymon/jwt-auth)	2.x
Auth (Admin)	Filament	4.x
RBAC	Spatie Laravel Permission	6.x
Admin UI	Filament	4.x
Mobile	Flutter	Planned
Cache	Redis	Planned

✨ Filament v4 Highlights

Custom Components

MapPicker — Interactive Leaflet map with radius picker for geofencing locations

Features Used

Modern Schema patterns (live(), visible(), dehydrate hooks)
Navigation groups with Indonesian labels
Permission-based menu visibility
Soft delete handling in queries
Custom table filters with raw PostgreSQL queries

🧮 Attendance Logic

Attendance Record (State)

One record per employee per day
Tracks: clock_in_at, clock_out_at, source, notes
Auto-calculated: is_late, late_duration_minutes, is_early_leave

Source Tracking

Source	Description
`mobile`	Clock via mobile app (planned)
`manual`	Manual entry by HR/Admin

Status Types (for Review)

Status	Label	Color
Present	Hadir	Success
Absent	Tidak Hadir	Danger
On Leave	Cuti/Izin	Info
Weekend	Akhir Pekan	Gray
Holiday	Libur	Warning
Not Yet	Belum Tiba	Gray

🗓️ Work Schedule System

Pre-seeded 7-day schedule (Sunday = 0, Saturday = 6)
Configurable: is_working_day, work_start_time, work_end_time
Used for late/early leave calculation
Cannot create/delete — Only edit existing schedules

📍 Geofencing (Location)

Features

Interactive map picker with search
Configurable radius (10m - 5000m)
Haversine formula for distance calculation
Active/inactive status

Methods Available

$location->isWithinRadius($lat, $lng);     // Check if coordinate is within radius
$location->calculateDistance($lat, $lng);  // Get distance in meters
Location::findNearest($lat, $lng);         // Find nearest active location
Location::findContaining($lat, $lng);      // Find all locations containing point

📋 Roadmap

✅ MVP (Current - Implemented)

Authentication (JWT + Filament)
RBAC with Spatie Laravel Permission
Employee & Department management
Daily attendance with manual entry
Attendance review (daily & monthly)
Leave & overtime management with approval
Work schedule configuration
Holiday management
Geofencing locations with map picker

🔜 Next Phase

Mobile app (Flutter) with clock-in/out
Attendance Logs (immutable audit trail)
Photo capture for attendance proof
Push notifications

📅 Post-MVP

💡 Why This Project?

This project demonstrates:

Aspect	What It Shows
Backend Architecture	Clean separation of concerns, service patterns
Database Design	PostgreSQL-specific features, proper indexing
Security	JWT + RBAC, server-side permission resolution
Modern Stack	Laravel 12 + Filament v4 latest patterns
Business Logic	Real-world HR/attendance rules
Custom Components	Filament custom form components (MapPicker)

📁 Project Structure

people-sync/
├── backend/
│   ├── app/
│   │   ├── Enums/                  # AttendanceSource, AttendanceStatus, DayOfWeek
│   │   ├── Filament/
│   │   │   ├── Forms/Components/   # Custom components (MapPicker)
│   │   │   └── Resources/          # Admin panel resources
│   │   ├── Http/
│   │   │   ├── Controllers/
│   │   │   │   └── Api/V1/         # Mobile API controllers
│   │   │   ├── Middleware/         # JWT, ActiveUser, EmployeeOnly
│   │   │   ├── Requests/Api/V1/    # Form request validation
│   │   │   └── Resources/Api/V1/   # API response transformers
│   │   ├── Models/
│   │   └── Services/
│   ├── database/migrations/
│   ├── docs/api/                   # API specification
│   └── routes/
│       ├── api.php                 # Mobile API routes (/api/v1/*)
│       └── web.php                 # Admin panel routes
└── docs/
    ├── api/                        # API documentation
    └── v2/                         # PRD & migration specs

🏃 Getting Started

# Clone & setup
cd backend
composer install
cp .env.example .env
php artisan key:generate
php artisan jwt:secret

# Database
php artisan migrate
php artisan db:seed

# Development
composer dev

# Running project
php artisan serve

# Access Filament Admin Panel
# Default: http://localhost:8000/admin

📝 Final Note

PeopleSync is intentionally designed as a production-minded MVP, focusing on:

✅ Correctness — Strong data validation & constraints
✅ Auditability — Source tracking, soft deletes
✅ Extensibility — Ready for payroll, multi-tenant, and more

Rather than feature count, the priority is real-world quality.

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
backend		backend
docs		docs
README.md		README.md

DwikyAnggarda/people-sync

Folders and files

Latest commit

History

Repository files navigation