◆ System Design
Architecture
A multi-surface Shopify app built on Remix, powered by five extensions, communicating through App Proxy and Session Tokens, backed by Supabase and the EU VIES API.
1
System Architecture Diagram
End-to-end data flow from Shopify storefront surfaces through authentication layers to backend services and external APIs.
system-architecture.diagram
+=====================================================================+ | SHOPIFY ECOSYSTEM | | +-------------------+ +-------------------+ +-----------------+ | | | Cart Page | | Checkout (Plus) | | Thank You Page | | | | App Block | | UI Extension | | UI Extension | | | | App Embed (Drawer) | | (Preact) | | (Preact) | | | +--------+----------+ +--------+----------+ +-------+---------+ | | | | | | | +--------+----------+ +--------+----------+ +-------+---------+ | | | Customer Account | | Shopify Function | | Shopify Admin | | | | UI Extension | | Cart Validation | | Webhooks | | | | (Preact) | | (WASM/JS) | | Admin API | | | +--------+----------+ +-------------------+ +-------+---------+ | +===========|=============================================|===========+ | | | | App Proxy HMAC Session Token JWT Webhook HMAC | | | v v v +=====================================================================+ | VAT VALIDATOR APP (Fly.io) | | | | +-------------------------------------------------------------------+ | | Remix 2.x Framework | | | | | | /api/proxy/* /api/validate /webhooks/* | | | /api/proxy/settings /api/thankyou/* /health | | | /api/proxy/customer /api/account/* /app/* (admin) | | +-------------------------------------------------------------------+ | | Service Layer | | | | | | Format Validator VIES Client Cache Service | | | Abuse Protection Tax Exemption Reverse Charge | | | Order Metafield Customer MF Shop Settings | | | Admin API Retry Stats Service | | +-------------------------------------------------------------------+ +===========|======================|======================|===========+ | | | v v v +-------------------+ +---------------------+ +---------------------+ | Supabase | | VIES API | | Shopify Admin API | | PostgreSQL | | EU VAT Validation | | GraphQL | | Cache + Settings | | HTTP/XML | | Metafields/Tax | | Stats + Logs | | ~100 req/min | | Orders/Customers | +-------------------+ +---------------------+ +---------------------+
2
Project Structure
A Remix-based monorepo housing the admin app, five Shopify extensions, shared utilities, database migrations, and comprehensive tests.
project-structure
vat-validator/ ├── app/ # Remix application │ ├── routes/ # API endpoints + Admin pages │ ├── services/ # Business logic (11 services) │ ├── lib/ # Utilities, VIES client, auth │ └── types/ # TypeScript interfaces ├── extensions/ # 5 Shopify extensions │ ├── vat-cart-widget/ # Theme App Extension (App Block + App Embed) │ ├── vat-cart-validation/ # Shopify Function (Cart Validation) │ ├── vat-checkout-ui/ # UI Extension (Plus only, Preact) │ ├── vat-thank-you/ # UI Extension (Preact) │ └── vat-customer-account/# UI Extension (Preact) ├── shared/ # Build-time shared code │ ├── vat-formats.ts # Country regex patterns (27 EU + XI) │ ├── format-validator.ts# Client-side format validation │ └── types.ts # Shared TypeScript types ├── supabase/ # Database │ └── migrations/ # PostgreSQL migration files ├── tests/ # Vitest test suites │ ├── unit/ # Unit tests │ ├── integration/ # Integration tests │ └── e2e/ # End-to-end tests ├── docs/plans/ # Phase plans (29 documents) ├── shopify.app.toml # Shopify app config ├── fly.toml # Fly.io deployment config └── Dockerfile # Container build
3
Extension Architecture
Five purpose-built extensions cover every customer touchpoint, from cart to post-purchase, using Theme App Extensions, UI Extensions, and a Shopify Function.
vat-cart-widget
Theme App Ext
Key Files
blocks/vat-input.liquid
assets/vat-cart.js
assets/vat-drawer.js
locales/en.default.json
vat-cart-validation
Function
Key Files
src/run.ts
input.graphql
shopify.extension.toml
vat-checkout-ui
UI Extension
Plus
Key Files
src/Checkout.tsx
src/components/VatInput.tsx
src/hooks/useVatValidation.ts
vat-thank-you
UI Extension
Key Files
src/ThankYou.tsx
src/components/VatPostCheckout.tsx
src/hooks/useOrderVat.ts
vat-customer-account
UI Extension
Key Files
src/AccountPage.tsx
src/components/VatProfile.tsx
src/hooks/useCustomerVat.ts
4
Communication Patterns
Four distinct communication patterns handle authentication and data flow between Shopify surfaces and the VAT Validator backend.
App Proxy Flow
1
Cart Page
↓
HTTP request via /apps/vat-validator/*
2
Shopify Proxy
↓
Appends HMAC signature
3
Backend /api/proxy/*
↓
Verify HMAC, process request
4
JSON Response
Session Token Flow
1
UI Extension
↓
sessionToken.get() from SDK
2
JWT Token
↓
Authorization: Bearer <token>
3
Backend /api/*
↓
Verify JWT, extract shop
4
JSON Response
Webhook Flow
1
Shopify Event
↓
ORDERS_CREATE, APP_UNINSTALLED...
2
HMAC Signed POST
↓
X-Shopify-Hmac-Sha256 header
3
Backend /webhooks/*
↓
Process event, sync data
4
200 OK
Function Flow
1
Cart Submit
↓
Shopify runs Function
2
input.graphql Query
↓
Read cart attrs + metafields
3
run() Execution
↓
Return errors[] or pass
4
Block / Allow Checkout
5
Shared Code Strategy
Extensions cannot import from the app directory. A prebuild script copies shared modules into each extension at build time, ensuring consistent validation logic across all surfaces.
6
Service Layer
Eleven specialized services handle everything from VAT format validation to tax exemption management, organized by responsibility domain.
Format Validator
VIES Client
Cache Service
Order Metafield Service
Customer Metafield Service
Shop Settings Service
Abuse Protection
Tax Exemption Service
Reverse Charge Service
Admin API Retry
Stats Service
Core Validation
Data / Metafields
Protection
Tax Logic
Infrastructure
7
API Routes
Nine API endpoints serve the five surfaces and system needs, each with appropriate authentication for its communication pattern.
| Route | Method | Auth | Surface | Description |
|---|---|---|---|---|
/api/proxy/validate |
POST | HMAC | cart | Cart VAT validation |
/api/proxy/customer-vat |
GET | HMAC | cart | Customer VAT auto-populate |
/api/proxy/settings |
GET | HMAC | cart | Widget settings |
/api/validate |
POST | JWT | checkout | Checkout validation |
/api/thankyou/save-vat |
POST | JWT | thank_you | Save VAT to order |
/api/thankyou/check-vat |
GET | JWT | thank_you | Check existing VAT |
/api/account/validate |
POST | JWT | account | Account VAT management |
/webhooks/* |
POST | Webhook | system | Webhook handlers |
/health |
GET | None | system | Health check |
8
Performance Requirements
Latency targets across all endpoints, with cached responses returning in under 100ms and VIES-dependent calls bounded by upstream API performance.
| Endpoint | P50 | P95 | P99 |
|---|---|---|---|
| App Proxy cached | 80ms | 150ms | 300ms |
| App Proxy VIES | 600ms | 1500ms | 3000ms |
/api/validate cached |
50ms | 100ms | 200ms |
/api/validate VIES |
500ms | 1500ms | 3000ms |
/api/proxy/settings |
30ms | 80ms | 150ms |
| Admin pages | 200ms | 500ms | 1000ms |
9
Caching Strategy
A three-tier caching architecture minimizes VIES API calls while ensuring validation results stay fresh. Each layer reduces latency and protects against upstream failures.
L1
Fly Proxy (Edge)
Edge-level caching for static settings and repeated requests from the same region.
TTL: 5 min
L2
Supabase Cache (Database)
Persistent cache of VAT validation results in PostgreSQL. Serves as fallback when VIES is unavailable.
TTL: 24 hours
L3
VIES API (Origin)
Real-time validation against the official EU VAT Information Exchange System. No caching at this level.
No cache