# 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](./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. |