TECHNICAL ARCHITECTURE · V1.0 · JUNE 2026

A ledger with AI around it — never the other way

Gigabite is a ledger-first transaction platform with AI-native automation at every boundary. AI creates candidate facts; deterministic validators and human review promote them into append-only truth.

SECTION 01NON-NEGOTIABLES

Five principles the architecture refuses to bend

P1

Approved truth lives in the operational ledger

The ledger is append-only, versioned, evidence-backed, and auditable.

P2

AI creates candidate facts, not final truth

Model outputs are staged, validated, reconciled, and reviewed before they touch commercial records.

P3

Every material field traces to evidence

Product attributes, pricing terms, certification claims, payment terms, and shipment facts link back to source documents, pages, spans, tables, or image regions.

P4

The lakehouse is analytical, not the live ledger

Iceberg receives ledger events as a derived mirror. It is never responsible for live commercial truth.

P5

Vector retrieval is rebuildable, never authoritative

Semantic indexes are derived from documents, candidate facts, and approved records — and can be dropped and rebuilt at any time.

SECTION 02THE WRITE PATH

How a messy PDF becomes a commercial fact

One direction, six stages. Nothing skips validation, and only the ledger commit service writes approved events.

STAGE 1

Source artifacts

Buyer & supplier uploads, email intake, ERP APIs → immutable object storage.

STAGE 2

AI extraction

Classifier → field extractor → normalizer. Every run logged with model, prompt, cost.

STAGE 3

Candidate facts

Structured facts with confidence scores, each linked to evidence spans.

STAGE 4

Validation

Schema + business validators, reconciliation, risk & confidence scoring.

STAGE 5

Human review

Only where required. Queues by domain: specs, matches, certs, credit, disputes.

STAGE 6

Ledger commit

Append-only events → projections, outbox, lakehouse mirror.

The full map

