FiscalDB — The Engine

Architecture

Requests enter over PostgreSQL or MySQL wire protocols, or over REST. The Query Engine validates and routes; the WAL Manager appends every event; Segment Storage encrypts and compresses; the Hash Chain and RFC 3161 TSA client seal each validated document; connectors negotiate with tax authorities.

Clients

ERP · drivers · curl

PostgreSQL wire

:5432

MySQL wire

:3306

REST

:8080

Query Engine

FiscalSQL · validation · routing

WAL Manager

append-only saga · LSN

Segment Storage

AES-256-GCM · zstd/lz4 · CRC-32

Hash Chain + RFC 3161 TSA

prev→final · TimeStampToken

AEAT

Facturae / VeriFactu

SAT

CFDI 4.0 / PAC

Peppol

UBL 2.1 / BIS 3.0

Ingest saga

A document moves through a strict saga: PayloadStored → Validated / ValidationFailed → TsaTimestampReceived → AddFiscalStamp. Each step is its own append-only WAL entry.

WAL — ingest sagaappend-only

LSN 1PayloadStored
segment=0007.fseg offset=0x1a4f crc32=0x9f3c1d22 zstd=on
LSN 2Validated
schema=CFDI-4.0 mode=strict issuer=XAXX010101000
LSN 3TsaTimestampReceived
tsa=tss.fnmt.es serial=0x4b8e21 genTime=2026-01-14T09:21:07Z
LSN 4AddFiscalStamp
authority=SAT uuid=3F2504E0-4F89-41D3-9A0C-0305E82C3301

WAL format

Append-only segments (.fseg) with a magic header, CRC-32 per record, a sparse index, a metadata index, and the hash chain ledger.

hexdump — segment headerfiscaldb

offset    bytes
00000000  46 53 45 47  "FSEG" magic
00000004  01 00        version=1
00000006  00 07        segment=0007
00000008  9f 3c 1d 22  crc32(record[0])
0000000c  ...          sparse_index_offset

Recovery

Recovery is deterministic: segments are replayed in LSN order and the hash chain is verified on boot. A mismatch halts startup rather than silently serving tampered data.

fiscaldb verify-chainfiscaldb

$ fiscaldb verify-chain --tenant acme
replaying 41,208 records …
prev_hash → final_hash … OK
TSA tokens verified: 41,208 / 41,208
chain integrity: VERIFIED

Per-tenant isolation

Isolation is enforced at the WAL level, the segment level, and the key level. Each tenant has its own hash chain and its own encryption key derivation — there is no shared mutable surface between tenants.

Compression

zstd by default, lz4 optional, applied block-level. Fiscal XML is highly repetitive, which is why on-disk footprint drops 60–80% versus raw XML stored as a Postgres BLOB.

Encryption at rest

AES-256-GCM protects both the WAL and segments. The 32-byte key is loaded from FISCALDB_STORAGE_KEY. Authenticated encryption means tampering with ciphertext is detected on read.

Indexes

RoaringBitmap indexes cover the fiscal metadata that auditors actually query: status, tenant, issuer tax id, receiver tax id, and issue date.

psql — indexed lookupfiscaldb

fiscal=> SELECT external_id, status FROM invoices
         WHERE issuer_tax_id = 'XAXX010101000'
         AND issue_date >= '2026-01-01';
-- RoaringBitmap AND across 4 columns, <1ms

Append-only DML semantics

UPDATE becomes "append a Correction Event". DELETE becomes "append a Cancellation Tombstone". Destructive mutation has no code path.

psql — mutation rejectedfiscaldb

fiscal=> UPDATE invoices SET total = 0 WHERE id = 42;
ERROR (45000): FiscalDB is Append-Only. Use a Correction Event.

Vector / fraud module

An embeddings-based anomaly score flags suspicious documents, with fuzzy duplicate detection and semantic search across the vault. This is the Fraud & Anomaly feature — vector embeddings used for a concrete purpose, not a buzzword.

fiscaldb-cli — anomaly scanfiscaldb

$ fiscaldb-cli "SCAN ANOMALIES tenant acme since 24h"
external_id FAC-2026-0991  score 0.94  near-dup of FAC-2026-0817
external_id FAC-2026-1043  score 0.88  amount outlier (z=4.1)
2 anomalies · 18,402 documents scanned

The FiscalDB Engine