High Level Architecture

This section establishes the foundational architecture decisions, platform choices, and system design patterns that guide the entire Fiscalization implementation.

Technical Summary

Fiscalization implements a local-first engine architecture with cloud management plane. A single Go binary contains the core API and all country adapters, deployable on customer infrastructure or hosted by Zyntem on GCP. The system consists of:

Fiscalization Engine (Go + Gin, single binary): Unified REST API containing core routing, multi-tenant authentication, transaction orchestration, and all country-specific adapter logic (Spain/TicketBAI/Verifactu, Italy/SDI, France/NF525). Runs identically on ISV partner hardware, Docker, POS appliances, or Zyntem-hosted Cloud Run.
Management Plane (Go, Cloud Run): Cloud service handling agent registration, heartbeat ingestion, binary distribution, license management, and fleet monitoring. Optional for on-premise deployments.
Dashboard (Next.js 14 App Router): Developer-facing UI for transaction inspection, location management, API key generation, certificate upload, and fleet monitoring (hosted mode and management plane)
Documentation Site (Docusaurus): Interactive API reference with live mock testing, SDK code examples, and country-specific integration guides

Integration Points:

Country adapters are compiled into the engine binary (no inter-service HTTP calls)
Dashboard consumes Core API via REST endpoints (authenticated with NextAuth.js sessions)
Tax authority integrations isolated within adapter packages (Spain: AEAT, Italy: AdE SDI, France: NF525 local logging)
Cloud Storage (hosted mode) or local filesystem (on-premise mode) serves receipts, QR codes, and audit logs
Management plane communicates with deployed engines via registration and heartbeat protocols

Infrastructure Platform:

Compute: Cloud Run for hosted mode and management plane (serverless containers, auto-scaling 0-10 instances); customer infrastructure for on-premise mode
Database: Cloud SQL PostgreSQL (hosted mode) or embedded SQLite (on-premise mode) — same Store interfaces, config-driven selection
Storage: Cloud Storage for receipts in hosted mode (Standard class), local filesystem for on-premise mode
Secrets: Secret Manager (hosted mode) or local configuration file (on-premise mode) for API keys, X.509 certificates, tax authority credentials

How This Achieves PRD Goals:

Developer Experience (NFR3: <10min first transaction): OpenAPI-driven SDK generation (6 languages), interactive docs with mock API (no signup required), instant API key generation
Reliability (NFR2: 99.5% uptime hosted): Engine binary isolation prevents cascading failures, Cloud Run 99.9% SLA for hosted mode, circuit breakers on tax authority calls, on-premise mode eliminates network dependency on Zyntem
Country Expansion Velocity (30% faster development): Adapter generator tool scaffolds new countries, shared types ensure contract consistency, single binary simplifies testing
Cost Efficiency: On-premise mode shifts compute costs to customer; hosted mode uses serverless compute (scale-to-zero, $323/month infrastructure = 14-28% of target MRR)
Deployment Flexibility: Same binary runs anywhere — customer data center, Docker, or Zyntem Cloud Run. No vendor lock-in for customers.

Deployment Topology

The system supports two deployment modes sharing a single engine binary. Configuration (via fiscalization.yaml or environment variables) determines which backend services are used.

Data Plane (Fiscalization Engine)

