# ipconnex-services/canada-compliance-erpnext architecture

> Architecture diagram of the GitHub repository ipconnex-services/canada-compliance-erpnext, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ipconnex-services/canada-compliance-erpnext
- Repository: https://github.com/ipconnex-services/canada-compliance-erpnext

## Overview

Canada Business Compliance is a Frappe/ERPNext app that configures Canadian sales and purchase tax, then selects and applies tax templates to business documents. Administrators configure each company, create payable accounts and generate province-specific templates and rules; runtime logic resolves the relevant province and template, while document-form logic handles exemptions and zero-rated items. The app also normalizes province names, synchronizes customer territories, provides tax-rate lookup, and supplies a tax-invoice format. Some subsystem links are based on README documentation because their implementation was not sampled.

Main entry points: [`canada_business_compliance/ca_sales_tax/doctype/ca_company_tax_config/ca_company_tax_config.py`](https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/ca_sales_tax/doctype/ca_company_tax_config/ca_company_tax_config.py) (Config fields), [`canada_business_compliance/utils/province.py`](https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/utils/province.py) (Province normalization), [`canada_business_compliance/utils/tax_resolver.py`](https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/utils/tax_resolver.py) (Sales tax resolver), [`canada_business_compliance/public/js/ca_sales_tax.js`](https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/public/js/ca_sales_tax.js) (Sales form tax rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_configuration["Company configuration"]
  node_config_form["Company tax config"]
  node_config_doc["Config fields"]
end

subgraph group_setup["Tax setup"]
  node_account_setup["Tax accounts<br/>[setup_taxes.py]"]
  node_template_setup["Templates and rules<br/>[setup_taxes.py]"]
  node_tax_store[("ERPNext tax records")]
end

subgraph group_resolution["Tax resolution"]
  node_province["Province normalization<br/>[province.py]"]
  node_sales_resolver["Sales tax resolver<br/>[tax_resolver.py]"]
  node_purchase_resolver["Purchase destination resolver<br/>[tax_resolver.py]"]
  node_address_store[("ERPNext addresses")]
end

subgraph group_application["Document application"]
  node_form_rules["Sales form tax rules<br/>[ca_sales_tax.js]"]
end

subgraph group_support["Compliance support"]
  node_territory_sync["Customer territory sync<br/>[territory.py]"]
  node_tax_lookup["Province tax lookup<br/>[tax_calculator.py]"]
  node_custom_fields["Compliance fields<br/>[custom_fields.py]"]
  node_address_form["Address form behavior<br/>[ca_address.js]"]
  node_invoice_format["CA tax invoice"]
end

node_admin(("ERPNext administrator"))
node_sales_docs["Sales documents"]
node_purchase_docs["Purchase documents"]

node_admin -->|"configures company"| node_config_form
node_config_form -->|"edits config"| node_config_doc
node_admin -->|"creates accounts"| node_account_setup
node_admin -->|"generates rules"| node_template_setup
node_account_setup -->|"saves account links"| node_config_doc
node_account_setup -->|"creates accounts"| node_tax_store
node_template_setup -->|"creates templates and rules"| node_tax_store
node_template_setup -->|"normalizes province"| node_province
node_sales_docs -->|"selects sales tax"| node_sales_resolver
node_purchase_docs -->|"selects purchase tax"| node_purchase_resolver
node_sales_resolver -->|"normalizes location"| node_province
node_purchase_resolver -->|"normalizes destination"| node_province
node_sales_resolver -->|"reads address state"| node_address_store
node_purchase_resolver -->|"checks delivery location"| node_address_store
node_sales_resolver -->|"finds sales template"| node_tax_store
node_purchase_resolver -->|"finds purchase template"| node_tax_store
node_sales_docs -->|"runs form rules"| node_form_rules
node_form_rules -->|"reads address state"| node_address_store
node_form_rules -->|"loads company settings"| node_config_doc
node_form_rules -->|"updates tax rows"| node_sales_docs
node_tax_lookup -->|"uses province mapping"| node_province
node_tax_lookup -->|"reads tax templates"| node_tax_store
node_territory_sync -->|"normalizes address state"| node_province
node_territory_sync -->|"reads linked address"| node_address_store
node_custom_fields -.->|"adds compliance fields"| node_config_doc
node_address_form -.->|"uses address state"| node_address_store
node_invoice_format -->|"prints registration details"| node_config_doc

click node_config_form "https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/ca_sales_tax/doctype/ca_company_tax_config/ca_company_tax_config.js"
click node_config_doc "https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/ca_sales_tax/doctype/ca_company_tax_config/ca_company_tax_config.py"
click node_account_setup "https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/utils/setup_taxes.py"
click node_template_setup "https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/utils/setup_taxes.py"
click node_province "https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/utils/province.py"
click node_sales_resolver "https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/utils/tax_resolver.py"
click node_purchase_resolver "https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/utils/tax_resolver.py"
click node_form_rules "https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/public/js/ca_sales_tax.js"
click node_territory_sync "https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/utils/territory.py"
click node_tax_lookup "https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/utils/tax_calculator.py"
click node_custom_fields "https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/utils/custom_fields.py"
click node_address_form "https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/public/js/ca_address.js"
click node_invoice_format "https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/ca_sales_tax/print_format/ca_tax_invoice/ca_tax_invoice.json"

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_config_form,node_config_doc toneBlue
class node_account_setup,node_template_setup,node_tax_store toneAmber
class node_province,node_sales_resolver,node_purchase_resolver,node_address_store toneMint
class node_form_rules toneRose
class node_territory_sync,node_tax_lookup,node_custom_fields,node_address_form,node_invoice_format,node_admin,node_sales_docs,node_purchase_docs toneIndigo
```

## Components

### Company configuration

- [Company tax config](https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/ca_sales_tax/doctype/ca_company_tax_config/ca_company_tax_config.js): `canada_business_compliance/ca_sales_tax/doctype/ca_company_tax_config/ca_company_tax_config.js`
- [Config fields](https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/ca_sales_tax/doctype/ca_company_tax_config/ca_company_tax_config.py): `canada_business_compliance/ca_sales_tax/doctype/ca_company_tax_config/ca_company_tax_config.py`

### Tax setup

- [Tax accounts](https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/utils/setup_taxes.py): `canada_business_compliance/utils/setup_taxes.py`
- [Templates and rules](https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/utils/setup_taxes.py): `canada_business_compliance/utils/setup_taxes.py`
- **ERPNext tax records**

### Tax resolution

- [Province normalization](https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/utils/province.py): `canada_business_compliance/utils/province.py`
- [Sales tax resolver](https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/utils/tax_resolver.py): `canada_business_compliance/utils/tax_resolver.py`
- [Purchase destination resolver](https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/utils/tax_resolver.py): `canada_business_compliance/utils/tax_resolver.py`
- **ERPNext addresses**

### Document application

- [Sales form tax rules](https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/public/js/ca_sales_tax.js): `canada_business_compliance/public/js/ca_sales_tax.js`

### Compliance support

- [Customer territory sync](https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/utils/territory.py): `canada_business_compliance/utils/territory.py`
- [Province tax lookup](https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/utils/tax_calculator.py): `canada_business_compliance/utils/tax_calculator.py`
- [Compliance fields](https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/utils/custom_fields.py): `canada_business_compliance/utils/custom_fields.py`
- [Address form behavior](https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/public/js/ca_address.js): `canada_business_compliance/public/js/ca_address.js`
- [CA tax invoice](https://github.com/ipconnex-services/canada-compliance-erpnext/blob/main/canada_business_compliance/ca_sales_tax/print_format/ca_tax_invoice/ca_tax_invoice.json): `canada_business_compliance/ca_sales_tax/print_format/ca_tax_invoice/ca_tax_invoice.json`

### Other components

- **ERPNext administrator**
- **Sales documents**
- **Purchase documents**

## Connections

- ERPNext administrator → Company tax config: configures company (evidence: `README.md`)
- Company tax config → Config fields: edits config (evidence: `canada_business_compliance/ca_sales_tax/doctype/ca_company_tax_config/ca_company_tax_config.js`)
- ERPNext administrator → Tax accounts: creates accounts (evidence: `README.md`)
- ERPNext administrator → Templates and rules: generates rules (evidence: `README.md`)
- Tax accounts → Config fields: saves account links (evidence: `canada_business_compliance/utils/setup_taxes.py`)
- Tax accounts → ERPNext tax records: creates accounts (evidence: `canada_business_compliance/utils/setup_taxes.py`)
- Templates and rules → ERPNext tax records: creates templates and rules (evidence: `README.md`)
- Templates and rules → Province normalization: normalizes province (evidence: `canada_business_compliance/utils/setup_taxes.py`)
- Sales documents → Sales tax resolver: selects sales tax
- Purchase documents → Purchase destination resolver: selects purchase tax
- Sales tax resolver → Province normalization: normalizes location (evidence: `canada_business_compliance/utils/tax_resolver.py`)
- Purchase destination resolver → Province normalization: normalizes destination (evidence: `canada_business_compliance/utils/tax_resolver.py`)
- Sales tax resolver → ERPNext addresses: reads address state (evidence: `canada_business_compliance/utils/tax_resolver.py`)
- Purchase destination resolver → ERPNext addresses: checks delivery location (evidence: `canada_business_compliance/utils/tax_resolver.py`)
- Sales tax resolver → ERPNext tax records: finds sales template (evidence: `canada_business_compliance/utils/tax_resolver.py`)
- Purchase destination resolver → ERPNext tax records: finds purchase template (evidence: `canada_business_compliance/utils/tax_resolver.py`)
- Sales documents → Sales form tax rules: runs form rules
- Sales form tax rules → ERPNext addresses: reads address state (evidence: `canada_business_compliance/public/js/ca_sales_tax.js`)
- Sales form tax rules → Config fields: loads company settings (evidence: `README.md`)
- Sales form tax rules → Sales documents: updates tax rows (evidence: `canada_business_compliance/public/js/ca_sales_tax.js`)
- Province tax lookup → Province normalization: uses province mapping (evidence: `canada_business_compliance/utils/tax_calculator.py`)
- Province tax lookup → ERPNext tax records: reads tax templates (evidence: `canada_business_compliance/utils/tax_calculator.py`)
- Customer territory sync → Province normalization: normalizes address state (evidence: `canada_business_compliance/utils/territory.py`)
- Customer territory sync → ERPNext addresses: reads linked address (evidence: `canada_business_compliance/utils/territory.py`)
- Compliance fields → Config fields: adds compliance fields
- Address form behavior → ERPNext addresses: uses address state
- CA tax invoice → Config fields: prints registration details (evidence: `README.md`)
