# arus-info/erpnext-australian-localisation architecture

> Architecture diagram of the GitHub repository arus-info/erpnext-australian-localisation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arus-info/erpnext-australian-localisation
- Repository: https://github.com/arus-info/erpnext-australian-localisation

## Overview

#### Purpose and platform

This is a Frappe/ERPNext v16 app that adds Australian accounting localisation: GST/BAS reporting, payment batching and ABA bank-file export, AU bank-statement CSV import, and ABN validation. It runs inside the ERPNext server and Desk UI; it is not a standalone service. Core app registration and lifecycle entry points are `erpnext_australian_localisation/hooks.py`, `erpnext_australian_localisation/install.py`, and `erpnext_australian_localisation/boot.py`.

#### Installation, schema, and ERPNext integration

Installation provisions localisation-specific custom fields, property setters, fixtures, and workspace data; uninstallation reverses app-owned setup. Versioned patches evolve existing ERPNext documents and configuration. This is the principal boundary with ERPNext’s persisted DocType model.
- `erpnext_australian_localisation/setup/custom_fields.py`
- `erpnext_australian_localisation/setup/property_setters.py`
- `erpnext_australian_localisation/patches.txt`

Server-side overrides extend or replace ERPNext behavior for companies, invoices, payment entries, bank import, and master-data validation. Desk-side bundles attach corresponding client behavior to standard forms.
- `erpnext_australian_localisation/overrides/invoices.py`
- `erpnext_australian_localisation/overrides/payment_entry.py`
- `erpnext_australian_localisation/public/js/australian_localisation.bundle.js`

#### Tax classification and GST determination

AU tax codes and determination records encode GST posting behavior based on customer/supplier classifications and transaction context. These records feed ERPNext invoice and expense/payment workflows rather than owning a separate ledger.
- `erpnext_australian_localisation/erpnext_australian_localisation/doctype/au_tax_code/au_tax_code.py`
- `erpnext_australian_localisation/erpnext_australian_localisation/doctype/au_tax_determination/au_tax_determination.py`
- `erpnext_australian_localisation/overrides/purchase_invoice.py`

#### BAS configuration and report pipeline

`AU Localisation Settings` selects reporting frequency and Full versus Simpler BAS mode. Full reporting maps transactional tax outcomes to BAS labels; Simpler reporting maps configured income accounts. Reporting periods and report-entry child records provide the persisted report structure. BAS creation/calculation is a server-side background-capable task boundary over ERPNext accounting data.
- `erpnext_australian_localisation/erpnext_australian_localisation/doctype/au_localisation_settings/au_localisation_settings.py`
- `erpnext_australian_localisation/erpnext_australian_localisation/doctype/au_bas_report/au_bas_report.py`
- `erpnext_australian_localisation/tasks/bas_report.py`

#### BAS presentation and outputs

BAS labels, entries, and report entries represent calculated values and underlying transactional detail. JSON DocType definitions and Desk JS provide the interactive report workflow; Frappe print formats/templates render printable BAS output.
- `erpnext_australian_localisation/erpnext_australian_localisation/doctype/au_bas_label/au_bas_label.json`
- `erpnext_australian_localisation/erpnext_australian_localisation/print_format/au_full_bas_report_format/au_full_bas_report_format.json`
- `erpnext_australian_localisation/templates/includes/au_print_format.css`

#### Payment proposal, batches, and ABA export

The Payment Proposal page selects payable supplier/employee documents and creates Payment Batch records. A batch owns invoice/item child rows and produces an Australian Banking Association (ABA) bulk-payment file for upload to a bank; the bank is an offline downstream endpoint, not a direct integration.
- `erpnext_australian_localisation/erpnext_australian_localisation/page/payment_proposal/payment_proposal.py`
- `erpnext_australian_localisation/erpnext_australian_localisation/doctype/payment_batch/payment_batch.py`
- `erpnext_australian_localisation/erpnext_australian_localisation/doctype/payment_batch/aba_file_generator.py`

#### External validation and bank-statement ingestion

