The Problem

Kenyan businesses using ERPNext lack built‑in compliance for tax, payroll, and HS‑code integration. Without these features, companies must export data to spreadsheets, manually map tax codes, and risk non‑compliance with KRA regulations.

What This Does

csf_ke is a custom ERPNext app that adds Kenyan‑specific doctypes, reports, and overrides.

  • Payroll reports (csf_ke/report/.../*.py) generate statutory documents such as P9A, P10, NSSF, and HELB reports.
  • Tax compliance (csf_ke/doctype/.../*.py) creates custom fields for ETR, VAT withholding, and TIMs HS‑codes.
  • Overridden behaviour (csf_ke/overrides/*.py) modifies core ERPNext logic for salary slips, sales documents, and customer validation to embed KRA requirements.
  • Front‑end (csf_ke/public/js/kenya_sales_tax_reco/App.jsx) provides a single‑page UI for the Kenya sales tax reconciliation page.

How It Is Wired

The app hooks into ERPNext’s Doctype framework.

  • Doctype registration occurs in csf_ke/csf_ke/doctype/__init__.py; each Doctype folder (employee_separation_type, kenya_sales_reconciliation, etc.) contains a *.json that defines fields, and a *.py that implements server‑side logic.
  • Overriding core methods: csf_ke/overrides/salary_slip.py replaces frappe.model.document.Document.save for salary slips, adding tax component calculations.
  • Reporting follows the standard ERPNext report pattern: the *.py file imports frappe.get_list and assembles data; the UI is rendered via *.js and *.json.
  • Entry point for the UI is the page csf_ke/page/kenya_sales_tax_reco/kenya_sales_tax_reco.js, which registers the React component defined in csf_ke/public/js/kenya_sales_tax_reco/App.jsx.
  • Network side: when a user opens the reconciliation page, ERPNext loads the page script, which mounts the React component that calls the REST endpoint /api/method/csf_ke.api.fetch_sales_tax. That method is defined in csf_ke/csf_ke/api/update_item_price_list.py and performs a database query on Sales Invoice and Item tables, then returns JSON.

The wiring is linear: page script → React component → API method → Doctype query → JSON response. No cycles or shared mutable state beyond the database.

How To Use It

# clone
git clone https://github.com/moses-y/navari_csf_ke

# install python dependencies
cd navari_csf_ke
pip install -e .

# install node dependencies (frontend assets)
npm install  # package.json present, but no lockfile

# enable the app in ERPNext
bench --site <site> install-app csf_ke

# restart the bench
bench restart

No extra environment variables are required; configuration is in csf_ke/config/csf_ke.py. The app is activated by adding csf_ke to the installed_apps list in sites/<site>/site_config.json.

Real‑World Use

A mid‑size Kenyan firm needs to file the monthly P10 tax return. After installing the app, the finance user navigates to Reports → P10 Tax Report, selects the month, and clicks Generate. The report pulls salary slip data, applies the KRA withholding rates defined in csf_ke/doctype/vat_withholding/vat_withholding.json, and outputs a PDF ready for KRA upload.

Code Health & Issues

  • Missing lockfile – package.json declares npm packages, but no package-lock.json or pnpm-lock.yaml exists, risking non‑deterministic builds.
  • CI coverage – .github/workflows/ci.yml runs tests; 31 test files cover doctypes but no integration tests for the React component.
  • Documentation – 34 markdown files provide guidance, but the README lacks a setup section.

The Bottom Line

The repository delivers a comprehensive set of Kenyan tax and payroll extensions for ERPNext. It follows ERPNext conventions, making it easy to maintain for developers familiar with Doctype overrides. The absence of a JavaScript lockfile and limited frontend tests are the main gaps. Clients needing KRA compliance in Kenya should adopt this app, provided they run a deterministic npm install in a CI pipeline.