# sowaan/quotation_profitability architecture

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

- Interactive diagram: https://gitdiagram.com/sowaan/quotation_profitability
- Repository: https://github.com/sowaan/quotation_profitability

## Overview

##### Project type and purpose
- This is a Frappe/ERPNext “app” (a plugin) named “quotation_profitability.”
- Its goal is to enhance the Quotation DocType in ERPNext by adding profitability calculations and UI‐level enhancements.

##### File structure
- Top‐level:
- pyproject.toml – project definition
- README.md, license.txt, .gitignore
- quotation_profitability/
- config/            – app configuration (hooks, docs)
- fixtures/          – JSON definitions for new custom fields
- modules.txt        – module loading order
- patches.txt        – database patches/migrations
- hooks.py           – Frappe hook definitions (event bindings)
- public/            – static assets (CSS/JS/img)
- quotation_profitability/quotation_profitability/
- client_scripts/    – front‐end JS for the Quotation form
- events/            – Python functions handling DocType events
- templates/pages/   – custom web pages or form enhancements

##### Key README insights
- Minimal README; confirms it’s an ERPNext extension focused on quotation profitability.

a. Client (Browser)
b. Web Server (NGINX or built‐in Frappe server)
c. Frappe Application Server
– Core Frappe framework
– ERPNext modules
– quotation_profitability app
d. Database (MariaDB)
e. Caching & Queues (Redis for real‐time / background jobs)
f. Background Workers (Celery/bench worker)

##### Relationships & interactions
1. User opens a Quotation in the browser → HTTP(S) request → Web Server
2. Web Server routes to Frappe Application Server
3. Frappe Server loads:
- Core framework
- ERPNext DocType definitions
- Custom app via modules.txt, fixtures, patches
- hook bindings from hooks.py
4. Browser loads client_scripts/quotation.js → UI enhancements, field watchers
5. On Quotation save/validate → server‐side event (events/quotation_profitability.py)
6. Server computes profitability → updates DocType custom fields (from fixtures) → writes to MariaDB
7. If any background tasks (e.g., large calculations, reports), they’re enqueued to Redis → processed by background workers
8. Responses flow back to client; UI updates with profitability figures

##### Architectural patterns & principles
- Plugin architecture: hooks + event‐driven customization
- MVC:
- Model = Quotation DocType + custom fields (fixtures)
- View = client script UI + Jinja templates/pages
- Controller = hook handlers in Python (events)
- Separation of concerns: static assets under public, migrations under patches, hooking under hooks.py.

- Labels on all components (e.g., “Frappe App Server,” “quotation_profitability hooks”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    Browser["Browser (Client)"]:::external
    DB["MariaDB"]:::external
    Redis["Redis (Cache/Queue)"]:::external

    %% Application Layers
    NGINX["NGINX / Load Balancer"]:::app-layer
    Workers["Background Workers"]:::app-layer

    %% Frappe Server with subcomponents
    subgraph "Frappe App Server" 
        direction TB
        Core["Core Frappe Framework"]:::app-layer
        ERPNext["ERPNext Modules"]:::app-layer
        subgraph "quotation_profitability App" 
            direction TB
            Config["config/ (hooks & docs)"]:::custom
            InitRoot["__init__.py (root)"]:::custom
            InitModule["__init__.py (app pkg)"]:::custom
            ModulesTxt["modules.txt"]:::custom
            Patches["patches.txt"]:::custom
            Fixtures["fixtures (custom_field.json)"]:::custom
            Hooks["hooks.py"]:::custom
            Events["events (quotation_profitability.py)"]:::custom
            ClientScript["quotation.js"]:::custom
            Templates["templates/pages"]:::custom
        end
    end

    %% Data Flows
    Browser -->|"1. HTTP Request"| NGINX
    NGINX -->|"2. Route to Frappe"| Core
    Core -->|"Load ERPNext"| ERPNext
    ERPNext -->|"Load Custom App"| ModulesTxt
    ModulesTxt -->|"Load fixtures"| Fixtures
    ModulesTxt -->|"Apply patches"| Patches
    ERPNext -->|"Bind hooks"| Hooks
    ERPNext -->|"Register events"| Events
    ERPNext -->|"Serve client scripts"| ClientScript
    ERPNext -->|"Render templates"| Templates

    Core -->|"DB CRUD"| DB
    Core <-->|"Cache & Enqueue"| Redis
    Redis -->|"Process jobs"| Workers
    Workers -->|"DB write"| DB
    Core -->|"5. Response"| Browser

    %% Click Events
    click Hooks "https://github.com/sowaan/quotation_profitability/blob/main/quotation_profitability/hooks.py"
    click ModulesTxt "https://github.com/sowaan/quotation_profitability/blob/main/quotation_profitability/modules.txt"
    click Patches "https://github.com/sowaan/quotation_profitability/blob/main/quotation_profitability/patches.txt"
    click Fixtures "https://github.com/sowaan/quotation_profitability/blob/main/quotation_profitability/fixtures/custom_field.json"
    click ClientScript "https://github.com/sowaan/quotation_profitability/blob/main/quotation_profitability/quotation_profitability/client_scripts/quotation.js"
    click Events "https://github.com/sowaan/quotation_profitability/blob/main/quotation_profitability/quotation_profitability/events/quotation_profability.py"
    click Templates "https://github.com/sowaan/quotation_profitability/tree/main/quotation_profitability/templates/pages/"
    click Config "https://github.com/sowaan/quotation_profitability/tree/main/quotation_profitability/config/"
    click InitRoot "https://github.com/sowaan/quotation_profitability/blob/main/quotation_profitability/__init__.py"
    click InitModule "https://github.com/sowaan/quotation_profitability/blob/main/quotation_profitability/quotation_profitability/__init__.py"

    %% Styles
    classDef external fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef app-layer fill:#d4edda,stroke:#333,stroke-width:1px
    classDef custom fill:#ffe5b4,stroke:#333,stroke-width:1px
```
