saefulrahman/eigen-hris
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
eigen-hris/AGENTS.md
T
saefulrahman 16cbe65c62 Initialize Eigen HRIS project 
- Add .gitignore, .yarnrc.yml, and initial project metadata (AGENTS.md, DESIGN.md, package.json, Yarn lock, Tailwind, PostCSS, Next.js config, TypeScript config)
- Add CSV data files (users, employees, contracts, attendances)
- Implement API routes for auth, employees, contracts, attendances, analytics, and file upload
- Add core pages (dashboard, employees, attendances, profile, login, main layout)
- Add UI components (avatar, avatar picker, badge, button, card, input, modal, select, sidebar, navigation shell, top header)
- Add attendance features (table, clock widget, unified permit modal with file upload, upload API)
- Add employee management (contract timeline with file upload, employee form modal, employee table)
- Add dashboard widgets (leaderboard, early bird, latecomer, night owl, day status feed, date filter bar)
- Add utilities (avatar generator, analytics calculations, CSV DB layer, auth context)
- Add type definitions for auth, employee, contract, attendance, dashboard

All changes are synchronized with documentation (AGENTS.md, DESIGN.md, walkthrough).
2026-08-27 17:41:59 +07:00

194 lines
11 KiB
Markdown
Raw Permalink Blame History

# 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. |
Reference in New Issue View Git Blame Copy Permalink