Open-source reference architecture · South Africa
A national tax platform, open for study.
OpenTax-SA is a working reference architecture for a government-scale tax submission API — OAuth 2.1 with DPoP, POPIA consent, validation-gated returns, a transactional outbox and a tamper-evident audit chain — complete, runnable on a laptop, and deliberately honest about what it is not.
What it demonstrates
The hard parts of tax infrastructure, done in the open.
Not slides — a running system with tests, an OpenAPI contract and a backlog of documented gaps. These five mechanisms are the reason the codebase exists.
OAuth 2.1 with DPoP
Authorization code + PKCE for every client, Ed25519-signed tokens, rotating refresh tokens with reuse detection, and optional sender-constrained access (RFC 9449).
EdDSA · RFC 9449POPIA consent gate
Submission writes fail closed unless an active, purpose-scoped consent record exists for exactly that data subject and client.
POPIA · fail closedValidation-gated lifecycle
A return only becomes an assessment by passing a deterministic validation state machine — illegal transitions are refused with typed errors, not silently coerced.
state machineTransactional outbox → JetStream
Domain events are journalled in the same SQL transaction as the write, then relayed at-least-once to NATS JetStream. No dual-write inconsistencies.
outbox · NATSTamper-evident audit chain
Every consequential action lands in an HMAC-SHA256 hash-chained log — reorder, edit or delete a row and the chain visibly breaks.
HMAC-SHA256Architecture
Seven services, one honest system.
A gateway fronts everything and enforces authn/authz. Each service owns its schema and its state machine; nothing reaches the audit chain or the message bus by accident.
Diagram is full-size — swipe horizontally to explore it.
Applications and limits
What you can build with it — and what you cannot.
The codebase is a foundation, not a finished ministry. Equally: it is not a disguised eFiling product, and the limits are enforced in code, not just prose.
-
A practitioner portal
Mandate-based filing on behalf of clients — the gateway derives identity from the token, never from request parameters.
-
An accounting-software connector
A confidential OAuth client that submits final returns, polls status, and reads illustrative assessment responses.
-
A classroom or conference sandbox
The whole digital-government surface — consent, DSAR, audit, events — runs on one laptop with Docker Compose.
-
A privacy desk
POPIA access packs are generated server-side, and deletion requests complete with a documented retention notice.
Live demo
Walk the whole flow in three minutes.
A guided browser journey against the real services — sign in as a synthetic taxpayer, grant consent, submit a return, watch validation gate it, recover, and read the illustrative assessment. Raw status codes and tracking IDs are shown at every step.
- 01 sign in as the printed synthetic demo taxpayer
- 02 grant POPIA consent for tax_submission
- 03 create + submit a final IT12 (PKCE code flow)
- 04 validation_failed → fix → reopen → resubmit → accepted
- 05 illustrative assessment · document upload · DSAR
Run locally
Seven services, one laptop, four commands.
The repo is the spec: the OpenAPI contract, an implementation plan, ADRs and a
backlog of known gaps all live under docs/. The end-to-end script
exercises OAuth, consent, submission, validation and revocation against real
Postgres, Redis and NATS.
- RuntimeNode 22 · Docker
- Footprint≈ 4 GB RAM
- Contractdocs/api/openapi.yaml
- LicenseMPL-2.0
# clone and boot the full stack $ 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 # the script prints the whole trace — # authorize → token → consent → submit → accept
Open source
Mozilla Public License 2.0. Fork it, read it, tear it apart.
Serious reviewers are the intended audience. The security model, the ADRs and the backlog are all public — if you find a gap, the honest response is an issue, and the docs are treated as the spec.
MPL-2.0 · file-level copyleft
Contact
Discuss a pilot, a briefing or a code review.
OpenTax-SA is maintained by Brandon September. If you work in digital public infrastructure and want a technical walkthrough, a security briefing, or to explore what a pilot of this reference architecture could look like — send a note. Straight answers, no deck required.