# horilla-opensource/horilla architecture

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

- Interactive diagram: https://gitdiagram.com/horilla-opensource/horilla
- Repository: https://github.com/horilla-opensource/horilla

## Overview

Based on a careful review of the repository file tree and the README, Horilla is a full‐stack HRMS (Human Resource Management System) built on Django. It is a monolithic yet highly modular Django application where each domain (such as employee management, attendance, leave, payroll, recruitment, onboarding/offboarding, helpdesk, projects, etc.) is encapsulated in its own Django “app” or module. It uses PostgreSQL as its database and is containerized (Dockerfile, docker-compose.yaml) with environment configuration (.env) to support development and deployment.

##### Main Components
- Client/User Interface: Represented by the browser front-end consuming rendered templates, static assets (HTML/CSS/JS) from various directories (e.g., in “static”, “templates”) and potentially API endpoints.
- Web Server / Django Application Layer: The Django framework serves as the core where the Model-View-Template (MVT) architecture is followed. Each domain – such as “employee”, “attendance”, “asset”, “payroll”, “helpdesk”, “recruitment”, “onboarding”, “offboarding”, “project”, etc. – is implemented as a separate module.
- API Layer: Note the presence of modules like “horilla_api” which provides RESTful endpoints to support programmatic access. This can be represented as a separate component but integrated into the core Django app.
- Database: PostgreSQL is used as the persistence layer. Include the database as a central repository that is accessed by the Django ORM.
- Background/Supporting services: Scheduler modules (found in several apps such as asset/scheduler, attendance/scheduler, payroll/scheduler, etc.) and management commands that support tasks like report generation, scheduled jobs, and message processing.
- External Integrations: Although not very extensive, there are integrations with biometric devices (“biometric” app) and possibly an LDAP authentication (“horilla_ldap”), and Outlook authentication (“outlook_auth”), which should be shown as external systems that the HRMS communicates with.

##### Relationships and Interactions
- User requests (from browsers or client apps) are routed to the Django Web Server where URL routing (see “horilla/urls.py”, “employee/urls.py”, etc.) directs requests to appropriate modules.
- The business logic is implemented in the Django views, which in turn use Django Models and Forms – associated with each domain.
- The API endpoints (from the “horilla_api” directory) should be drawn as another layer or component that interacts with the same database and internal business logic, and may connect with external mobile/web clients.
- Background tasks and scheduler components operate asynchronously and interact with the core database.
- The Dockerfile and docker-compose file indicate that the environment can be containerized, implying that the application layer (Django application, possibly a web server like Gunicorn) and the PostgreSQL database might run in separate containers.

##### Architectural Patterns and Design Principles
- Django’s Model-View-Template pattern is the primary architectural style. This encourages a separation between the presentation layer (templates/static front-end) and business logic (views, models).
- The repository’s modular layout (i.e. separate Django “apps” for each HR function) encourages separation of concerns and ease of maintainability.
- Use of API endpoints indicates a RESTful design layer to support external integrations.
- Background tasks (from scheduler modules) may suggest asynchronous processing for time-dependent operations.
- Docker configuration and environment management (.env) simplify deployment and environment-specific configuration.

##### Relevant Technologies and Frameworks
- Django (and its MVT pattern) for the application framework.
- PostgreSQL as the database.
- Docker for containerization.
- Front-end assets managed through static file directories.
- External tools possibly from Bootstrap, Chart.js, and custom JavaScript (as referenced in the README and static directories).

