# mk293822/advance-hr-management architecture

> Architecture diagram of the GitHub repository mk293822/advance-hr-management, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mk293822/advance-hr-management
- Repository: https://github.com/mk293822/advance-hr-management

## Overview

##### Project Type and Purpose
- Full-stack HR management application
- Backend: Laravel 11 (REST API + Inertia middleware)
- Frontend: React + TypeScript SPA, styled with Tailwind CSS/daisyUI
- Core use cases: employee CRUD, departments, leave requests, dashboard analytics, caching, scheduled jobs, authentication via Sanctum

##### File Structure
- app/ – Laravel MVC (Actions, Controllers, Models, Services, Jobs, Observers)
- resources/js/ – React component tree (Layouts, Pages, Components, state types)
- routes/ – auth.php, web.php, console.php define HTTP & console entrances
- config/ – environment & service configuration (cache, queue, permission)
- database/ – migrations, factories, seeders (MySQL)
- bootstrap/ & public/ – framework boot, index.php web entrypoint
- storage/ – disk persistence (sessions, cache, files)
- tests/ – PHPUnit/Pest Feature & Unit tests
- npm & composer files – build and dependency manifests

##### README Insights
- Auth: Laravel Sanctum (SPA tokens)
- Caching: Laravel cache store with automatic invalidation
- Scheduling: Console commands & queued Jobs (DailyTaskAutomation)
- UI uses Fuse.js for search, Heroicons, Zustand or Context (optional)

a. Main Components
– Browser/Client: React SPA
– Inertia Middleware (Laravel HTTP)
– API Layer: Laravel Controllers → Services → Eloquent ORM
– Persistence: MySQL / MariaDB
– Cache Store: Redis or filesystem cache driver
– Authentication: Laravel Sanctum
– Scheduler: Laravel Console Scheduler + Queue Worker (Jobs)
– Storage: Local disk / S3 (for attachments)
– Optional External Services: Email (SMTP/Mailgun), Third-party search

b. Relationships & Interactions
1. User (Browser) → HTTP(S) → Laravel/web.php + Inertia
2. Controllers validate Requests → delegate to Services
3. Services perform business logic → interact with Models (Eloquent)
4. Models read/write to MySQL & dispatch cache invalidation
5. Sanctum issues/validates tokens on protected routes
6. Scheduled tasks (Cron → scheduler) enqueue Jobs → Queue Worker processes
7. API responses (JSON/Inertia payload) → React renders UI
8. Frontend uses Axios to call REST endpoints for data-driven pages

c. Architectural Patterns & Principles
– MVC (Controllers, Models, Views/Responses)
– Service Layer (app/Services for separation of business logic)
– Repository (Eloquent as ORM)
– Jobs & Queues (async processing)
– Caching Pattern (read-through/invalidation)
– Inertia as a glue between Laravel and React
– Modular React components & layout composition

d. Key Technologies/Frameworks
– Laravel 11: routing, middleware, Sanctum, Scheduler, Cache, Queue
– Eloquent ORM: Models & migrations
– React + TypeScript: UI layers, state management
– Tailwind CSS & daisyUI: styling
– Fuse.js: fuzzy search
– Axios: HTTP client
– PHPUnit/Pest: testing
– Redis (recommended) / file cache

