Technical Architecture Summary
Hoike Technologies — VAT API Toolkit (MTD VAT, Flat Rate–only)
Scope & HMRC Approval Focus
Hoike Technologies intentionally implements only the two mandatory
MTD VAT endpoints required for HMRC production credential approval:
- Retrieve VAT obligations
- Submit VAT return
The system is Flat Rate–only by design. All other endpoints are deliberately
deferred until post-approval.
1) System Overview
The VAT API Toolkit is a Node.js (Express, ESM) web application backed by PostgreSQL
(Prisma ORM). It implements a tightly controlled VAT submission pipeline prioritising
determinism, auditability, and HMRC compliance.
The platform supports Flat Rate Scheme VAT only, with both
automated invoice aggregation and explicit manual turnover entry, depending on
the client’s Flat Rate category.
2) Major Components
Web Application (Express)
- Client-facing routes for obligations → preview → submit.
- Admin routes for sandbox test-user management and audit tooling.
- Server-side rendering (EJS) for transparent, reviewable VAT flows.
Data Layer (PostgreSQL + Prisma)
- Client: VRN, Flat Rate category, percentage, environment flags.
- Invoice & InvoiceProcessingRun: source data and normalized outputs.
-
VatReturnPreview:
authoritative, hash-locked snapshot of a VAT return for a period.
-
VatReturnSubmission:
idempotent submission record including HMRC receipts.
- OAuthCredential (sandbox) and HmrcAuth (production).
HMRC Integration Layer
- Environment-aware HTTP client (sandbox vs production).
- Refresh-token–based OAuth lifecycle management.
- Mandatory fraud-prevention headers enforced in production.
3) Environment Model
Sandbox and production are strictly isolated at the credential, token, and data level:
| Mode |
Token Store |
VRN Used |
Purpose |
| Sandbox |
OAuthCredential |
Sandbox test-user VRN |
End-to-end functional testing |
| Production |
HmrcAuth |
Live client VRN |
Real VAT submissions |
4) End-to-End VAT Journey
A) Retrieve Obligations
- Valid HMRC authorization is verified.
- The system retrieves open VAT obligations.
- A periodKey is selected for preparation.
B) Preview (Authoritative Snapshot)
- Flat Rate category determines data source (AUTO or MANUAL).
-
For AUTO categories, invoice processing runs are aggregated into gross turnover.
-
For MANUAL categories, turnover is explicitly entered and confirmed by the user.
-
A deterministic HMRC payload is generated and written to a
VatReturnPreview snapshot.
-
A payload hash is stored; all subsequent renders use this snapshot.
C) Submit Return
- Submission is only allowed from a confirmed preview snapshot.
- Payload hash is re-verified immediately before submission.
- Idempotent submission records prevent duplicate filings.
- HMRC responses and timestamps are persisted for audit.
5) Reliability, Safety, and Auditability
- Snapshot immutability: preview data is not recomputed silently.
- Manual confirmation audit: manual turnover requires explicit confirmation.
- Payload hashing: prevents preview/submission drift.
- Idempotent submission: guards against retries and double-clicks.
- Admin audit & rebuild: controlled admin-only rebuild with full traceability.
6) Planned Post-Approval Expansion
After HMRC production approval, Hoike Technologies plans to extend support to additional
MTD VAT endpoints (liabilities, payments, financial details, penalties) and broader Flat Rate
categories, while retaining the same snapshot-based, audit-first architecture.
Document: Technical Architecture Summary • Prepared for HMRC and internal operational review.