jibu tax - Moses Yebei

The Problem

Kenya's Finance Act 2023 Section 16 mandates that no business expense is tax-deductible without an official eTIMS electronic tax invoice. This requirement has created an existential crisis for East Africa's 16 million informal traders, who lack access to the laptops, smartphones, and stable broadband required by existing eTIMS clients. Missing a monthly filing triggers an immediate KES 2,000 fine per trader, exposing millions to financial ruin or exclusion from corporate supply chains.

What This Does

JibuTax transforms any cellular phone line into a government-compliant fiscal point-of-sale terminal. The backend (backend/app/main.py) is a FastAPI application wired with LangGraph to manage a multi-agent workflow. The orchestrator (orchestrator/conversation_state_machine.py) manages the conversation flow, routing user input through agent nodes located in backend/app/agent/nodes/: extraction.py parses spoken trade details (Swahili/Sheng/English), tax_math.py calculates the 1.5% Turnover Tax, and validation.py checks compliance. The KRA integration is handled by backend/app/services/kra_service.py and exposed via backend/app/api/v1/kra.py. On the frontend, frontend/src/App.jsx bootstraps the React application via Vite, with UI components like TaxCalculator.jsx and InvoiceViewer.jsx interfacing with the API through frontend/src/services/api.js. Month-end autonomous filing is handled by backend/app/cron/month_end.py and backend/app/celery_app.py, which aggregate ledger data and submit NIL returns with Obligation Code 7 if sales are zero.

How It Is Wired

Execution begins at backend/app/main.py, which starts the FastAPI server and initializes the Celery app for background task processing. The conversation state machine in orchestrator/conversation_state_machine.py acts as the primary router, passing the dialogue context to the agent graph (backend/app/agent/graph.py). This graph sequences the nodes: extraction extracts structured data from unstructured speech, tax_engine.py (implied by the node list and services) performs the calculations, and kra_service.py submits the return. The resulting invoice is dispatched via backend/app/services/whatsapp_dispatcher.py or SMS. The database layer resides in backend/app/database.py, utilizing models defined in backend/app/models/ (taxpayer.py, tax_return.py, invoice.py, ledger.py). The immutable ledger is a core dependency for the cron job's aggregation logic. Outside the process, the system interfaces with KRA's eTIMS API and, via elevenlabs/agent_config.json and orchestrator/elevenlabs_webhook.py, handles voice input and synthesis.

How To Use It

Setup:

Backend: cd backend && pip install -r requirements.txt
Frontend: cd frontend && npm install
Docker: docker-compose up --build (defined in root docker-compose.yml)

Configuration:

Copy .env.example files from the root, backend/, and orchestrator/ to .env.
Required keys (inferred from README and service files) include KRA credentials, M-Pesa till numbers, and ElevenLabs API keys. See .env.example for the defined variables.

Running it:

Start the API: uvicorn backend.app.main:app --reload
The test suite can be invoked from the root: pytest (configurable via pytest.ini).

Real-World Use

A trader dials the JibuTax number. The elevenlabs_webhook.py processes the incoming audio, feeding it into the conversation_state_machine.py. The agent extracts: "I sold goods to a Safari Hotel for 5,000 shillings." The tax_engine calculates the 1.5% turnover tax (75 shillings). kra_service.py submits the eTIMS return, and whatsapp_dispatcher.py sends the official QR-stamped invoice to the trader's WhatsApp within the 500ms target window. On the 18th of the month, cron/month_end.py runs autonomously, aggregating the ledger and filing a NIL return if no sales occurred, protecting the trader from the KES 2,000 late-filing penalty.

Code Health & Issues

Medium - No LICENSE file found in root: Usage and redistribution rights are unclear despite the MIT badge in the README.
Medium - No CI/CD pipeline detected: No automated build or test gate exists in .github/; the README claims "65/65 Passed," but the static analysis confirms the absence of pipeline configuration.

The Bottom Line

This is a technically dense, well-structured repo that successfully bridges a complex regulatory gap (KRA eTIMS) with a low-friction interface (voice phone calls). The LangGraph multi-agent architecture is the standout feature, providing clear modularity for the extraction, tax, and filing stages. However, the missing license file and complete lack of CI/CD are significant barriers to professional adoption and contribution. It is best suited for fintech teams or NGOs in East Africa needing to modernize tax compliance for informal traders, provided they can secure the necessary API keys and address the SDLC gaps.

What the analyser found

Deployment readiness

5/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

108 files

Python71
Markdown8
JSX8
JSON4
JavaScript4
YAML2

ReactFlaskExpressTailwindDocker

Module dependencies

The 10 most depended-upon modules of 83, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_frontend_src_services_api["api"] n1_frontend_src_App["App"] n2_d_src_components_InvoiceList["InvoiceList"] n3_src_components_InvoiceViewer["InvoiceViewer"] n4_nd_src_components_PinChecker["PinChecker"] n5_src_components_TaxCalculator["TaxCalculator"] n6_rc_components_VoiceSimulator["VoiceSimulator"] n7_ontend_src_components_Header["Header"] n8_frontend_src_main["main"] n9_backend_app___init__["__init__"] n1_frontend_src_App --> n7_ontend_src_components_Header n1_frontend_src_App --> n6_rc_components_VoiceSimulator n1_frontend_src_App --> n3_src_components_InvoiceViewer n1_frontend_src_App --> n5_src_components_TaxCalculator n1_frontend_src_App --> n4_nd_src_components_PinChecker n1_frontend_src_App --> n2_d_src_components_InvoiceList n2_d_src_components_InvoiceList --> n0_frontend_src_services_api n3_src_components_InvoiceViewer --> n0_frontend_src_services_api n4_nd_src_components_PinChecker --> n0_frontend_src_services_api n5_src_components_TaxCalculator --> n0_frontend_src_services_api n6_rc_components_VoiceSimulator --> n0_frontend_src_services_api n8_frontend_src_main --> n1_frontend_src_App

Dependencies

15 of 31 declared dependencies are a major version behind. Resolved 31 of 31 against the registry.

Package	Declared	Latest	Behind
`redis`	>=5.0.0,<6.0.0	8.1.0	3 major
`langchain-google-genai`	>=1.0.1	4.3.4	3 major
`vite`	^5.1.6	8.2.1	3 major
`@vitejs/plugin-react`	^4.2.1	6.0.5	2 major
`langgraph`	>=0.0.30	1.2.11	1 major
`langchain-core`	>=0.1.30	1.5.5	1 major
`qrcode`	>=7.4.2,<8.0.0	8.2	1 major
`pytest`	>=8.1.0,<9.0.0	9.1.1	1 major

Findings

MediumNo CI/CD pipeline detected - no automated build/test gate .github/ or CI config
MediumNo LICENSE file - unclear usage/redistribution rights root

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high3

medium3

low1

Add a LICENSE; redistribution rights are undefinedhigh

no licence file at the repository root

Fix: Add MIT or Apache-2.0 at the repository root.

Add a workflow that builds and tests this repositoryhigh

83 source files, no CI configuration

Every change merges with nobody having run the build once, which across this estate is 499 repositories.

Fix: Add a workflow running the project build and test command on push and pull_request.

Add a build gate for the deployable artifacts herehigh2 occurrences

backend/Dockerfile

deployment artifacts with no workflow

Something in the repo is meant to reach a server and no automated step has ever validated it, which is the state of 125 repositories here.

Fix: Add a workflow that at least builds the image and validates the manifests.

Enable Dependabot or Renovatemedium

3 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium

backend/Dockerfile

python:3.10-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Add a non-root USER to the imagemedium

backend/Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.