##### Detail Without Over-Complication
- Layer: HTTP entrypoints, Controllers, Services, Models, Data Stores, Jobs
- Related components (e.g., all Services in one green cluster)
- Cross-cutting concerns: Middleware (Inertia, Auth), Cache invalidation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Browser/Client)"
        direction TB
        ReactSPA["React SPA"]:::frontend
        Layouts["Layouts & Pages"]:::frontend
        Axios["Axios HTTP Client"]:::frontend
        Styling["Tailwind CSS & daisyUI"]:::frontend
    end

    %% Backend API Layer
    subgraph "Backend API (Laravel)"
        direction TB
        Routing["HTTP & Inertia Entrypoints"]:::backend
        Inertia["Inertia Middleware"]:::backend
        AuthC["Authentication Controllers"]:::backend
        Sanctum["Laravel Sanctum"]:::backend
        APIControllers["API Controllers"]:::backend
        Services["Service Layer"]:::backend
        Models["Eloquent ORM Models"]:::backend
        CacheCfg["Cache Configuration"]:::backend
        CacheHandler["HandleCache Action"]:::backend
    end

    %% Async & Scheduler
    subgraph "Async & Scheduler"
        direction TB
        Scheduler["Scheduler & Console Commands"]:::async
        JobsNode["DailyTaskAutomation Job"]:::async
        QueueCfg["Queue Configuration"]:::async
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        DB["MySQL / MariaDB"]:::datastore
        CacheStore["Redis / File Cache"]:::datastore
        FileStorage["File Storage (Local/S3)"]:::datastore
        Migrations["Migrations & Factories"]:::datastore
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Email["Email Service (SMTP/Mailgun)"]:::external
        Search["Third-party Search"]:::external
    end

    %% Connections
    ReactSPA -->|"HTTP(S) requests"| Routing
    ReactSPA -->|"UI Composition"| Layouts
    ReactSPA -->|"API calls via"| Axios
    ReactSPA -->|"Styles applied via"| Styling

    Routing --> Inertia
    Inertia --> AuthC
    Inertia --> APIControllers

    AuthC -->|"issue/validate tokens"| Sanctum
    Sanctum --> APIControllers

    APIControllers -->|"delegate to"| Services
    Services -->|"uses"| Models
    Services --> CacheHandler
    CacheHandler --> CacheStore

    Models -->|"read/write"| DB
    Models -->|"invalidate/read-through"| CacheStore

    Scheduler -->|"enqueue tasks"| JobsNode
    JobsNode -->|"exec business logic"| Services
    JobsNode --> QueueCfg

    Migrations --> DB

    %% External
    Services -->|"send emails via"| Email
    Services -->|"fuzzy search via"| Search
    FileStorage -->|"store attachments"| Services

    %% Click Events
    click ReactSPA "https://github.com/mk293822/advance-hr-management/blob/main/resources/js/app.tsx"
    click ReactSPA "https://github.com/mk293822/advance-hr-management/tree/main/resources/js/"
    click Layouts "https://github.com/mk293822/advance-hr-management/tree/main/resources/js/Layouts/"
    click Axios "https://github.com/mk293822/advance-hr-management/blob/main/resources/js/bootstrap.ts"
    click Styling "https://github.com/mk293822/advance-hr-management/blob/main/tailwind.config.js"
    click Styling "https://github.com/mk293822/advance-hr-management/blob/main/resources/css/app.css"
    click Routing "https://github.com/mk293822/advance-hr-management/blob/main/routes/web.php"
    click Routing "https://github.com/mk293822/advance-hr-management/blob/main/routes/auth.php"
    click Inertia "https://github.com/mk293822/advance-hr-management/blob/main/app/Http/Middleware/HandleInertiaRequests.php"
    click AuthC "https://github.com/mk293822/advance-hr-management/tree/main/app/Http/Controllers/Auth/"
    click APIControllers "https://github.com/mk293822/advance-hr-management/tree/main/app/Http/Controllers/"
    click Services "https://github.com/mk293822/advance-hr-management/tree/main/app/Services/"
    click Models "https://github.com/mk293822/advance-hr-management/tree/main/app/Models/"
    click CacheCfg "https://github.com/mk293822/advance-hr-management/blob/main/config/cache.php"
    click CacheHandler "https://github.com/mk293822/advance-hr-management/blob/main/app/Actions/HandleCache.php"
    click Scheduler "https://github.com/mk293822/advance-hr-management/blob/main/app/Console/Commands/ClearLogs.php"
    click JobsNode "https://github.com/mk293822/advance-hr-management/blob/main/app/Jobs/DailyTaskAutomation.php"
    click QueueCfg "https://github.com/mk293822/advance-hr-management/blob/main/config/queue.php"
    click FileStorage "https://github.com/mk293822/advance-hr-management/blob/main/config/filesystems.php"
    click Email "https://github.com/mk293822/advance-hr-management/blob/main/config/mail.php"
    click Migrations "https://github.com/mk293822/advance-hr-management/tree/main/database/migrations/"
    click Migrations "https://github.com/mk293822/advance-hr-management/tree/main/database/factories/"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#00838F
    classDef backend fill:#E0F2F1,stroke:#004D40
    classDef datastore fill:#FFF3E0,stroke:#E65100
    classDef external fill:#ECEFF1,stroke:#607D8B
    classDef async fill:#F3E5F5,stroke:#6A1B9A
```
