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. Uploaded files are temporary and are removed about a day later. This demo is not file storage.
- 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
Nothing to clone yet — evaluate the live demo.
The source code is not public at the moment, so there are no clone commands to publish. The stack itself is real: seven services, an OpenAPI contract, an implementation plan and a documented backlog, sized to run on one laptop.
- RuntimeNode 22 · Docker
- Footprint≈ 4 GB RAM
Until the repository opens, the way to evaluate the system is the guided live demo — real services behind a synthetic tenant, raw status codes on screen — and the contact form for a walkthrough, a briefing or a pilot discussion.
Source availability
The repository is not public — yet.
OpenTax-SA is documented like an open project — an OpenAPI contract, ADRs and a backlog of known gaps — but the code itself is not published at the moment, so there is nothing to fork, star or sponsor today. If you need to see the source for a security review or a procurement decision, ask via the contact form.
Contact
Discuss a pilot, a briefing or a code review.
OpenTax-SA is maintained by its creator. 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.