ABN validation is an external Australian Business Register service boundary, using an organisation-provided GUID and applying results to Customer/Supplier data. Bank-statement import adapts bank-specific CSV formats into ERPNext Bank Reconciliation imports; supported format and mapping DocTypes isolate parsing configuration from standard ERPNext import behavior.
- `erpnext_australian_localisation/overrides/abn_verification.py`
- `erpnext_australian_localisation/overrides/bank_statement_import.py`
- `erpnext_australian_localisation/erpnext_australian_localisation/doctype/au_bank_statement_format/au_bank_statement_format.py`

Main entry points: [`erpnext_australian_localisation/hooks.py`](https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/hooks.py) (App entrypoints), [`erpnext_australian_localisation/install.py`](https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/install.py) (Installation and patches), [`erpnext_australian_localisation/tasks/bas_report.py`](https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/tasks/bas_report.py) (BAS calculation), [`erpnext_australian_localisation/erpnext_australian_localisation/doctype/au_tax_determination/au_tax_determination.py`](https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/erpnext_australian_localisation/doctype/au_tax_determination/au_tax_determination.py) (AU tax determination)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_lifecycle["App lifecycle"]
  node_app_entrypoints["App entrypoints<br/>Frappe hooks<br/>[hooks.py]"]
  node_installation["Installation and patches<br/>schema provisioning<br/>[install.py]"]
  node_customisations["Custom fields and properties<br/>ERPNext customisation<br/>[custom_fields.py]"]
  node_patches["Versioned patches<br/>migration list<br/>[patches.txt]"]
  node_desk_bundle["Desk client bundle<br/>JavaScript bundle"]
end

subgraph group_tax["GST and BAS"]
  node_invoice_overrides["Invoice overrides<br/>server override<br/>[invoices.py]"]
  node_tax_codes[("AU tax codes<br/>DocType<br/>[au_tax_code.py]")]
  node_tax_determination[("AU tax determination<br/>DocType")]
  node_purchase_invoice["Purchase invoice override<br/>server override"]
  node_bas_settings[("BAS settings<br/>DocType")]
  node_bas_report[("BAS report<br/>DocType<br/>[au_bas_report.py]")]
  node_bas_task["BAS calculation<br/>background task<br/>[bas_report.py]"]
  node_bas_presentation["BAS Desk and print output<br/>report presentation<br/>[au_bas_label.json]"]
end

subgraph group_payments["Payments and banking"]
  node_payment_proposal["Payment proposal<br/>Desk page"]
  node_payment_batch[("Payment batch<br/>DocType<br/>[payment_batch.py]")]
  node_aba_export["ABA file generator<br/>bank-file export"]
  node_bank_import["Bank statement import<br/>ERPNext import adapter"]
  node_bank_formats[("Bank statement formats<br/>DocType")]
  node_bank_upload{{"Bank upload<br/>offline endpoint"}}
end

subgraph group_integrations["External integration"]
  node_abn_validation["ABN validation<br/>external-service adapter"]
  node_abr_service{{"Australian Business Register<br/>external service"}}
end

node_frappe_erpnext{{"Frappe / ERPNext<br/>host platform"}}

node_app_entrypoints -->|"extends"| node_frappe_erpnext
node_app_entrypoints -->|"lifecycle"| node_installation
node_installation -->|"provisions"| node_customisations
node_installation -->|"runs"| node_patches
node_app_entrypoints -->|"loads"| node_desk_bundle
node_invoice_overrides -->|"applies"| node_tax_determination
node_purchase_invoice -->|"applies"| node_tax_determination
node_tax_determination -->|"selects"| node_tax_codes
node_tax_codes -->|"posts through"| node_frappe_erpnext
node_bas_settings -->|"configures"| node_bas_task
node_bas_task -->|"reads accounting data"| node_frappe_erpnext
node_bas_task -->|"calculates and persists"| node_bas_report
node_bas_report -->|"renders"| node_bas_presentation
node_payment_proposal -->|"creates"| node_payment_batch
node_payment_batch -->|"generates"| node_aba_export
node_aba_export -.->|"uploaded manually"| node_bank_upload
node_abn_validation -->|"validates ABNs"| node_abr_service
node_abn_validation -->|"updates parties"| node_frappe_erpnext
node_bank_formats -->|"configures parsing"| node_bank_import
node_bank_import -->|"imports reconciliation data"| node_frappe_erpnext

