# frappe/lending architecture

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

- Interactive diagram: https://gitdiagram.com/frappe/lending
- Repository: https://github.com/frappe/lending

## Overview

##### Project type and purpose
- This is an “app” (plugin) for the Frappe/ERPNext framework. It adds a Loan Management module (“lending”) on top of ERPNext, supplying Doctypes, dashboards, reports, patches and UI assets.

##### File structure
- Top-level files: configuration (pyproject.toml, setup.py), CI/CD and linting (GitHub workflows, .flake8, commitlint), license.
- “lending/”: the app’s source. Within it:
- config, hooks.py, install.py → Frappe hook definitions, app setup and configuration.
- loan_management/doctype → JSON, Python and JS definitions for each Doctype (model), server‐side business logic, client scripts and tests.
- loan_management/dashboard_chart and number_card → metadata for Kanban/KPI widgets.
- report → server and client code for custom reports.
- overrides/ and patches/ → extensions and migration scripts that manipulate ERPNext core behavior and schema.
- public/js, templates/pages → front-end assets (bundled JS, HTML templates).
- translations/ → CSV files for i18n.

##### README for additional insights
- Describes the app as “Open Source Lending software” to install into a Frappe Bench. No standalone web server or mobile component—this integrates into the ERPNext web UI.

##### Main components and their interactions
a. Client browser (UI layer)
- Fetches HTML, JS and CSS from Frappe’s HTTP server (bench → Nginx/Gunicorn).
- Executes JS hooks (defined in Doctype .js files) for client-side validation and UI interactions.
b. Frappe Application Server
- Core framework + ERPNext + Lending app.
- Uses hooks.py to register event handlers, overrides, scheduler tasks, API endpoints.
- Doctype definitions (.json) register models in MariaDB; Python controllers enforce business rules.
c. Database (MariaDB)
- Persists all Doctype records, system settings, patches.
d. Cache/Broker (Redis)
- Session management, Redis Queue for background jobs (e.g., interest accrual).
e. Bench process manager
- Supervises worker processes, scheduler, web server, background jobs.
f. External dependencies
- ERPNext core (other modules), Frappe Bench CLI, third-party services only if configured (e.g., email SMTP).

##### Architectural patterns and design principles
- MVC pattern via Frappe Doctypes (Model = .json schemas, View = Jinja templates + JS, Controller = Python).
- Plugin/Extension pattern: “lending” registers hooks and overrides rather than patching core code.
- Data migrations applied incrementally via “patches” folder.
- i18n support via CSV translations.
- Modular dashboards and reports allow drop-in integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Side"
        Browser["Browser (UI)"]:::frontend
    end

    %% HTTP Layer
    subgraph "HTTP Proxy"
        Proxy["Nginx/Gunicorn"]:::core
    end

    %% Application Server Layer
    subgraph "Application Server"
        Framework["Frappe Framework"]:::framework
        ERPNext["ERPNext Modules"]:::core
        subgraph "Lending App"
            Hooks["hooks.py & config"]:::app
            Doctype["loan_management/doctype"]:::app
            ClientScripts["Client-side Doctype Scripts"]:::app
            DashboardCharts["Dashboard Charts Metadata"]:::app
            DashboardSources["Dashboard Chart Data Sources"]:::app
            NumberCards["Number Cards (KPI Widgets)"]:::app
            Reports["Custom Reports"]:::app
            Workspace["Workspace Configuration"]:::app
            Overrides["Overrides of ERPNext Core"]:::app
            Patches["Data Migration Patches"]:::app
            FrontendAssets["Front-end Assets"]:::app
            I18n["Internationalization Files"]:::app
            Utils["Utility Functions"]:::app
            ModulesList["Module Registration List"]:::app
            Tests["Automated Tests"]:::app
        end
    end

    %% Persistence and Broker
    subgraph "Persistence"
        DB["MariaDB"]:::db
    end
    subgraph "Cache / Broker"
        Cache["Redis"]:::cache
    end

    %% Scheduler and Worker
    Scheduler["Scheduler"]:::core
    Worker["Background Worker"]:::core

    %% Web Request Flow
    Browser -->|HTTP Request| Proxy
    Proxy -->|Forward Request| Framework
    Framework -->|"Loads Modules"| ERPNext
    ERPNext -->|"Plugin Hooks"| Hooks
    Hooks -->|"Handle Routes & Controllers"| Doctype
    Doctype -->|"Execute Business Logic"| DB
    Doctype -->|"Use Cache/Queue"| Cache
    DB -->|"Query Results"| Doctype
    Cache -->|"Session / Jobs"| Doctype
    Doctype -->|"Response"| Browser

    %% Background Job Flow
    Scheduler -->|Schedule Jobs| Cache
    Cache -->|Queue Message| Worker
    Worker -->|Invoke| Doctype
    Worker -->|Access DB| DB

    %% Data Migration Flow
    Scheduler -->|Run Patches| Patches
    Patches -->|Alter Schema| DB

    %% Click Events
    click Hooks "https://github.com/frappe/lending/blob/develop/lending/hooks.py"
    click Doctype "https://github.com/frappe/lending/tree/develop/lending/loan_management/doctype/"
    click ClientScripts "https://github.com/frappe/lending/blob/develop/lending/loan_management/doctype/*/*.js"
    click DashboardCharts "https://github.com/frappe/lending/tree/develop/lending/loan_management/dashboard_chart/"
    click DashboardSources "https://github.com/frappe/lending/tree/develop/lending/loan_management/dashboard_chart_source/"
    click NumberCards "https://github.com/frappe/lending/tree/develop/lending/loan_management/number_card/"
    click Reports "https://github.com/frappe/lending/tree/develop/lending/loan_management/report/"
    click Workspace "https://github.com/frappe/lending/blob/develop/lending/loan_management/workspace/lending/lending.json"
    click Overrides "https://github.com/frappe/lending/tree/develop/lending/overrides/"
    click Patches "https://github.com/frappe/lending/tree/develop/lending/patches/"
    click FrontendAssets "https://github.com/frappe/lending/tree/develop/lending/public/js/"
    click I18n "https://github.com/frappe/lending/tree/develop/lending/translations/"
    click Utils "https://github.com/frappe/lending/blob/develop/lending/utils.py"
    click ModulesList "https://github.com/frappe/lending/blob/develop/lending/modules.txt"

    %% Styles
    classDef frontend fill:#D3D3F0,stroke:#666,stroke-width:1px
    classDef core fill:#AED6F1,stroke:#000,stroke-width:1px
    classDef framework fill:#85C1E9,stroke:#000,stroke-width:1px
    classDef app fill:#ABEBC6,stroke:#088A29,stroke-width:1px
    classDef db fill:#F9E79F,stroke:#B9770E,stroke-width:1px
    classDef cache fill:#F5B7B1,stroke:#641E16,stroke-width:1px
```
