xXx

Hexid M1n1 5h3ll MobiLe

home/emberdemos/corehr_app/current/docs/_[ Writable ]

File:/home/emberdemos/corehr_app/current/docs/PROJECT_BLUEPRINT.md

# CoreHR Project Blueprint

## Table of Contents

1. [Executive Summary & Vision](#1-executive-summary--vision)
2. [Technology Stack](#2-technology-stack)
3. [Development Standards & Practices](#3-development-standards--practices)
4. [Design System & Guidelines](#4-design-system--guidelines)
5. [System Architecture](#5-system-architecture)
6. [Phased Implementation Strategy](#6-phased-implementation-strategy)

---

## 1. Executive Summary & Vision

### 1.1 Vision Statement

This proposal outlines the "CoreHR" project, a strategic initiative to re-engineer the Frappe HR system using the contemporary Laravel (VILT) stack. The project's core objective is to deliver a Human Resource Management System (HRMS) Minimum Viable Product (MVP) that not only replicates but significantly improves upon existing functionalities, setting a new benchmark for internal operational efficiency and presenting a compelling value proposition for potential investors.

### 1.2 Key Focus Areas

A key focus is the precise incorporation of client-provided payroll formulas and an extensive suite of HR, Payroll, and Government reports, ensuring stringent compliance with local regulations, particularly those relevant to the Philippines.

### 1.3 Technology Strategy

The selection of the VILT stack—comprising Vue.js for dynamic user interfaces, Inertia.js for seamless Single Page Application (SPA) experiences, Laravel for a robust backend, and Tailwind CSS for flexible, modern styling—is a deliberate choice. This combination offers a significant competitive advantage by enhancing development efficiency, delivering a superior user experience, and ensuring long-term maintainability and scalability.

### 1.4 Expected Outcomes

The anticipated outcome is a highly efficient, intuitive, and future-proof HRMS. This system is designed to address the identified limitations of current HR solutions, moving beyond basic record-keeping to enable strategic workforce management. By leveraging the strengths of the VILT stack, CoreHR aims to streamline HR processes, reduce administrative overhead, improve data accuracy, and foster a more engaging employee experience, thereby demonstrating strong market potential and a clear path to profitability for stakeholders.

---

## 2. Technology Stack

This document serves as the single source of truth for the technology stack, packages, and services used in the CoreHR project. Our stack is based on the official Laravel 12 VILT Starter Kit to ensure maximum compatibility and long-term support.

### 2.1 Core Framework & Environment

- **PHP:** 8.3+
- **Laravel Framework:** 12.x
- **Node.js:** 20.x (LTS)
- **Development Environment:** Docker Desktop with WSL 2, managed via **Laravel Sail**
- **Database:** MySQL 8.0+ (via Laravel Sail)
- **Cache / Queues:** Redis (via Laravel Sail)

### 2.2 Backend (Laravel)

- **Core:** Laravel 12.x
- **Authentication:** Built-in Starter Kit authentication
- **Authorization:** Spatie's `laravel-permission` (for advanced RBAC)
- **Live Validation:** **Laravel Precognition**
- **File Storage:** Laravel Filesystem (local in dev, cloud in prod)
- **Code Quality:**
  - **Laravel Pint:** For PSR-12 code style enforcement
  - **Larastan:** For static analysis
- **Testing:**
  - **Pest:** For backend feature and unit tests
  - **Laravel Dusk:** For end-to-end browser automation testing

### 2.3 Frontend (VILT Stack)

- **Core:** **Vue.js 3.x**
- **Language:** **TypeScript**
- **Framework Bridge:** **Inertia.js 2.x**
- **Build Tool:** **Vite**
- **UI Component Library:** **shadcn-vue**. Components will be added via `npx shadcn-vue@latest add ...` as needed
- **CSS Framework:** **Tailwind CSS 3.x** (as the foundation for shadcn-vue)
- **Key Libraries:**
  - **State Management:** **Pinia** (official Vue standard)
  - **Form Handling:** **`laravel-precognition-vue-inertia`** for forms with live validation
  - **Data Tables:** **`@tanstack/vue-table`** for all data grids
  - **Date & Time:** `day.js`
  - **Charting/Graphs:** `ApexCharts.js` (with a Vue wrapper)
  - **Icons:** `lucide-vue-next`
- **Testing:**
  - **Vitest:** For Vue component unit tests

### 2.4 DevOps & CI/CD

- **Platform:** GitHub
- **Automation:** GitHub Actions
- **Containerization:** Docker

---

## 3. Development Standards & Practices

This document outlines the coding standards and best practices for the CoreHR project to ensure code quality, consistency, and maintainability.

### 3.1 General Principles

- **Language:** All code, comments, and documentation will be written in English
- **TDD:** Test-Driven Development is the preferred methodology. Write a failing test before writing the implementation
- **KISS (Keep It Simple, Stupid):** Prefer simple, readable solutions over complex, clever ones
- **DRY (Don't Repeat Yourself):** Abstract reusable logic into services, traits, or components

### 3.2 PHP / Laravel (Backend)

- **Code Style:** We will strictly adhere to the **PSR-12** standard, enforced automatically by **Laravel Pint**. Run `sail pint` before committing
- **Naming Conventions:**
  - Controllers: `SingularController` (e.g., `EmployeeProfileController`)
  - Models: `Singular` (e.g., `EmployeeLoan`)
  - Migrations: `verb_table_name_table` (e.g., `create_employee_loans_table`)
  - Service Classes: `SingularNounService` (e.g., `PayrollCalculationService`)
  - Form Requests: `ActionNounRequest` (e.g., `StoreEmployeeRequest`)
  - Routes: kebab-case (e.g., `my-profile/payslips`)
- **Architecture:**
  - **Fat Models, Skinny Controllers:** Business logic should reside in Models or dedicated Service Classes, not controllers. Controllers are for handling HTTP requests and responses
  - **Service Classes:** For complex, multi-step business logic (e.g., calculating a payslip, processing a loan application), create a dedicated service class in `app/Services/`
  - **Form Requests:** All request validation must happen in dedicated Form Request classes, not in the controller method
  - **Blade/Vue Communication:** All data passed from Laravel to Vue must be done through Inertia props in the controller. Avoid using `@json` directives
- **Database:**
  - All database interactions must go through the Eloquent ORM. No raw SQL queries without explicit approval for performance-critical reasons
  - Use migrations for all schema changes. Never edit the schema directly

### 3.3 JavaScript / Vue.js (Frontend)

- **Component Structure:** Use Vue 3's `<script setup>` syntax for all new components
- **Naming Conventions:**
  - Components: `PascalCase.vue` (e.g., `EmployeeCard.vue`, `LeaveApplicationForm.vue`)
- **State Management:**
  - Local component state should be managed with `ref()` or `reactive()`
  - Cross-component or global state (e.g., authenticated user, notifications) must be managed via a **Pinia** store
- **Props:** Define props explicitly with types and validation using `defineProps`
- **Styling:**
  - All styling must be done with **Tailwind CSS utility classes**.
  - Avoid writing custom CSS files unless absolutely necessary for a unique component that cannot be styled with utilities.
  - Create reusable UI elements (buttons, inputs, modals) as dedicated Vue components to ensure consistency.
- **Standard UI Patterns:**
  - **Data Grids:** All list views (e.g., index pages) must use the reusable `DataTable.vue` component powered by **TanStack Table**. This provides consistent client-side filtering, sorting, and pagination.
  - **CRUD Operations:**
    - For simple entities (2-4 fields), CRUD actions (Create/Edit) must be handled within a **`Dialog` (modal)** on the index page. This avoids page reloads and keeps the user in context.
    - Dedicated `Create.vue` and `Edit.vue` pages should be reserved for complex entities that require multi-step or extensive forms (e.g., Employee Onboarding).
  - **Form Structure:** All forms, whether in a dialog or on a dedicated page, must use the **`shadcn-vue` Form components** (`FormField`, `FormItem`, `FormLabel`, etc.) for accessibility and standardized validation message display.

### 3.4 Git & Commits

- **Branching:** Use a feature-branching model (e.g., `feature/P1-employee-profiles`, `fix/login-bug`)
- **Commit Messages:** Follow the **Conventional Commits** specification. This helps in generating automated changelogs
  - Examples: `feat: add loan application form`, `fix: correct overtime calculation`, `docs: update coding standards`, `refactor: simplify payroll service`

---

## 4. Design System & Guidelines

This document establishes the design principles and visual language for the CoreHR application, ensuring a consistent, high-quality user experience.

### 4.1 Core Principles

- **Vibe:** Modern, Clean, and Minimalist. The interface should feel uncluttered, intuitive, and efficient. We prioritize clarity and ease of use over decorative elements
- **Density:** Balanced. The UI will provide enough white space to be comfortable and reduce cognitive load, but will remain efficient for completing HR tasks. Data tables and forms will be well-structured without feeling cramped.
- **Layout:** The primary application layout will be a **Sidebar Layout**. This provides persistent, easy-to-access navigation suitable for the various modules of the HR system.
- **Workflow:** Prioritize **context-aware workflows**. Simple Create/Edit operations should occur in modals/dialogs to keep the user on the primary screen, minimizing full-page navigation.

### 4.2 Color Palette

- **Primary Brand Color:** `#eb2729` (A vibrant, confident red)
- **Implementation:** This primary color will be configured as the `primary` color in our Tailwind CSS theme (`tailwind.config.js`). It will be used for:
  - Primary buttons
  - Active navigation links
  - Focus rings on interactive elements
  - Key headers or highlights
- **Palette Generation:** We will use a tool (like <https://uicolors.app/create>) to generate a full palette (shades from 50 to 900) based on our primary red to ensure harmonious and accessible color variations for hover states, borders, and secondary text
- **System Colors:**
  - **Neutral:** A cool gray scale (e.g., Tailwind's default `slate` or `gray`)
  - **Success:** Green
  - **Warning:** Amber/Yellow
  - **Error:** A distinct, darker red (to differentiate from the primary brand red)
- **Themeability:** The architecture will be designed to allow the primary brand color to be easily changed in the future for different clients by updating a single configuration value in `tailwind.config.js`

### 4.3 Typography

- **Font Family:** We will use the default modern, sans-serif font provided by the Laravel VILT starter kit (likely **Inter**). This ensures high legibility on screens
- **Hierarchy:** A clear and consistent typographic scale will be used to differentiate headings (h1, h2, h3), body text, and UI labels. This will be defined in the Tailwind configuration

### 4.4 Components & Interactivity

- **Component Library:** All UI components will be built using **shadcn-vue**. We will strictly adhere to its design language to maintain visual consistency
- **Interactivity:** User feedback will be clear and immediate, but subtle
  - Smooth, quick transitions on interactive elements
  - Use of toast notifications for success/error messages after an action is performed
  - Loading states (spinners, skeleton loaders) will be used for any action that takes more than 200ms to complete

### 4.5 Accessibility (WCAG)

- All color combinations (text on background) must meet WCAG AA contrast ratios
- All interactive elements must have clear focus states
- Forms will have proper labels associated with their inputs

---

## 5. System Architecture

### 5.1 High-Level Overview

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Vue.js SPA    │    │   Laravel API    │    │   MySQL DB      │
│   (Frontend)    │◄──►│   (Backend)      │◄──►│   (Data Layer)  │
│                 │    │                  │    │                 │
│ • Inertia.js    │    │ • Controllers    │    │ • Eloquent ORM  │
│ • Pinia State   │    │ • Services       │    │ • Migrations    │
│ • shadcn-vue    │    │ • Form Requests  │    │ • Seeders       │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌──────────────────┐
                    │   Redis Cache    │
                    │   & Queue        │
                    └──────────────────┘
```

### 5.2 Data Model Principles

- **ORM:** All database interactions must use the Eloquent ORM
- **Schema:** All schema changes must be managed through Migrations
- **Security:** Sensitive data will be handled with appropriate encryption and access controls

---

## 6. Phased Implementation Strategy

### Phase 1: Foundation & Organizational Structure (Months 1-2)

**Goal:** Establish the project's technical foundation and build the core modules for managing company structure and user access.

**Deliverables:**

- Project setup complete (VILT stack, Sail, Git, CI)
- `spatie/laravel-settings` installed and a basic "Settings" page created
- `spatie/laravel-permission` installed; Roles (Super Admin, HR Admin, Employee) and a basic role-assignment UI
- **Modules:** Departments & Designations (CRUD functionality)

**Success Metric:** Admins can define the company's organizational structure.

### Phase 2: Core Employee Management (Months 3-4)

**Goal:** Build the central employee profile and self-service capabilities.

**Deliverables:**

- **Module:** Comprehensive Employee Management (CRUD for profiles)
- Integration of `shadcn-vue` for UI components
- Secure document uploads per employee
- A read-only "My Profile" page for employees

**Success Metric:** A complete employee database can be managed, and employees can view their own information.

### Phase 3: Attendance & Leave Management (Months 5-6)

**Goal:** Implement time tracking and absence management.

**Deliverables:**

- **Modules:** Holidays, Shifts, Attendance Tracking (web clock-in/out), and Leave Management (types, policies, application/approval workflow)
- Approved leave automatically creates "On Leave" attendance records

**Success Metric:** Employee work hours and absences are accurately tracked.

### Phase 4: Core Payroll Engine (Months 7-9)

**Goal:** Implement the complex, Philippines-specific payroll calculation engine.

**Deliverables:**

- **Modules:** Pay Periods, Employee Pay Rates
- Backend services to process attendance into categorized time entries (Regular, OT, ND, etc.)
- The core `PayrollCalculationService` to compute gross-to-net pay based on all client formulas
- Payslip generation with employee view/download

**Success Metric:** Accurate, compliant payslips can be generated for all employee types.

### Phase 5: Financial & Supporting HR Modules (Months 10-12)

**Goal:** Add loan, expense, and communication modules.

**Deliverables:**

- **Modules:** Employee Loan Management (with payroll deduction), Expense Reimbursement, News & Announcements, Company Policies

**Success Metric:** The system handles key financial workflows and internal communications.

### Phase 6: Advanced Features, Reporting & Launch (Ongoing)

**Goal:** Deliver advanced reports, automation, and prepare for production.

**Deliverables:**

- **Modules:** Comprehensive Reporting (including all required Government Reports: SSS, BIR, etc.), Dashboards with analytics
- Automation of routine tasks (leave accrual, reminders) via Laravel Scheduler
- Security Hardening (2FA, Audit Trails)
- User Acceptance Testing (UAT) and final documentation
- Production deployment

**Success Metric:** The system is live, stable, and delivering measurable value to the business.

Your Access Expired	Date. in : 14-12-2025
Regist : 09-12-2024	Expired : 01-12-2027