# babar88sgd/hr_vfg architecture

> Architecture diagram of the GitHub repository babar88sgd/hr_vfg, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/babar88sgd/hr_vfg
- Repository: https://github.com/babar88sgd/hr_vfg

## Overview

##### Project type and purpose
- This is a Frappe/ERPNext “app” (Python package) named hr_vfg that plugs into the Frappe framework to provide a full HR management module (“HR VentureForce Global”).
- It defines custom DocTypes (models), client-side scripts (JS), server‐side controllers (Python), report generators, event hooks, templates, and integration connectors (e.g. attendance machines, e-mail).

##### Main components
- **Frappe Application Server** (Python + WSGI)
- HTTP request router, ORM, scheduler, background workers
- **Frappe Web Frontend** (JS, HTML templates, Jinja)
- Browser‐based UI, form views, list views, reports
- **hr_vfg App Module**
- `hooks.py` – event hooks, scheduler tasks
- `hr_ventureforce_global` – customizations
– `custom/*.json` – custom data fixtures
– `doctype/*` – DocType definitions (JSON), Python controllers, JS client scripts, tests
– `report/*` – report definitions (JSON), Python report scripts, JS frontends, HTML templates
– `workspace/` – workspace definitions
– override scripts (`*_override.py`)
- `templates/` – page templates
- `www/` – website pages
- **Database** (MariaDB/MySQL)
- **Cache / Queue** (Redis)
- **External Services**
- Attendance machine APIs (via `attendance_connector.py`)
- SMTP email server (via Frappe mail integration)

##### Relationships & data flows
- **Browser ↔ HTTP ↔ Frappe Server**
- User actions (forms, report requests) go to the server
- **Frappe Server ↔ DB**
- Reads/Writes DocType tables defined by hr_vfg
- **Frappe Scheduler & Workers ↔ hr_vfg hooks**
- Periodic tasks (attendance backups, report generation)
- Event hooks trigger on document events
- **Frappe Server ↔ Redis**
- Job queue for background processing
- **hr_vfg ↔ External Attendance Machine**
- Poll or push data via connector
- **hr_vfg ↔ SMTP**
- Send notifications, payslip emails

