Web app and API for UK PAYE-style tax and National Insurance calculations. Seven calculators cover the common employment / self-employment / company- director / investor scenarios, all backed by the same HMRC-spec engine.

Live demo: https://tax.log7.uk/

• Implements the HMRC PAYE Tax Table Routines specification v24.0 (February 2026) — including the prescribed rounding directions (Free Pay up to 1p, Taxable Pay down to £1, final tax down to 1p). See docs/HMRC_PAYE_PIPELINE.md for the full mapping of spec sections to source code and known follow-ups.
• Supports English & Northern Irish, Scottish (S prefix, SRIT) and Welsh (C prefix, WRIT) tax codes.
• Public read-only API mirrors the calculator forms (no auth required; 60 requests/minute throttle per IP). Per-mode endpoint: POST /api/calculate/<mode>/ with <mode> ∈ paye / limited_co / umbrella / ir35 / sole_trader / dividend / sa_estimator.
• Tax rates are stored in DB and synced from seed data committed to the repository — see calculator/tax_rate_seed_data.py.
• 195 tests across unit (helpers, rounding directions, tax-code parsing), integration (per-mode flows) and HMRC reference vectors.

The calculator's output matches HMRC's reference Tax Tables to the penny (cumulative and non-cumulative basis) for the following scenarios. Every conformance claim below is backed by a reference vector in calculator/reference_vectors/hmrc_paye_{2024,2025,2026}.json and an integration test in calculator/test_hmrc_reference_vectors.py

• calculator/test_hmrc_parity.py; helper-level rounding behaviour is covered separately in calculator/test_helpers.py (195 tests total across the suite).

What is not covered yet:

• IR35 status determination — the IR35 tab quantifies the cost of an inside-IR35 placement, it does not decide whether you are inside.
• Multiple PAYE employers in the same year.
• Annual Maximum NIC reconciliation between Class 1 and Class 4 for high earners with both PAYE and self-employment.
• Self Assessment estimator v1 does not model: savings interest + Personal Savings Allowance, High Income Child Benefit Charge, Payments on Account cash-flow, Capital Gains Tax. Scoped for a future v2 pass.

make install        # creates .venv, installs deps and pre-commit hooks
make migrate
make sync-rates
make run            # http://127.0.0.1:8000/

Or via Docker (closer to production):

make docker         # builds + runs the container on http://localhost:9000/

make help lists every common command (test, lint, fmt, docker, smoke, …).

The API is public read-only — it mirrors the calculator forms exactly, just with a JSON response. Throttling (60 requests/minute per IP) is the only protection. A per-customer authenticated tier will be added when the B2B paid plan is launched.

Per-mode endpoint at /api/calculate/<mode>/ where <mode> ∈ paye / limited_co / umbrella / ir35 / sole_trader / dividend / sa_estimator:

curl -X POST http://127.0.0.1:8000/api/calculate/paye/ \
  -H "Content-Type: application/json" \
  -d '{
        "tax_year": 2025,
        "income": 60000,
        "income_type": "yearly",
        "workweek_hours": 40,
        "tax_code": "1257L",
        "is_blind": false,
        "no_ni": false,
        "is_scotland": false
      }'

Tax-rate lookups are also public:

curl http://127.0.0.1:8000/api/tax-rates/

POST/PUT/PATCH/DELETE on /api/tax-rates/ return 405 Method Not Allowed — official rates cannot be mutated through the API.

The project ships as a Docker container. make docker builds and runs a development container (DEBUG=True, full analytics capture); make docker-prod builds and runs a production-mode container (DEBUG=False, anonymised analytics retention, auto-generated SECRET_KEY). Both expose the app on port 9000 by default and are intended to sit behind a reverse proxy that terminates TLS.

An Azure Web App demo deployment exists at tax-calculator-abhnf5crftcxg4fu.eastus-01.azurewebsites.net as a CI/CD skills showcase; auto-deploy on push is disabled.

• User Guide — what every option on the form means and the UK tax concept behind it. Read this if you're using the calculator and aren't sure which Pension scheme / tax code / calculation basis applies to you.
• Architecture — how the codebase fits together: form/view dispatch, calculation engine layout, UI architecture (mode tabs → cards → collapsibles), data model split, test strategy, deployment flow, decision log. Read this if you're changing code.
• HMRC pipeline methodology — the spec-section-to-source-code mapping for the PAYE flow, plus the rounding-directions reference table.

• PAYE & NI calculations follow the HMRC PAYE Tax Table Routines specification v24.0 (February 2026). Pension, student loans (Plans 1/2/4/5/Postgrad), dividend tax, Limited Company flow with salary/dividend split optimiser, Director's NI annual cumulative basis, Umbrella, Sole Trader, Dividend (standalone investment- dividends), and Self Assessment estimator (multi-source combiner) are all implemented. Embeddable iframe widget at /embed/<mode>/ for B2B distribution.

Published under the GNU Affero General Public License v3.0 (full text). In short: free to use, study, modify and self-host. If you run a modified version as a network service, you must publish your source under the same licence. Suitable for personal, educational and non-commercial use; commercial integrations that don't want the AGPL source-publication obligation should contact @loglux for a commercial-licence arrangement.

Copyright © 2026 @loglux.