The filing experience before TaxBridge
Nigerian SME tax filing can involve repeated manual entry, fragmented records, and uncertain confirmation across multiple submission steps. The central risk is not just time; it is errors compounding without a machine-readable audit trail or a reliable way to reconcile an interrupted submission.
TaxBridge was designed to reduce that friction by automating repeatable steps and making correctness a property of the workflow. Timing measurements exist in private project records, so this public case study focuses on the inspectable architecture.
Why Row-Level Security at the database engine, not the application
The first design decision was the one that mattered most: multi-tenancy enforcement.
Every tax filing platform handles data from multiple clients. The question is where the boundary between tenants is enforced. Application-layer filtering — adding a WHERE tenant_id = ? clause to every query — is fragile. An application bug, a missed WHERE clause, or an ORM quirk can silently expose one tenant's records to another.
TaxBridge enforces the tenant policy at the PostgreSQL engine level via Row-Level Security. When the RLS policy is active for the application role, a query that omits its tenant predicate still remains subject to the database policy. That moves the isolation boundary out of each query path and into a schema-level control that can be exercised directly in tests.
The reason this matters: an application-layer filter alone is not a sufficient tenant boundary. RLS policies attached to the database schema narrow the failure surface and can be exercised directly in isolation tests.
Idempotent job queues for NRS API rate limits
The Nigeria Revenue Service integration boundary is treated as rate-limited and failure-prone. Filing windows can create burst traffic, so the internal workflow cannot assume that an external submission will complete synchronously.
The naive approach: queue requests and retry on 429. This works until a job fails mid-execution, because the retry re-sends the same request and the NRS API processes it again, producing a duplicate submission.
BullMQ queues in TaxBridge are idempotent by design. Each job carries a stable identifier derived from the submission content. Before execution, the worker checks whether this identifier has already been successfully processed. If it has, the job is marked complete without re-submitting. If it has not, submission proceeds and the identifier is recorded.
The outcome: retries remain tied to a stable submission identity, and workers can reconcile completed work before issuing another external request. Public artifacts describe the mechanism; private integration evidence is not presented as agency certification.
Cached real-time tax calculations
VAT, withholding tax, and annual return calculations are computationally inexpensive but latency-sensitive — users see the result in real time as they enter figures, so each calculation must complete within a perceptible threshold.
The implementation uses Redis as the computation cache for jurisdiction-specific rule lookups. Tax rules change infrequently; caching the rule set per jurisdiction per tax period means the calculation path is a pure function on cached data, with no database round-trips on the hot path.
The calculation layer remains stateless and scales independently from the external submission queue. This keeps the interactive path separate from slower or unavailable third-party services without publishing an unlinked latency claim.
Hash-chained audit trail
The NRS requires an immutable audit trail for every submitted return. An audit trail that can be retroactively edited is not an audit trail — it is a log with deletion access.
TaxBridge implements a hash-chained record structure. Every audit event is cryptographically bound to the previous event's hash. Any retroactive modification breaks the chain at the point of modification, producing a chain-break that is detectable without access to the original data.
This is the same principle used in append-only ledger systems. Applied here, it means the audit trail is a first-class correctness property of the data model, not a reporting layer added after submission.
Tests as an audit artifact
Coverage alone does not establish compliance. The useful evidence is a focused test suite that maps jurisdiction rules, calculation edge cases, and submission state transitions to executable behavior.
Those tests provide an internal audit trail for the implementation. They do not imply regulator endorsement or certification.
What TaxBridge demonstrates
Nigerian SME tax filing is a hard problem because it sits at the intersection of unreliable external APIs, strict audit requirements, and users who will not tolerate a slow or opaque system.
The architecture answer: enforce correctness at the database layer, make every external API call idempotent, cache computation aggressively, and build the audit trail into the data model rather than on top of it. Each of these is a general principle for compliance-critical systems. TaxBridge applies them in combination, against a specific real-world constraint set.