##### Instructing the Principal Software Engineer
- Grouping and layers: Optionally layer components into “Presentation”, “Application”, “Data”, and “Integration” layers to reflect distinct responsibilities.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        Browser["Browser / Client"]:::frontend
        TA["Templates"]:::frontend
        ST["Static Assets"]:::frontend
        Browser -->|"renders"| TA
        Browser -->|"loads"| ST
    end

    %% Application Layer
    subgraph "Application Layer (Django)"
        DjangoCore["Django Application Core"]:::backend
        click DjangoCore "https://github.com/horilla-opensource/horilla/tree/master/horilla/"

        subgraph "Domain Apps"
            Employee["Employee Management Module"]:::module
            click Employee "https://github.com/horilla-opensource/horilla/tree/master/employee/"
            Attendance["Attendance Module"]:::module
            click Attendance "https://github.com/horilla-opensource/horilla/tree/master/attendance/"
            Leave["Leave Management Module"]:::module
            click Leave "https://github.com/horilla-opensource/horilla/tree/master/leave/"
            Payroll["Payroll Module"]:::module
            click Payroll "https://github.com/horilla-opensource/horilla/tree/master/payroll/"
            Recruitment["Recruitment Module"]:::module
            click Recruitment "https://github.com/horilla-opensource/horilla/tree/master/recruitment/"
            Onboarding["Onboarding Module"]:::module
            click Onboarding "https://github.com/horilla-opensource/horilla/tree/master/onboarding/"
            Offboarding["Offboarding Module"]:::module
            click Offboarding "https://github.com/horilla-opensource/horilla/tree/master/offboarding/"
            Helpdesk["Helpdesk Module"]:::module
            click Helpdesk "https://github.com/horilla-opensource/horilla/tree/master/helpdesk/"
            Projects["Projects Module"]:::module
            click Projects "https://github.com/horilla-opensource/horilla/tree/master/project/"
        end

        API["Django API Layer"]:::api
        click API "https://github.com/horilla-opensource/horilla/tree/master/horilla_api/"

        Background["Background Scheduler & Tasks"]:::scheduler
        click Background "https://github.com/horilla-opensource/horilla/tree/master/base/management/commands/"
    end

    %% Data Layer
    subgraph "Data Layer"
        Database["PostgreSQL Database"]:::database
    end

    %% External Integrations
    subgraph "External Integrations"
        Biometric["Biometric Integration"]:::external
        click Biometric "https://github.com/horilla-opensource/horilla/tree/master/biometric/"
        LDAP["LDAP Integration"]:::external
        click LDAP "https://github.com/horilla-opensource/horilla/tree/master/horilla_ldap/"
        Outlook["Outlook Authentication"]:::external
        click Outlook "https://github.com/horilla-opensource/horilla/tree/master/outlook_auth/"
    end

    %% Containerization
    Docker["Docker Container & Environment"]:::docker
    click Docker "https://github.com/horilla-opensource/horilla/tree/master/Dockerfile"
    click Docker "https://github.com/horilla-opensource/horilla/blob/master/docker-compose.yaml"
    click Docker "https://github.com/horilla-opensource/horilla/blob/master/.env.dist"

    %% Connections: Presentation to Application
    TA -->|"HTTP Request"| DjangoCore
    ST -->|"HTTP Request"| DjangoCore
    Browser -->|"HTTP Request"| DjangoCore

    %% Connections within Application Layer
    DjangoCore -->|"routes to"| Employee
    DjangoCore -->|"routes to"| Attendance
    DjangoCore -->|"routes to"| Leave
    DjangoCore -->|"routes to"| Payroll
    DjangoCore -->|"routes to"| Recruitment
    DjangoCore -->|"routes to"| Onboarding
    DjangoCore -->|"routes to"| Offboarding
    DjangoCore -->|"routes to"| Helpdesk
    DjangoCore -->|"routes to"| Projects
    DjangoCore -->|"handles API"| API
    DjangoCore -->|"triggers"| Background

    %% Database interactions
    DjangoCore -->|"ORM"| Database
    Employee -->|"DB Ops"| Database
    Attendance -->|"DB Ops"| Database
    Leave -->|"DB Ops"| Database
    Payroll -->|"DB Ops"| Database
    Recruitment -->|"DB Ops"| Database
    Onboarding -->|"DB Ops"| Database
    Offboarding -->|"DB Ops"| Database
    Helpdesk -->|"DB Ops"| Database
    Projects -->|"DB Ops"| Database
    API -->|"ORM"| Database
    Background -->|"DB Ops"| Database

    %% External integrations from Application Layer
    DjangoCore -->|"LDAP"| LDAP
    DjangoCore -->|"Outlook"| Outlook
    DjangoCore -->|"Biometric"| Biometric

    %% Docker encapsulation
    Docker --- DjangoCore
    Docker --- Database

    %% Click events for Presentation Layer assets
    click TA "https://github.com/horilla-opensource/horilla/tree/master/templates/"
    click ST "https://github.com/horilla-opensource/horilla/tree/master/static/"

    %% Styles
    classDef frontend fill:#ffefd5,stroke:#d2691e,stroke-width:2px;
    classDef backend fill:#d0e1f9,stroke:#31708f,stroke-width:2px;
    classDef module fill:#d9ead3,stroke:#6aa84f,stroke-width:2px;
    classDef api fill:#fff2cc,stroke:#e69138,stroke-width:2px;
    classDef scheduler fill:#c9daf8,stroke:#6d9eeb,stroke-width:2px;
    classDef database fill:#fde9d9,stroke:#b45f06,stroke-width:2px,stroke-dasharray: 5 5;
    classDef external fill:#f4cccc,stroke:#cc0000,stroke-width:2px;
    classDef docker fill:#e6e6fa,stroke:#663399,stroke-width:2px;
```
