# navariltd/navari_csf_ke architecture

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

- Interactive diagram: https://gitdiagram.com/navariltd/navari_csf_ke
- Repository: https://github.com/navariltd/navari_csf_ke

## Overview

CSF_KE is a Frappe/ERPNext application adding Kenyan tax compliance, eTIMS support, statutory payroll reporting, and localized business features. A key user workflow uploads eTIMS CSVs in the Kenya Sales Tax Reconciliation page, compares them with ERPNext sales-tax data, and can save the reconciliation. Separately, ERPNext invoice events feed localized validations and price updates; eTIMS queue jobs run in background workers. The README documents additional payroll and tax reports. Those reports are grouped by capability because individual implementations were not sampled.

Main entry points: [`csf_ke/csf_ke/doctype/kenya_sales_reconciliation/kenya_sales_reconciliation.py`](https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/csf_ke/doctype/kenya_sales_reconciliation/kenya_sales_reconciliation.py) (Reconciliation Logic), [`csf_ke/public/js/kenya_sales_tax_reco/App.jsx`](https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/public/js/kenya_sales_tax_reco/App.jsx) (Reconciliation Page), [`csf_ke/etims/report/etims_sales_ledger/etims_sales_ledger.py`](https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/etims/report/etims_sales_ledger/etims_sales_ledger.py) (eTIMS Sales Ledger), [`csf_ke/hooks.py`](https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/hooks.py) (ERPNext Event Hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_reconciliation["Sales Reconciliation"]
  node_reco_page["Reconciliation Page<br/>[App.jsx]"]
  node_reco_api["Reconciliation Logic"]
  node_reco_record[("Saved Reconciliation")]
  node_uploaded_files["Uploaded CSV Files"]
  node_erp_sales_tax["Sales Tax Report"]
end

subgraph group_etims["eTIMS Compliance"]
  node_etims_ledger["eTIMS Sales Ledger"]
  node_sales_invoices[("Sales Invoices")]
  node_ledger_entries[("eTIMS Ledger Entries")]
  node_queue_manager["Queue Manager"]
  node_queue_jobs[("eTIMS Job Queue<br/>[etims_job_queue.py]")]
  node_worker["Background Worker"]
end

subgraph group_payroll["Payroll Reporting"]
  node_payroll_reports["Statutory Payroll Reports"]
  node_payroll_data[("Payroll Records")]
end

subgraph group_tax["Tax And Finance"]
  node_tax_reports["Localized Tax Reports"]
  node_withholding["VAT Withholding<br/>[vat_withholding.py]"]
end

subgraph group_localization["Business Localization"]
  node_price_margin["Item Price Margins"]
  node_event_hooks["ERPNext Event Hooks<br/>[hooks.py]"]
  node_price_updates["Price Updates<br/>[item_price.py]"]
  node_pin_validation["KRA PIN Validation<br/>[sales_doc.py]"]
end

node_user(("ERPNext User"))
node_kra(("KRA eTIMS"))
node_erpnext(("ERPNext Platform"))

node_user -->|"uses"| node_reco_page
node_reco_page -->|"uploads CSVs"| node_uploaded_files
node_reco_page -->|"calls reconciliation"| node_reco_api
node_reco_api -->|"compares against"| node_erp_sales_tax
node_reco_api -->|"reads uploaded data"| node_uploaded_files
node_reco_api -->|"saves record"| node_reco_record
node_user -->|"runs report"| node_etims_ledger
node_etims_ledger -->|"reads invoice data"| node_sales_invoices
node_etims_ledger -->|"reads ledger data"| node_ledger_entries
node_queue_manager -->|"selects jobs"| node_queue_jobs
node_queue_manager -->|"enqueues execution"| node_worker
node_worker -->|"runs job"| node_queue_jobs
node_user -->|"runs report"| node_payroll_reports
node_payroll_reports -->|"reports on"| node_payroll_data
node_user -->|"runs report"| node_tax_reports
node_user -->|"imports data"| node_withholding
node_erpnext -->|"dispatches events"| node_event_hooks
node_event_hooks -->|"calls on submit"| node_price_updates
node_event_hooks -->|"calls on validation"| node_pin_validation
node_user -->|"configures margins"| node_price_margin
node_price_margin -->|"supports pricing"| node_erpnext
node_kra -.->|"provides statements"| node_uploaded_files

click node_reco_page "https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/public/js/kenya_sales_tax_reco/App.jsx"
click node_reco_api "https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/csf_ke/doctype/kenya_sales_reconciliation/kenya_sales_reconciliation.py"
click node_reco_record "https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/csf_ke/doctype/kenya_sales_reconciliation/kenya_sales_reconciliation.py"
click node_erp_sales_tax "https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/csf_ke/report/kenya_sales_tax_report/kenya_sales_tax_report.py"
click node_etims_ledger "https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/etims/report/etims_sales_ledger/etims_sales_ledger.py"
click node_ledger_entries "https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/etims/doctype/etims_sales_ledger_entry/etims_sales_ledger_entry.py"
click node_queue_manager "https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/etims/doctype/etims_queue_manager/etims_queue_manager.py"
click node_queue_jobs "https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/etims/doctype/etims_job_queue/etims_job_queue.py"
click node_worker "https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/etims/doctype/etims_queue_manager/etims_queue_manager.py"
click node_payroll_reports "https://github.com/navariltd/navari_csf_ke/tree/develop/csf_ke/csf_ke/report"
click node_tax_reports "https://github.com/navariltd/navari_csf_ke/tree/develop/csf_ke/csf_ke/report"
click node_withholding "https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/csf_ke/doctype/vat_withholding/vat_withholding.py"
click node_price_margin "https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/csf_ke/doctype/selling_item_price_margin/selling_item_price_margin.py"
click node_event_hooks "https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/hooks.py"
click node_price_updates "https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/csf_ke/utils/item_price.py"
click node_pin_validation "https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/csf_ke/overrides/sales_doc.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_reco_page,node_reco_api,node_reco_record,node_uploaded_files,node_erp_sales_tax,node_user toneBlue
class node_etims_ledger,node_sales_invoices,node_ledger_entries,node_queue_manager,node_queue_jobs,node_worker toneAmber
class node_payroll_reports,node_payroll_data toneMint
class node_tax_reports,node_withholding toneRose
class node_price_margin,node_event_hooks,node_price_updates,node_pin_validation,node_kra,node_erpnext toneIndigo
```

## Components

### Sales Reconciliation

- [Reconciliation Page](https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/public/js/kenya_sales_tax_reco/App.jsx): `csf_ke/public/js/kenya_sales_tax_reco/App.jsx`
- [Reconciliation Logic](https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/csf_ke/doctype/kenya_sales_reconciliation/kenya_sales_reconciliation.py): `csf_ke/csf_ke/doctype/kenya_sales_reconciliation/kenya_sales_reconciliation.py`
- [Saved Reconciliation](https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/csf_ke/doctype/kenya_sales_reconciliation/kenya_sales_reconciliation.py): `csf_ke/csf_ke/doctype/kenya_sales_reconciliation/kenya_sales_reconciliation.py`
- **Uploaded CSV Files**
- [Sales Tax Report](https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/csf_ke/report/kenya_sales_tax_report/kenya_sales_tax_report.py): `csf_ke/csf_ke/report/kenya_sales_tax_report/kenya_sales_tax_report.py`

### eTIMS Compliance

- [eTIMS Sales Ledger](https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/etims/report/etims_sales_ledger/etims_sales_ledger.py): `csf_ke/etims/report/etims_sales_ledger/etims_sales_ledger.py`
- **Sales Invoices**
- [eTIMS Ledger Entries](https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/etims/doctype/etims_sales_ledger_entry/etims_sales_ledger_entry.py): `csf_ke/etims/doctype/etims_sales_ledger_entry/etims_sales_ledger_entry.py`
- [Queue Manager](https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/etims/doctype/etims_queue_manager/etims_queue_manager.py): `csf_ke/etims/doctype/etims_queue_manager/etims_queue_manager.py`
- [eTIMS Job Queue](https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/etims/doctype/etims_job_queue/etims_job_queue.py): `csf_ke/etims/doctype/etims_job_queue/etims_job_queue.py`
- [Background Worker](https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/etims/doctype/etims_queue_manager/etims_queue_manager.py): `csf_ke/etims/doctype/etims_queue_manager/etims_queue_manager.py`

### Payroll Reporting

- [Statutory Payroll Reports](https://github.com/navariltd/navari_csf_ke/tree/develop/csf_ke/csf_ke/report): `csf_ke/csf_ke/report`
- **Payroll Records**

### Tax And Finance

- [Localized Tax Reports](https://github.com/navariltd/navari_csf_ke/tree/develop/csf_ke/csf_ke/report): `csf_ke/csf_ke/report`
- [VAT Withholding](https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/csf_ke/doctype/vat_withholding/vat_withholding.py): `csf_ke/csf_ke/doctype/vat_withholding/vat_withholding.py`

### Business Localization

- [Item Price Margins](https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/csf_ke/doctype/selling_item_price_margin/selling_item_price_margin.py): `csf_ke/csf_ke/doctype/selling_item_price_margin/selling_item_price_margin.py`
- [ERPNext Event Hooks](https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/hooks.py): `csf_ke/hooks.py`
- [Price Updates](https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/csf_ke/utils/item_price.py): `csf_ke/csf_ke/utils/item_price.py`
- [KRA PIN Validation](https://github.com/navariltd/navari_csf_ke/blob/develop/csf_ke/csf_ke/overrides/sales_doc.py): `csf_ke/csf_ke/overrides/sales_doc.py`

### Other components

- **ERPNext User**
- **KRA eTIMS**
- **ERPNext Platform**

## Connections

- ERPNext User → Reconciliation Page: uses
- Reconciliation Page → Uploaded CSV Files: uploads CSVs
- Reconciliation Page → Reconciliation Logic: calls reconciliation
- Reconciliation Logic → Sales Tax Report: compares against
- Reconciliation Logic → Uploaded CSV Files: reads uploaded data
- Reconciliation Logic → Saved Reconciliation: saves record
- ERPNext User → eTIMS Sales Ledger: runs report
- eTIMS Sales Ledger → Sales Invoices: reads invoice data
- eTIMS Sales Ledger → eTIMS Ledger Entries: reads ledger data
- Queue Manager → eTIMS Job Queue: selects jobs
- Queue Manager → Background Worker: enqueues execution
- Background Worker → eTIMS Job Queue: runs job
- ERPNext User → Statutory Payroll Reports: runs report
- Statutory Payroll Reports → Payroll Records: reports on
- ERPNext User → Localized Tax Reports: runs report
- ERPNext User → VAT Withholding: imports data
- ERPNext Platform → ERPNext Event Hooks: dispatches events
- ERPNext Event Hooks → Price Updates: calls on submit
- ERPNext Event Hooks → KRA PIN Validation: calls on validation
- ERPNext User → Item Price Margins: configures margins
- Item Price Margins → ERPNext Platform: supports pricing
- KRA eTIMS → Uploaded CSV Files: provides statements