# ahmedemamhatem/invoicing architecture

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

- Interactive diagram: https://gitdiagram.com/ahmedemamhatem/invoicing
- Repository: https://github.com/ahmedemamhatem/invoicing

## Overview

##### Project type and purpose
- This is a Frappe/ERPNext “app” (plugin) named “invoicing” that extends the core framework with custom doctypes, reports, workspace pages and fixtures for an invoicing module.
- Its purpose is to add invoicing features—clients, suppliers, invoice settings—and a profit-and-loss report to a Frappe site.

##### File structure
- Top-level:
- pyproject.toml, license.txt, .gitignore
- invoicing/ — root of the app
- invoicing/ contains:
- config/ — app configuration (hooks, permissions)
- fixtures/ — JSON fixtures for custom fields, translations, property setters
- hooks.py, install.py — entry points into Frappe’s installation lifecycle
- invoicing/ — actual module packages
– report/profit_and_loss/ (Python logic, JSON report definition, JS client)
– workspace/ (JSON definitions for module workspaces, named in Arabic)
- modules.txt, patches.txt — module registration and migration scripts
- templates/ — Jinja templates for custom pages
- public/ — static assets (empty placeholder)

##### README
- Very brief; confirms the project is named “Invoicing” and is MIT-licensed.

##### Main components
a. Frappe Framework Server
b. Invoicing App
- Hooks & Configuration
- Fixtures Loader
- Custom Doctypes & Property Setters
- Reports subsystem (Python + JSON + JS)
- Workspace definitions (custom pages)
- Templates and static assets
c. Database (MariaDB/MySQL)
d. Web Client (Browser, running Frappe Desk UI + custom JS)
e. Bench/Scheduler Worker (for patch runs, scheduled report generation)

##### Relationships and interactions
- Browser ↔ HTTP ↔ Frappe Server
- User clicks “Profit & Loss” → JS widget fetches JSON definition → invokes Python report script → SQL queries → JSON response → rendered in UI
- User navigates to workspace pages → Frappe serves Jinja templates and JSON definitions
- Frappe Server ↔ Database
- Fixtures loaded at install time write to tabCustom Field, tabProperty Setter, tabTranslation
- Modules.txt tells Frappe which module to register
- Patches.txt runs migrations on bench migrate
- Bench Scheduler ↔ Frappe Server
- install.py hook executes on app install
- patches.txt entries applied by patch runner

##### Architectural patterns and design principles
- Modular layering—app conforms to Frappe’s plugin architecture
- Separation of concerns:
- hooks.py handles lifecycle events
- fixtures store declarative customizations
- report folder encapsulates server logic, metadata, client code
- Convention over configuration—modules.txt auto-registers module

##### Details to capture
- Report flow: “profit_and_loss.json defines report → profit_and_loss.py executes → JS renders”
- Workspace JSON definitions mapped to UI menus

## Diagram (Mermaid)

```mermaid
flowchart TD
    Browser["Browser (Frappe Desk UI)"]:::client
    Server["Frappe Framework Server"]:::core
    DB["MariaDB/MySQL"]:::db
    Scheduler["Bench Scheduler"]:::scheduler

    subgraph "Invoicing App (Plugin)"
        Hooks["Hooks & Configuration"]:::app
        InstallHook["Install Hook"]:::app
        ConfigDir["App Configuration Directory"]:::app
        Fixtures["Fixtures Loader"]:::app
        ModulesReg["Module Registration"]:::app
        Patches["Patch Scripts"]:::app
        subgraph "Reports Subsystem"
            ReportDef["profit_and_loss.json"]:::app
            ReportLogic["profit_and_loss.py"]:::app
            ReportJS["profit_and_loss.js"]:::app
        end
        subgraph "Workspace Definitions"
            WS1["إعدادات_الفواتير.json"]:::app
            WS2["العملاء.json"]:::app
            WS3["الموردين.json"]:::app
            WS4["مدير_النظام.json"]:::app
        end
        Templates["Jinja Templates"]:::app
        Assets["Static Assets"]:::app
    end

    Browser -->|"HTTP Request"| Server
    Server -->|"SQL"| DB
    Scheduler -->|"runs install & patches"| Server
    Browser -->|"loads templates & definitions"| Templates
    Browser -->|"loads JS"| ReportJS
    Server --> Hooks
    Hooks -->|"on_install"| InstallHook
    InstallHook --> Fixtures
    InstallHook --> ModulesReg
    Scheduler --> Patches
    Server --> ReportLogic
    ReportDef --> ReportLogic
    ReportLogic --> DB
    Server --> WS1
    Server --> WS2
    Server --> WS3
    Server --> WS4

    click Hooks "https://github.com/ahmedemamhatem/invoicing/blob/main/invoicing/hooks.py"
    click InstallHook "https://github.com/ahmedemamhatem/invoicing/blob/main/invoicing/install.py"
    click ConfigDir "https://github.com/ahmedemamhatem/invoicing/tree/main/invoicing/config/"
    click Fixtures "https://github.com/ahmedemamhatem/invoicing/blob/main/invoicing/fixtures/custom_field.json"
    click Fixtures "https://github.com/ahmedemamhatem/invoicing/blob/main/invoicing/fixtures/property_setter.json"
    click Fixtures "https://github.com/ahmedemamhatem/invoicing/blob/main/invoicing/fixtures/translation.json"
    click ModulesReg "https://github.com/ahmedemamhatem/invoicing/blob/main/invoicing/modules.txt"
    click Patches "https://github.com/ahmedemamhatem/invoicing/blob/main/invoicing/patches.txt"
    click ReportDef "https://github.com/ahmedemamhatem/invoicing/blob/main/invoicing/invoicing/report/profit_and_loss/profit_and_loss.json"
    click ReportLogic "https://github.com/ahmedemamhatem/invoicing/blob/main/invoicing/invoicing/report/profit_and_loss/profit_and_loss.py"
    click ReportJS "https://github.com/ahmedemamhatem/invoicing/blob/main/invoicing/invoicing/report/profit_and_loss/profit_and_loss.js"
    click WS1 "https://github.com/ahmedemamhatem/invoicing/blob/main/invoicing/invoicing/workspace/إعدادات_الفواتير/إعدادات_الفواتير.json"
    click WS2 "https://github.com/ahmedemamhatem/invoicing/blob/main/invoicing/invoicing/workspace/العملاء/العملاء.json"
    click WS3 "https://github.com/ahmedemamhatem/invoicing/blob/main/invoicing/invoicing/workspace/الموردين/الموردين.json"
    click WS4 "https://github.com/ahmedemamhatem/invoicing/blob/main/invoicing/invoicing/workspace/مدير_النظام/مدير_النظام.json"
    click Templates "https://github.com/ahmedemamhatem/invoicing/tree/main/invoicing/templates/pages/"
    click Assets "https://github.com/ahmedemamhatem/invoicing/tree/main/invoicing/public/"

    classDef core fill:#CCCCCC,stroke:#333,stroke-width:1px
    classDef app fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef db fill:#90EE90,stroke:#333,stroke-width:1px
    classDef client fill:#FFA500,stroke:#333,stroke-width:1px
    classDef scheduler fill:#F0E68C,stroke:#333,stroke-width:1px
```
