Open source · MPL-2.0 · South Africa

A secure reference architecture for digital tax submission APIs.

OpenTax-SA shows how a government-scale tax filing platform could be built: OAuth 2.1, consent, validation-gated returns, durable events, and an HMAC audit chain — as an honest educational system, not a live revenue service.

View the repository Try the live demo Sponsor

Seven services

Gateway, auth, consent, submission, validation, audit, and notifications — each with a clear boundary.

Security-first

OAuth 2.1 with PKCE, DPoP, rotating refresh tokens, object-level authorisation, and HMAC service auth.

Built to study

PostgreSQL, Redis, NATS JetStream, Docker Compose, and a full OpenAPI contract you can run on a laptop.

Architecture at a glance

Clients talk to the API gateway. Auth issues tokens. Consent gates submission. Validation decides whether a return continues. Events leave through a transactional outbox into JetStream.

External client
      │
      ▼
 API Gateway  ──► Auth (OAuth 2.1 / DPoP)
      │
      ├─► Consent / DSAR
      ├─► Tax Submission ──► Validation Engine
      ├─► Audit (HMAC hash chain)
      └─► Notification (email or log)
                 ▲
                 │  outbox → NATS JetStream
 PostgreSQL · Redis · Object storage

What people can build with this repo

A practitioner portal that files on behalf of clients after consent.
An accounting-software connector that submits returns and polls status.
A taxpayer status page and document inbox.
A privacy desk for consent and access-request exports.
A classroom or conference sandbox for digital-government architecture.

You cannot build a real eFiling site on this code alone. There are no authentic SARS rates or legal rules here.

Live demo

Synthetic users only. The demo API and auth endpoints are reached through a Cloudflare Tunnel to a small Oracle Cloud always-free VM.

API health Auth health How the flow works

If a health check fails, the demo VM may be restarting. The marketing site stays up on Cloudflare Pages.

Run it yourself

git clone https://github.com/bseptember/opentax-sa.git
cd opentax-sa
npm ci
docker compose --profile services up -d --build
bash scripts/e2e-flow.sh

Needs Node 22, Docker, and about 4 GB RAM for a comfortable local stack. Full docs live in the repository under docs/.