##### Architectural patterns & design principles
- **Modular plugin architecture**: hr_vfg sits on top of Frappe core via `hooks.py`.
- **Model‐View‐Controller** (via DocType JSON = model; Python & JS controllers; Jinja/UI views).
- **Event-driven**: custom logic tied to document lifecycle events and scheduler.
- **Separation of concerns**:
- Data (DocType JSON + database)
- Business logic (Python controllers, schedulers)
- Presentation (JS, HTML templates)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        Browser["User Browser"]:::external
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        subgraph "Frappe Core"
            direction TB
            Server["Frappe Application Server"]:::frappecore
            Scheduler["Scheduler & Workers"]:::frappecore
        end
        subgraph "hr_vfg App"
            direction TB
            Config["Config Module"]:::hrvfg
            Hooks["Hooks & Scheduler Tasks"]:::hrvfg
            Fixtures["Custom Data Fixtures"]:::hrvfg
            Doctypes["DocType Definitions & Controllers"]:::hrvfg
            ClientScripts["Client-Side Scripts (JS)"]:::hrvfg
            Tests["DocType Event Hooks & Tests"]:::hrvfg
            Reports["Report Definitions & Generators"]:::hrvfg
            ReportFront["Report Frontend (JS & Templates)"]:::hrvfg
            Workspace["Workspace Definitions"]:::hrvfg
            Templates["Page Templates"]:::hrvfg
            Pages["Website Pages"]:::hrvfg
            Connector["Attendance Machine Connector"]:::hrvfg
            Email["Email Integration Scripts"]:::hrvfg
            Backup["Attendance Backup Scheduler"]:::hrvfg
            PayrollOverride["Payroll Entry Override"]:::hrvfg
            SalaryOverride["Salary Slip Override"]:::hrvfg
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DB["MariaDB/MySQL Database"]:::data
        Redis["Redis (Cache/Queue)"]:::data
    end

    %% Integration Layer
    subgraph "Integration Layer"
        direction TB
        AttendanceAPI["Attendance Machine API"]:::external
        EmailService["SMTP Email Service"]:::external
    end

    %% Flows
    Browser -->|"HTTP Request"| Server
    Server -->|"ORM Queries"| DB
    Server -->|"Job Queue"| Redis
    Server -->|"Triggers"| Hooks
    Scheduler -->|"Periodic Tasks"| Hooks
    Hooks -->|"Custom Logic"| Doctypes
    Hooks -->|"Backup Job"| Backup
    Doctypes -->|"Controllers"| Connector
    Connector -->|"Poll/Push Data"| AttendanceAPI
    Email -->|"Send Emails"| EmailService
    Reports -->|"Run Reports"| ReportFront
    ReportFront -->|"Render Templates"| Templates
    Server -->|"Load Templates"| Templates
    Server -->|"Serve Pages"| Pages
    Server -->|"Use Fixtures"| Fixtures
    Server -->|"Load Workspace"| Workspace

    Browser -->|"Interact"| ClientScripts
    ClientScripts --> Server

    %% Click Events
    click Config "https://github.com/babar88sgd/hr_vfg/blob/main/hr_vfg/config/desktop.py"
    click Hooks "https://github.com/babar88sgd/hr_vfg/blob/main/hr_vfg/hooks.py"
    click Fixtures "https://github.com/babar88sgd/hr_vfg/blob/main/hr_vfg/hr_ventureforce_global/custom/*.json"
    click Doctypes "https://github.com/babar88sgd/hr_vfg/tree/main/hr_vfg/hr_ventureforce_global/doctype/"
    click ClientScripts "https://github.com/babar88sgd/hr_vfg/blob/main/hr_vfg/hr_ventureforce_global/doctype/attendance_logs/attendance_logs.js"
    click Tests "https://github.com/babar88sgd/hr_vfg/blob/main/hr_vfg/hr_ventureforce_global/doctype/absent_adjustment_with_holiday/test_absent_adjustment_with_holiday.py"
    click Reports "https://github.com/babar88sgd/hr_vfg/tree/main/hr_vfg/hr_ventureforce_global/report/"
    click ReportFront "https://github.com/babar88sgd/hr_vfg/blob/main/hr_vfg/hr_ventureforce_global/report/attendance_register/attendance_register.js"
    click ReportFront "https://github.com/babar88sgd/hr_vfg/blob/main/hr_vfg/hr_ventureforce_global/report/daily_employee_attendance_d_2/daily_employee_attendance_d_2_pdf.html"
    click Workspace "https://github.com/babar88sgd/hr_vfg/blob/main/hr_vfg/hr_ventureforce_global/workspace/hr_addon/hr_addon.json"
    click Templates "https://github.com/babar88sgd/hr_vfg/tree/main/hr_vfg/templates/pages/"
    click Pages "https://github.com/babar88sgd/hr_vfg/tree/main/hr_vfg/www/"
    click Connector "https://github.com/babar88sgd/hr_vfg/blob/main/hr_vfg/hr_ventureforce_global/doctype/employee_attendance/attendance_connector.py"
    click Email "https://github.com/babar88sgd/hr_vfg/blob/main/hr_vfg/hr_ventureforce_global/doctype/employee_attendance/attendance_email.py"
    click Backup "https://github.com/babar88sgd/hr_vfg/blob/main/hr_vfg/hr_ventureforce_global/doctype/employee_attendance/emp_att_backup.py"
    click PayrollOverride "https://github.com/babar88sgd/hr_vfg/blob/main/hr_vfg/hr_ventureforce_global/payroll_entry_override.py"
    click SalaryOverride "https://github.com/babar88sgd/hr_vfg/blob/main/hr_vfg/hr_ventureforce_global/salary_slip_override.py"

    %% Styles
    classDef frappecore fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef hrvfg fill:#d4edda,stroke:#333,stroke-width:1px;
    classDef data fill:#fff3cd,stroke:#333,stroke-width:1px;
    classDef external fill:#f8d7da,stroke:#333,stroke-width:1px;
```