SYSTEM ARCHITECTURE · FLOW
flowchart TB
  subgraph SRC[Source channels]
    U["Buyer & supplier uploads
CSV · PDF · XLSX · images"] E["Email intake"] A["ERP & portal APIs"] end subgraph ART[Artifact plane] S3[("S3 immutable objects")] REG[("Document registry")] end subgraph AI[AI processing] C["Classifier"] --> X["Field extractor"] X --> N["Normalizer"] end subgraph STG[Staging & controls] CF[("Candidate facts
+ evidence spans")] V["Validators"] RQ["Review queues"] end subgraph LED[Operational ledger] EV[("Append-only events
hash-chained")] PR[("Current-state projections")] end subgraph ANA[Analytics & intelligence] OB[("Event outbox")] --> ICE[("Iceberg lakehouse")] --> BI["BI · eval datasets"] end U --> S3 E --> S3 A --> REG S3 --> REG REG --> C N --> CF CF --> V V -->|controls pass| EV V -->|review required| RQ RQ -->|approved| EV EV --> PR EV --> OB
SOURCE: FINAL ARCHITECTURE · §5

THE COMMERCIAL COUNTERPART · THE PRICING SPINE

The write path governs how any fact becomes truth. The price is the fact that matters most commercially — and it commits the same way, three times: a held live quotation, a locked order finalization, and a trued-up delivery settlement. One hardening figure, evidence-linked at every step, never re-guessed.

See the full pricing spine on the Business plan →
SECTION 03STORAGE PLANES

Four planes, one source of truth

OPERATIONAL

PostgreSQL

Ledger events, projections, candidate facts, review queues, credit sub-ledgers, workflow state. Transactional writes, hash chains, row-level security.

SOURCE OF TRUTH
ARTIFACT

S3 object storage

Original documents, images, parsed pages, model inputs and outputs, evidence files. Immutable.

SOURCE OF TRUTH · RAW
ANALYTICAL

Apache Iceberg

Bronze → silver → gold: event mirror, entity snapshots, supplier intelligence, training and evaluation datasets.

DERIVED
RETRIEVAL

pgvector

Semantic search over products, documents, specs, quotes, review history. OpenSearch only if volume outgrows Postgres.

REBUILDABLE

Ownership is strict: application services write only through the ledger command API; AI services write only candidate facts, evidence, and model runs; analytical jobs never write back to the operational ledger.

One transaction, two worlds

LEDGER → LAKEHOUSE · FLOW
flowchart TB
  APP["App & agent services"] --> CMD["Ledger command API"] --> TXN[("Postgres transaction")]
  TXN --> EVT[("ledger_event")]
  TXN --> PRJ[("projections")]
  TXN --> OBX[("event_outbox")]
  OBX --> PUB["Outbox publisher"] --> BRZ[("Bronze
raw events & documents")] BRZ --> SLV[("Silver
entities & snapshots")] --> GLD[("Gold
scores · features · metrics")] GLD --> DASH["Dashboards"] GLD --> EVAL["AI evaluation datasets"]
SOURCE: FINAL ARCHITECTURE · §6.3
SECTION 04DOMAIN LEDGERS

Six ledgers, one event store

Every domain has an event history and a current-state projection (quote_current, credit_account_current, …). Projections update idempotently, in the same transaction as the commit where consistency requires it.

LEDGER 1

Product & specification

Customer SKUs, spec versions, required attributes, the SKU equivalency graph.

LEDGER 2

Supplier & factory

Factory capability, certification scope and expiry, audit history.

LEDGER 3

Quote & landed cost

Versioned quotes with itemized cost components, assumptions, validity windows.

LEDGER 4

Order & shipment

Customer and supplier POs, container milestones: booked, departed, cleared, delivered.

LEDGER 5

Credit & payment

Net terms, credit accounts and draws, receivables, double-entry postings, exposure.

LEDGER 6

Quality, dispute & compliance

Quality issues, dispute records, compliance exceptions, supplier risk history.

SECTION 05SERVICE TOPOLOGY

Fourteen services, four tiers, one write path

Every service has exactly one reason to exist and one thing it may write. The ledger command service is the only writer of approved events — everything else stages, reviews, projects, or publishes.

EXPERIENCE

Facing people

identity & tenant
document service
review service
notification service

INTELLIGENCE

Facing models

AI processing
candidate facts
retrieval (pgvector)
review triage

LEDGER CORE

Facing truth

ledger command ★
projection service
quote · order · finance
compliance service

DATA

Facing history

lakehouse publisher
outbox processor
eval dataset builder

SECTION 06TAMPER EVIDENCE

The hash chain: audit-grade without a blockchain

Every event hashes its canonical payload together with the previous event hash for its aggregate. Tampering anywhere breaks the chain everywhere after it.

LEDGER_EVENT · HASHING

event_hash = sha256(canonical_json( tenant_id, aggregate_type, aggregate_id, aggregate_sequence, event_type, event_version, event_time, payload, previous_event_hash # chain per aggregate ))

The evidence chain

CANONICAL DATA MODEL · ER
erDiagram
  SOURCE_DOCUMENT ||--o{ DOCUMENT_PAGE : contains
  SOURCE_DOCUMENT ||--o{ EVIDENCE_SPAN : supports
  DOCUMENT_PAGE ||--o{ EVIDENCE_SPAN : locates
  EVIDENCE_SPAN ||--o{ CANDIDATE_FACT : proves
  CANDIDATE_FACT ||--o{ REVIEW_TASK : creates
  REVIEW_TASK ||--o{ REVIEW_DECISION : resolves
  CANDIDATE_FACT ||--o{ LEDGER_EVENT : promotes_to
  LEDGER_EVENT ||--o{ EVENT_OUTBOX : publishes
  LEDGER_EVENT ||--o{ PROJECTION : builds
    
SOURCE: FINAL ARCHITECTURE · §8 — EVERY MATERIAL FIELD WALKS THIS CHAIN
SECTION 07HUMAN-IN-THE-LOOP

Auto-approval is a policy, not a vibe

Every candidate fact runs the same gauntlet. The only variable is whether a human sits between scoring and commit — and that is decided by policy, per fact type.

The routing decision

AI PROCESSING · FLOW
flowchart TB
  D["Document ingestion"] --> CL["Classifier"] --> EX["Field extractor"] --> NM["Normalizer"] --> CF["Candidate fact writer"]
  CF --> VA["Validators"] --> RC["Risk & confidence scorer"] --> RT{"Review
required?"} RT -->|no| CR["Commit request"] RT -->|yes| HR["Human review task"] HR -->|approved / edited| CR CR --> LC["Ledger commit service"] EX -.-> MR[("Model run log")] NM -.-> MR HR -.-> FB[("Reviewed examples")] FB -.-> MR
SOURCE: FINAL ARCHITECTURE · §10 — DOTTED EDGES FEED THE EVALUATION LOOP

Auto-approve when controls pass LOW RISK

  • Product extraction: supported family, required attributes present, high confidence, no conflicting priors
  • Supplier SKUs from structured catalogs of known suppliers
  • Matches with attribute agreement, evidence, approved factory, low substitution risk
  • Quote math from approved inputs via the deterministic calculator
  • PO ↔ quote reconciliation within configured tolerances
  • Payments matching reference, amount, invoice, and customer exactly

Always a human MATERIAL

  • New supplier or factory approval
  • Food-contact, medical, compostability, or safety claims without prior approved evidence
  • High-value first orders and material substitutions
  • Credit limit increases; write-offs, refunds, credit memos, dispute settlements
  • Tariff classification changes and certification exceptions
  • Anything that would create unbalanced financial entries
SECTION 08TECHNOLOGY BASELINE

Boring where it should be boring

LAYERDIRECTIONNOTE
Web appNext.js · React · TypeScriptOperator workbench + buyer portal
BackendFastAPI · Pydantic · SQLAlchemyTyped contracts end to end
WorkflowsTemporalDurable multi-step commercial workflows
Operational DBPostgreSQL + pgvectorLedger, projections, retrieval in one plane at MVP
ObjectsAWS S3Immutable artifact store
LakehouseIceberg · Glue · AthenaParquet tables; dbt + Spark transforms
EventsPostgres outbox → RedpandaStream only when throughput demands it
RuntimeECS Fargate · TerraformContainerized, IaC from day one
ObservabilityOpenTelemetry · MetabaseTraces + model run logs; MVP dashboards
SECTION 09MVP · DEFINITION OF DONE

The MVP is done when a stranger can audit it

Definition of done §20.3

  • A customer can upload an item list or invoice
  • Supported SKUs extract and normalize; every value links to source evidence
  • Matches propose with attribute-level explanations; reviewers approve, edit, or reject
  • Approved records emit append-only ledger events
  • A quote version generates with cost components and assumptions
  • The lakehouse receives the event mirror; dashboards report extraction quality, review backlog, match outcomes, quote activity

Event taxonomy v1 SAMPLE

SOURCE_DOCUMENT_RECEIVED DOCUMENT_CLASSIFIED CUSTOMER_SKU_EXTRACTED PRODUCT_SPEC_APPROVED FACTORY_CERTIFICATION_APPROVED PRODUCT_MATCH_PROPOSED PRODUCT_MATCH_APPROVED QUOTE_VERSION_CREATED QUOTE_SENT_TO_BUYER QUOTE_ACCEPTED REVIEW_TASK_RESOLVED LEDGER_EVENT_PUBLISHED