eigen-hris/AGENTS.md

AGENTS.md - Eigen HRIS Development & Agent Blueprint

1. Project Overview & System Context

Eigen HRIS is a modern, human-centric Human Resource Integration System designed to manage employee records, contract histories, daily attendance (WFO/WFH), unified leave & permit requests, and gamified analytical dashboards (such as top attendance streaks, early birds, chronic latecomers, and night owls).

The application is built on Next.js and TailwindCSS, utilizing a zero-dependency CSV-based file database for transparent, lightweight, and robust data persistence.

---

2. Technical Stack & Conventions

Core Stack

• Package Manager: Yarn (yarn add, yarn dev, yarn build)
• Framework: Next.js (App Router, Server Actions, and Route Handlers)
• Styling: TailwindCSS with bespoke design tokens, Tailwind Animate
• Icons & UI Utilities: Lucide React, clsx, tailwind-merge, date-fns / dayjs
• Typography: Plus Jakarta Sans
• Storage Layer: Flat .csv files stored in /data/*.csv, managed via a centralized Server-side Data Access Layer (Node.js fs/promises + CSV serializer/parser) with concurrency write-safety.
• Online Photo/Avatar Generator: Integration with dynamic online avatar endpoints (e.g. DiceBear API, Pravatar, Unsplash curated portraits, UI-Avatars) with instant preview and randomize capabilities.

Project Structure Blueprint

├── data/
│   ├── users.csv
│   ├── employees.csv
│   ├── employee_contracts.csv
│   └── attendances.csv
├── public/
│   └── uploads/
├── src/
│   ├── app/
│   │   ├── api/
│   │   │   ├── auth/
│   │   │   ├── employees/
│   │   │   ├── contracts/
│   │   │   ├── attendances/
│   │   │   ├── analytics/
│   │   │   └── upload/
│   │   ├── (auth)/
│   │   │   └── login/
│   │   ├── (dashboard)/
│   │   │   ├── dashboard/
│   │   │   ├── employees/
│   │   │   │   └── [id]/
│   │   │   ├── attendances/
│   │   │   └── profile/
│   │   ├── layout.tsx
│   │   └── page.tsx
│   ├── components/
│   │   ├── ui/ (Button, Input, Modal, Badge, Dropdown, Table, Card, AvatarPicker)
│   │   ├── layout/ (Sidebar, TopHeader, NavigationShell)
│   │   ├── dashboard/ (LeaderboardCard, EarlyBirdCard, LatecomerCard, NightOwlCard, DayStatusFeed)
│   │   ├── employees/ (EmployeeTable, EmployeeFormModal, ContractTimeline, OnlinePhotoPicker)
│   │   └── attendances/ (AttendanceTable, UnifiedPermitModal, ClockActionWidget, AttendanceFilterBar)
│   ├── lib/
│   │   ├── csv-db.ts (CSV CRUD operations, locking, serialization)
│   │   ├── auth.ts (Session, Cookie handling, RBAC checks)
│   │   ├── avatar.ts (Online avatar URL generator & presets)
│   │   └── analytics.ts (Aggregation logic for streaks, early bird, latecomers, night owls)
│   ├── types/
│   │   ├── auth.ts
│   │   ├── employee.ts
│   │   ├── contract.ts
│   │   ├── attendance.ts
│   │   └── dashboard.ts
│   └── styles/
│       └── globals.css
├── AGENTS.md
├── DESIGN.md
└── package.json

---

3. CSV Database Schema & Models

users.csv

Column	Type	Description
id	string (UUID)	Unique user identifier
username	string	Login username (unique)
password	string	Stored credential (hashed or plain demo password)
role	enum (superadmin, staff)	Access permission level
employee_id	string (nullable)	Associated employee ID for staff accounts
created_at	ISO string	Timestamp of user creation

employees.csv

Column	Type	Description
id	string (UUID/EMP-xxx)	Unique employee ID
nik	string	Employee Identification Number
full_name	string	Full legal name
email	string	Official work email address
phone	string	Contact phone number
department	string	Department/Division (e.g., Engineering, HR, Product, Finance, Marketing)
position	string	Job title / designation
status	enum (active, probation, resigned, terminated)	Current employment status
join_date	YYYY-MM-DD	Employment start date
work_location_default	enum (WFO, WFH, HYBRID)	Default working arrangement
photo_url	string	Generated online photo/avatar URL (Dicebear, Pravatar, Unsplash)
created_at	ISO string	Record creation timestamp
updated_at	ISO string	Last updated timestamp

employee_contracts.csv

Column	Type	Description
id	string (UUID)	Unique contract ID
employee_id	string	Foreign key referencing employees.csv
contract_number	string	Formal employment agreement reference
contract_type	enum (PKWT, PKWTT, INTERNSHIP, FREELANCE)	Contract classification
start_date	YYYY-MM-DD	Contract start date
end_date	YYYY-MM-DD (nullable)	Contract end date (null for permanent PKWTT)
salary	number	Base monthly compensation
notes	string	Specific provisions, job description remarks
document_url	string (nullable)	Reference to uploaded contract copy
created_at	ISO string	Creation timestamp

attendances.csv (Unified Attendance, Leaves, & Permits Log)

Column	Type	Description
id	string (UUID)	Attendance/Incident entry ID
employee_id	string	Foreign key referencing employees.csv
date	YYYY-MM-DD	Calendar date of the record
type	enum (PRESENT, SICK, ANNUAL_LEAVE, PERMIT, LATE_PERMIT, EARLY_LEAVE_PERMIT, OFFICIAL_TRAVEL)	Record classification
work_mode	enum (WFO, WFH, OFF)	Work venue mode
clock_in	HH:mm:ss (nullable)	Clock-in time
clock_out	HH:mm:ss (nullable)	Clock-out time
duration_minutes	number (nullable)	Total recorded working minutes
late_minutes	number (default: 0)	Minutes clocked in after designated work start (e.g. 09:00)
status	enum (PENDING, APPROVED, REJECTED, CONFIRMED)	Approval status for permits/leaves
reason_or_notes	string	Activity note, permit justification, or doctor note details
attachment_url	string (nullable)	Proof image/document reference
created_at	ISO string	Submission timestamp

---

4. Feature Specifications & Workflows

4.1 Authentication & RBAC

• Login: Simple username & password form.
• Roles:
  • Superadmin: Full access to CRUD employees, manage contract history, review and approve/reject leave/permit requests, override attendance logs, and access company-wide analytics.
  • Staff: Limited to personal clock-in/out, personal leave/permit submissions, viewing own profile and contract history, and viewing the company leaderboard.

4.2 Employee & Contract Management (with Online Photo Generator)

• Employee Directory: Search by name, NIK, department, and filter by status.
• Online Photo Generator:
  • When creating or editing an employee, users can type a seed or click "Generate New Avatar" to fetch a dynamic portrait URL (e.g. https://api.dicebear.com/7.x/lorelei/svg?seed=..., https://i.pravatar.cc/300?u=..., or curated Unsplash professional portraits).
  • Live preview in modal before saving.
• Contract Timeline: On employee detail/edit view, superadmins can view chronological contract history (e.g. Internship → PKWT 1 → PKWT 2 → PKWTT) and append new contracts.

4.3 Unified Attendance & Incident Management

• Unified Log: A single centralized table aggregating standard attendance (clock-in / clock-out) and incidents (sakit, cuti, izin terlambat, izin pulang cepat, dinas luar).
• Staff Actions:
  • One-click Clock In / Clock Out (with WFO/WFH toggle).
  • Submit request modal for Sick Leave, Annual Leave, Late Permission, or Early Checkout with date picker, reason, and optional attachment.
• Superadmin Actions:
  • Quick action buttons to approve or reject pending requests.
  • Manual entry creation or modification.

4.4 Gamified Analytics Dashboard

• Date Range Filters:
  • Preset filters: This Month, Last Month, Last 30 Days, or Custom Date Range (From - To).
• Gamification Cards & Leaderboard:
  • Top 5 "Si Paling Rajin" (Streak Champions): Ranked by highest number of present days with zero unexcused lates in the selected date range.
  • "Si Paling Pagi" (The Early Bird): Employee with the earliest average clock-in time.
  • "Si Paling Telat" (The Chronic Snoozer): Employee with the highest cumulative late minutes.
  • "Si Paling Pulang Malam" (The Night Owl): Employee with the latest average clock-out time.
• Daily Status Feed (Filter by Today, Yesterday, Tomorrow):
  • Instant breakdown: Present (WFO/WFH count), On Leave (Cuti), Sick (Sakit), Late (Izin Telat), and Upcoming scheduled leaves for tomorrow.

---

5. Agent Guidelines & Coding Standards

1. Mandatory Documentation Sync (Rule #1): Any modification, architectural change, new feature, schema alteration, or workflow update MUST be immediately recorded in both AGENTS.md and DESIGN.md alongside code changes.
2. CSV Concurrency & Integrity: All write operations must be atomic and handle read-modify-write cycles safely to avoid race conditions.
3. Strict Typing: All data models must have TypeScript definitions in src/types/. Validate form inputs with clean validation routines.
4. Design Conformity: Implement UI strictly in accordance with DESIGN.md using the brand palette, Plus Jakarta Sans typography, and modern micro-interactions.
5. Anti-AI-Slop Principle: Avoid generic filler layouts. Use crisp typography, clear spatial hierarchy, purposeful badges, and intuitive date filters.

---

6. Changelog & Project Evolution Log

Date	Author / Agent	Changes & Notes
2026-08-27	System / Antigravity	Initial blueprint creation for Eigen HRIS: CSV database schemas, online photo generator (photo_url), gamified dashboard analytics, and mandatory documentation synchronization rule.
2026-08-27	User / Antigravity	Set Yarn as the designated package manager for dependency management, builds, and development workflow.
2026-08-27	System / Antigravity	Full implementation executed: Next.js App Router codebase, CSV database layer (users.csv, employees.csv, employee_contracts.csv, attendances.csv), online avatar picker (Dicebear, Pravatar, Unsplash, UI-Avatars), gamified leaderboard cards & highlights, unified attendance table, contract timeline, and role-based authentication. Built successfully with 0 errors.
2026-08-27	User / Antigravity	Implemented multipart image/document upload API (/api/upload) saving to public storage (/public/uploads/) with instant preview and download buttons across tables and permit modals.