click node_app_entrypoints "https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/hooks.py"
click node_installation "https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/install.py"
click node_customisations "https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/setup/custom_fields.py"
click node_patches "https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/patches.txt"
click node_desk_bundle "https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/public/js/australian_localisation.bundle.js"
click node_invoice_overrides "https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/overrides/invoices.py"
click node_tax_codes "https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/erpnext_australian_localisation/doctype/au_tax_code/au_tax_code.py"
click node_tax_determination "https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/erpnext_australian_localisation/doctype/au_tax_determination/au_tax_determination.py"
click node_purchase_invoice "https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/overrides/purchase_invoice.py"
click node_bas_settings "https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/erpnext_australian_localisation/doctype/au_localisation_settings/au_localisation_settings.py"
click node_bas_report "https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/erpnext_australian_localisation/doctype/au_bas_report/au_bas_report.py"
click node_bas_task "https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/tasks/bas_report.py"
click node_bas_presentation "https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/erpnext_australian_localisation/doctype/au_bas_label/au_bas_label.json"
click node_payment_proposal "https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/erpnext_australian_localisation/page/payment_proposal/payment_proposal.py"
click node_payment_batch "https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/erpnext_australian_localisation/doctype/payment_batch/payment_batch.py"
click node_aba_export "https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/erpnext_australian_localisation/doctype/payment_batch/aba_file_generator.py"
click node_abn_validation "https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/overrides/abn_verification.py"
click node_bank_import "https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/overrides/bank_statement_import.py"
click node_bank_formats "https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/erpnext_australian_localisation/doctype/au_bank_statement_format/au_bank_statement_format.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_entrypoints,node_installation,node_customisations,node_patches,node_desk_bundle toneBlue
class node_invoice_overrides,node_tax_codes,node_tax_determination,node_purchase_invoice,node_bas_settings,node_bas_report,node_bas_task,node_bas_presentation toneAmber
class node_payment_proposal,node_payment_batch,node_aba_export,node_bank_import,node_bank_formats,node_bank_upload toneMint
class node_abn_validation,node_abr_service toneRose
class node_frappe_erpnext toneNeutral
```

## Components

### App lifecycle

- [App entrypoints](https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/hooks.py): Frappe hooks · Registers lifecycle hooks, overrides, assets, and boot behavior. · `erpnext_australian_localisation/hooks.py`
- [Installation and patches](https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/install.py): schema provisioning · Creates app-owned customisations and evolves ERPNext documents. · `erpnext_australian_localisation/install.py`
- [Custom fields and properties](https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/setup/custom_fields.py): ERPNext customisation · `erpnext_australian_localisation/setup/custom_fields.py`
- [Versioned patches](https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/patches.txt): migration list · `erpnext_australian_localisation/patches.txt`
- [Desk client bundle](https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/public/js/australian_localisation.bundle.js): JavaScript bundle · Adds client behavior to standard ERPNext forms. · `erpnext_australian_localisation/public/js/australian_localisation.bundle.js`

### GST and BAS

- [Invoice overrides](https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/overrides/invoices.py): server override · `erpnext_australian_localisation/overrides/invoices.py`
- [AU tax codes](https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/erpnext_australian_localisation/doctype/au_tax_code/au_tax_code.py): DocType · Defines GST posting behavior. · `erpnext_australian_localisation/erpnext_australian_localisation/doctype/au_tax_code/au_tax_code.py`
- [AU tax determination](https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/erpnext_australian_localisation/doctype/au_tax_determination/au_tax_determination.py): DocType · Classifies GST from party and transaction context. · `erpnext_australian_localisation/erpnext_australian_localisation/doctype/au_tax_determination/au_tax_determination.py`
- [Purchase invoice override](https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/overrides/purchase_invoice.py): server override · `erpnext_australian_localisation/overrides/purchase_invoice.py`
- [BAS settings](https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/erpnext_australian_localisation/doctype/au_localisation_settings/au_localisation_settings.py): DocType · Selects reporting frequency and Full or Simpler BAS mode. · `erpnext_australian_localisation/erpnext_australian_localisation/doctype/au_localisation_settings/au_localisation_settings.py`
- [BAS report](https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/erpnext_australian_localisation/doctype/au_bas_report/au_bas_report.py): DocType · Persists reporting periods, labels, entries, and detail. · `erpnext_australian_localisation/erpnext_australian_localisation/doctype/au_bas_report/au_bas_report.py`
- [BAS calculation](https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/tasks/bas_report.py): background task · Calculates BAS values from ERPNext accounting data. · `erpnext_australian_localisation/tasks/bas_report.py`
- [BAS Desk and print output](https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/erpnext_australian_localisation/doctype/au_bas_label/au_bas_label.json): report presentation · Provides BAS labels, interactive workflow, and printable output. · `erpnext_australian_localisation/erpnext_australian_localisation/doctype/au_bas_label/au_bas_label.json`

### Payments and banking

- [Payment proposal](https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/erpnext_australian_localisation/page/payment_proposal/payment_proposal.py): Desk page · Selects payable supplier and employee documents. · `erpnext_australian_localisation/erpnext_australian_localisation/page/payment_proposal/payment_proposal.py`
- [Payment batch](https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/erpnext_australian_localisation/doctype/payment_batch/payment_batch.py): DocType · Owns selected payment and invoice rows. · `erpnext_australian_localisation/erpnext_australian_localisation/doctype/payment_batch/payment_batch.py`
- [ABA file generator](https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/erpnext_australian_localisation/doctype/payment_batch/aba_file_generator.py): bank-file export · Generates an offline bulk-payment file for bank upload. · `erpnext_australian_localisation/erpnext_australian_localisation/doctype/payment_batch/aba_file_generator.py`
- [Bank statement import](https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/overrides/bank_statement_import.py): ERPNext import adapter · Converts bank CSV data into Bank Reconciliation imports. · `erpnext_australian_localisation/overrides/bank_statement_import.py`
- [Bank statement formats](https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/erpnext_australian_localisation/doctype/au_bank_statement_format/au_bank_statement_format.py): DocType · Stores bank-specific CSV parsing and mapping configuration. · `erpnext_australian_localisation/erpnext_australian_localisation/doctype/au_bank_statement_format/au_bank_statement_format.py`
- **Bank upload**: offline endpoint

### External integration

- [ABN validation](https://github.com/arus-info/erpnext-australian-localisation/blob/develop/erpnext_australian_localisation/overrides/abn_verification.py): external-service adapter · Validates Customer and Supplier ABNs using an organisation GUID. · `erpnext_australian_localisation/overrides/abn_verification.py`
- **Australian Business Register**: external service

### Other components

- **Frappe / ERPNext**: host platform · Provides Desk, accounting workflows, and persisted DocTypes.

## Connections

- App entrypoints → Frappe / ERPNext: extends
- App entrypoints → Installation and patches: lifecycle
- Installation and patches → Custom fields and properties: provisions
- Installation and patches → Versioned patches: runs
- App entrypoints → Desk client bundle: loads
- Invoice overrides → AU tax determination: applies
- Purchase invoice override → AU tax determination: applies
- AU tax determination → AU tax codes: selects
- AU tax codes → Frappe / ERPNext: posts through
- BAS settings → BAS calculation: configures
- BAS calculation → Frappe / ERPNext: reads accounting data
- BAS calculation → BAS report: calculates and persists
- BAS report → BAS Desk and print output: renders
- Payment proposal → Payment batch: creates
- Payment batch → ABA file generator: generates
- ABA file generator → Bank upload: uploaded manually
- ABN validation → Australian Business Register: validates ABNs
- ABN validation → Frappe / ERPNext: updates parties
- Bank statement formats → Bank statement import: configures parsing
- Bank statement import → Frappe / ERPNext: imports reconciliation data