Technical Architecture Summary

Hoike Technologies — VAT API Toolkit (MTDfB VAT, Flat Rate–only)

Scope & HMRC Approval Focus

Hoike Technologies intentionally implements only the two mandatory MTDfB 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.

The system is designed with a safety-first submission architecture, enforcing strict environment isolation, deterministic payload generation, and multi-layer validation before any HMRC interaction.

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.
Strict separation of sandbox and production OAuth flows.
Token storage segregated by environment and identity type.
Client connection state tracked via hmrcConnectionStatus.

Background Workers

Obligation synchronization worker.
VAT payment reconciliation worker.
Reminder notification worker.
Worker health monitoring with audit tracking.

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) Submission Safety Architecture

VAT submission is governed by a multi-layer safety system designed to prevent accidental, duplicate, or invalid filings.

Environment guards: Non-production environments cannot submit to HMRC production.
Sandbox isolation: Clients connected via sandbox cannot submit to live HMRC.
Submission confirmation: Token-based confirmation step prevents accidental submission.
Payload verification: Snapshot hash must match reconstructed payload.
Invoice fingerprinting: Detects data drift between preview and submission.
Idempotency: Unique submission constraints prevent duplicate filings.
Submission locks: Prevent concurrent or repeated submission attempts.

6) Reliability, Auditability, and Compliance

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.
Compliance event logging: All critical actions (OAuth, submission attempts, failures, and blocks) are recorded via a structured ComplianceEvent system.
Submission blocking audit: All blocked submissions are logged with reason codes for traceability.
Environment-aware safeguards: Runtime checks enforce strict separation between sandbox, staging, and production.

7) Environment & Deployment Model

Development: Local environment using sandbox HMRC APIs.
Staging: Isolated database and environment for pre-production testing.
Production: Live environment with HMRC production credentials and strict safety controls.

Each environment maintains separate configuration, credentials, and database instances to ensure complete isolation and eliminate cross-environment risk.

8) Planned Post-Approval Expansion

After HMRC production approval, Hoike Technologies plans to extend support to additional MTDfB VAT endpoints (liabilities, payments, financial details, penalties) and also MTD for Income Tax, while retaining the same snapshot-based, audit-first architecture.

Document: Technical Architecture Summary • Prepared for HMRC and internal operational review.