Single Go binary (fiscalization-engine) containing core API and all country adapters. Exposes the same REST API (/fiscalization/v1/*) regardless of deployment mode.

Embedded-Cloud Mode: Engine binary runs on Cloud Run. PostgreSQL via Cloud SQL. Cloud Storage for receipts and audit logs. Multi-tenant, managed by Zyntem. ISV partners call the API from their backends.
Embedded-Local Mode: Engine binary runs on ISV partner infrastructure (bare metal, VM, Docker, POS appliance). Embedded SQLite (WAL mode, pure Go via modernc.org/sqlite). Local filesystem for receipts and audit logs. Single-tenant per deployment.

The binary is cross-compiled with CGO_ENABLED=0 for maximum portability. No C dependencies.

Control Plane (Management Plane)

Cloud service running on GCP Cloud Run. Provides:

Agent Registry: Tracks all deployed engine instances (version, OS, architecture, deployment mode)
Heartbeat Ingestion: Receives periodic health reports from engines, detects offline agents
Binary Distribution: Serves engine binary updates via Cloud Storage signed URLs
License Management: Validates license keys, enforces feature gates
Fleet Monitoring: Dashboard visibility into all deployed agents, versions, and health status

The management plane is optional for on-premise deployments. Engines operate fully independently when the management plane is unreachable.

Embedded-Cloud Mode (formerly "Hosted")

Zyntem runs the engine binary on Cloud Run with Cloud SQL PostgreSQL and Cloud Storage. ISV partners call the API from their own cloud backends. This preserves the original SaaS architecture (multi-tenant) — existing GCP infrastructure serves this mode directly.

Embedded-Local Mode (formerly "On-Premise")

ISV partners bundle and run the engine binary within their own product deployment (bare metal, VM, Docker, POS appliance) with embedded SQLite and local filesystem storage. The ISV's end-users (merchants) interact with the ISV's product, not with Zyntem directly. The management plane connection is optional but recommended for:

Automatic binary updates
Fleet health monitoring
License validation (per-merchant, not per-agent)
Centralized audit log aggregation (future)

Platform and Infrastructure Choice

Platform: Google Cloud Platform (GCP) — for hosted mode and management plane

Key Services (Hosted Mode + Management Plane):

Cloud Run: Serverless container platform for hosted engine instances and management plane
Cloud SQL PostgreSQL: Managed relational database for hosted mode (db-f1-micro for dev, db-n1-standard-1 for production)
Cloud Storage: Object storage for receipts, QR codes, XML audit logs (Standard class with lifecycle policies); also serves engine binary distribution for updates
Secret Manager: Encrypted storage for API keys, X.509 certificates, tax authority credentials
Cloud CDN: Global content delivery for receipts and static documentation assets
Cloud Monitoring + Cloud Trace: Observability with OpenTelemetry integration
Cloud Functions: Scheduled tasks (LROE batch submission, certificate expiration alerts, usage metering)

On-Premise Runtime:

Single Go binary, cross-compiled (CGO_ENABLED=0), no external dependencies
Embedded SQLite via modernc.org/sqlite (pure Go, no CGO required)
Local filesystem for receipt storage and audit logs
Optional TLS termination via built-in or reverse proxy (nginx, Caddy)

Management Plane Infrastructure:

Cloud Run service for agent registry and heartbeat API
Cloud SQL PostgreSQL for agent metadata, license records, fleet state
Cloud Storage for binary distribution (signed URLs, versioned artifacts)

Deployment Host and Regions:

Primary Region: europe-west1 (Belgium) - GDPR compliant, low latency to Spain/Italy/France tax authorities
Failover Region: europe-west3 (Frankfurt) - Phase 2 expansion for high availability (99.95% SLA)
CDN: Global edge locations (Cloud CDN for receipts, Firebase Hosting CDN for dashboard)
On-Premise: Customer-chosen location, no region constraints

Alternative Platforms Considered:

Platform	Pros	Cons	Decision
Vercel + Supabase	Rapid development, Next.js native, built-in auth	Limited control over backend services, Supabase pricing scales aggressively ($0.125/GB after 10GB free), no serverless Go support	Rejected: Backend requires Go (swaggo OpenAPI integration), unpredictable scaling costs
AWS Full Stack (Lambda, API Gateway, RDS, S3, Cognito)	Mature ecosystem, broad service catalog, extensive documentation	Higher operational complexity (IAM, VPC config), 25% more expensive ($450-500/month vs GCP $323/month), steeper learning curve	Rejected: More expensive, higher operational complexity (Lambda + API Gateway + ALB orchestration)
Azure (Functions, PostgreSQL, Blob Storage, AD B2C)	Excellent .NET integration, strong enterprise support, AI services	Less suited for Go ecosystem, similar cost to AWS, team has no Azure experience	Rejected: Not leveraging .NET, no cost advantage, Go ecosystem weaker
GCP (Cloud Run, Cloud SQL, Cloud Storage, Secret Manager)	40% cheaper than AWS, Cloud Run operational simplicity (no K8s), Go-friendly, managed PostgreSQL + Redis, OpenTelemetry native	Smaller service catalog vs AWS, fewer community resources	SELECTED: Cost-efficient ($323/month), operational simplicity saves 20+ hours/month maintenance, Go ecosystem alignment, EU data residency built-in

Recommendation Rationale:

Cost Efficiency: $323/month total infrastructure for hosted mode + management plane (40% cheaper than AWS equivalent). On-premise mode shifts compute costs to customer.
Simplicity: Cloud Run abstracts container orchestration, fully managed PostgreSQL reduces maintenance to <5 hours/month
Go Ecosystem: First-class Go support, strong OpenTelemetry integration, Cloud Run optimized for long-running HTTP services
EU Data Residency: europe-west1 ensures GDPR compliance (Italian data must remain in EU per NFR8). On-premise mode gives customers full data sovereignty.
Scaling Economics: Infrastructure cost as % of revenue drops from 28% (10 customers) to 5% (1,000 customers). On-premise customers require zero Zyntem infrastructure beyond the management plane.

Management Plane Architecture

The management plane is a lightweight cloud service providing fleet management for all deployed fiscalization engine instances. It runs on GCP Cloud Run and is the only Zyntem-operated service required for on-premise deployments (and even this is optional).

Registration Protocol

On first startup, the engine binary registers with the management plane:

POST /management/v1/agents/register
{
  "license_key": "lic_...",
  "partner_id": "partner_...",
  "engine_version": "1.2.3",
  "os": "linux",
  "arch": "amd64",
  "deployment_mode": "embedded-local",
  "hostname": "pos-server-01",
  "merchant_count": 12
}

Response includes an agent_id (UUID) and heartbeat_interval (default: 60s). The agent persists its agent_id locally for subsequent heartbeats.

If the management plane is unreachable at startup, the engine operates normally. Registration retries in the background with exponential backoff (1s, 2s, 4s, ... max 5min).

Heartbeat Protocol

Registered agents send periodic heartbeats:

POST /management/v1/agents/{agent_id}/heartbeat
{
  "engine_version": "1.2.3",
  "uptime_seconds": 86400,
  "transactions_since_last": 142,
  "storage_backend": "sqlite",
  "db_size_bytes": 52428800,
  "errors_since_last": 0
}

Response:

{
  "status": "ok",
  "update_available": true,
  "update_version": "1.3.0",
  "update_url": "https://storage.googleapis.com/...",
  "update_sha256": "abc123..."
}

Offline Resilience

The engine operates indefinitely without management plane connectivity:

All fiscalization operations work without the management plane
License validation is cached locally with configurable grace period (default: 30 days)
Heartbeat failures are logged but do not affect engine operation
When connectivity restores, the engine resumes heartbeats and the management plane reconciles state

Fleet Management

The management plane provides fleet-wide visibility:

Agent List: All registered agents with version, deployment mode, last heartbeat, health status
Version Distribution: Breakdown of engine versions across the fleet
Health Alerts: Agents missing heartbeats beyond configurable threshold (default: 5 minutes)
Update Orchestration: Mark target version, agents pick up updates via heartbeat response
License Enforcement: Revoke or suspend agents via management plane

Partner-Scoped Fleet Views

The management plane supports partner-level grouping:

Partner Dashboard: All agents belonging to a single ISV partner
Version Pinning: Partners can pin their fleet to a specific engine version (agents ignore newer versions until partner approves the update)
Merchant Count Tracking: Heartbeats report active merchant count for license enforcement (Embedded-Local billing is per-merchant, not per-agent)

Change Log

Date	Version	Description	Author
2025-10-27	1.0	Initial architecture document creation	Winston (Architect)
2026-03-08	2.0	Pivot to local-first engine architecture with cloud management plane. Added Deployment Topology, Management Plane Architecture sections. Updated Technical Summary, Platform and Infrastructure for dual deployment model (hosted + on-premise).	Winston (Architect)
2026-03-08	2.1	ISV-first GTM reframing. Renamed Hosted → Embedded-Cloud, On-Premise → Embedded-Local. Added `partner_id` and `merchant_count` to agent registration. Added Partner-Scoped Fleet Views section.	Winston (Architect)

Technical Summary​

Deployment Topology​

Data Plane (Fiscalization Engine)​

Control Plane (Management Plane)​

Embedded-Cloud Mode (formerly "Hosted")​

Embedded-Local Mode (formerly "On-Premise")​

Platform and Infrastructure Choice​

Management Plane Architecture​

Registration Protocol​

Heartbeat Protocol​

Offline Resilience​

Fleet Management​

Partner-Scoped Fleet Views​

Change Log​