CATHAGO · altair engine v10 + checks-v1.0 · task CU-86c7x8puw

Invoice verification, the full reference.

The complete picture of the native invoice-verification feature — the matching engine and checks, the document lifecycle from inbox to approved, the reviewer workflow in kepler, and the domain model, config and known gaps underneath. Four tabs; every claim traced to the backend + frontend knowledge bases.

altair's in-process engine (ENGINE_VERSION "v10.0") matches every invoice line against the order, the delivery note and the agreed price list, then a checks engine (checks-v1.0) runs financial, tax, master-data, duplicate and temporal rules on top. Everything is gated per tenant and frozen into an append-only audit report.

3matching tracks

11+1verification checks

4ways to trigger a run

0n8n calls in the hot path

1.1

The three matching tracks

Each invoice line is matched per track by a normalized article key. All three converge on InvoiceMatchingService.match(companyAccountId, invoiceId, Set<MatchTrack>).

Order · FIND_ORDER

Invoice line ↔ order line

Candidates = referenced-order lines with the same normalized article key. Best = min |orderedQty − invoiceQty|. Quantity outside tolerance ⇒ MISMATCHED. A unit-price guard rejects a 0.00-priced order line vs a priced invoice line.

Anti-double-bill: order__line_consumption ledger — remaining = ordered − consumed by other invoices; no capacity ⇒ OVER_CONSUMPTION.

Delivery · FIND_DELIVERY

Invoice line ↔ delivery note

First article-key match across referenced deliveries; cross-supplier allowed. A quantity mismatch keeps the matched line so 3-way reconciliation can still read the delivered qty.

Scope: honours the workflow's "e-delivery note only" toggle — regular extracted notes skipped under that scope with a truthful verdict.

Price · PRICE

Invoice price ↔ price list

Resolution order: a manual PRICELIST reference → the line's own priceListId → master-catalog lookup. Compares invoice unit price vs the price entry's pricePerUnit within tolerance.

Usability gate: price list must be ACTIVE and assigned to this tenant+project. Unresolvable ⇒ WAITING (never a false FAIL).

3-way reconciliation. When order matched and a delivery line is known, the engine checks billed ≤ delivered ≤ ordered — BILLED_MORE_THAN_DELIVERED is critical (paying for goods not received), DELIVERED_MORE_THAN_ORDERED a warning. Comparison is unit-of-measure aware: "200 KG" reconciles against "10 SAC" via the extracted alternative unit, then the master product's package factor; genuinely incomparable units emit an honest "differing units" verdict rather than a fabricated mismatch.

1.2

The run, stage by stage

STAGE 1

Trigger

Kafka event on invoice create/update, or a reviewer hits Run / Re-run.

InvoiceVerificationListener

STAGE 2

Gate

Which of the 3 tracks may run for this tenant, project, supplier & status.

AutomationGateService

STAGE 3

Match

Per line: order → delivery → price; reconcile; write per-track verdicts + ledger + references.

InvoiceMatchingServiceImpl

STAGE 4

Checks

Reload the doc, run all 11 checks + the 3-way quantity check sequentially.

VerificationCheck beans

STAGE 5

Report

Compute counters + outcome, append a report, log a Timeline activity.

VerificationReportEntity

STAGE 6

Approve

Reviewer checklist gates Approve — or touchless auto-approve if configured.

InvoiceAutoApproveService

Four ways a run starts

Auto

Invoice created / updated

Kafka listener on InvoiceBusinessDocumentTopic (group INVOICE_VERIFICATION_GROUP). Gate-resolved tracks only. On CREATED also auto-assigns a reviewer.

Auto

Matched documents changed

Adding/removing a reference re-runs the match synchronously via /rematch so the badge + verdicts reflect the completed match, not the pre-match snapshot.

Manual

Run verification

POST …/verification/run requests MatchTrack.all(). A track runs when allowed OR unconfigured; a configured-but-disabled track is dropped.

Manual

Re-run a single track

POST …/rematch?track=ORDER|DELIVERY|PRICE — "Find order / delivery / price-list match" from the detail toolbar.

1.3

The gate — which tracks may run

AutomationGateService.resolveAllowedTracks reads the tenant's active INVOICE automations and filters each by the invoice's current status (empty status list = matches all). A track is allowed iff ≥1 eligible workflow.

Per-track scoping

comparePricePerUnit suppression — PRICE is suppressed when every eligible Order (or Price) workflow has "compare price per unit = No"; the pricelist unit price then reads n/a instead of a false green tick.
e-delivery scope — resolveEDeliveryOnly reads the delivery workflows' compareEDeliveryNote; under that scope only mobile-channel e-delivery notes match.
Ignore service items — SERVICE-type lines are excluded from flagged tracks (serviceLinesSkipped), with an explicit per-line verdict.

Scope precedence (config)

A newer invoice__matching_config (per companyAccount, scoped by tenant + project + supplier) supersedes the old INVOICE_VERIFICATION_* automations.
In-scope ⇒ all tracks enabled; out-of-scope ⇒ legacy automation fallback.
Empty tenant-project assignments = applies to all tenants. Missing tenant/status ⇒ fallback allow-all.

Silent no-op. A "Re-run all" from an unconfigured tenant goes through the gate and can return an empty track set — nothing runs, matchSummary.skipped=true with a reason, and kepler shows a snackbar instead of a false all-green.

1.4

The checks engine

Each check is a Spring bean auto-registered via List<VerificationCheck>. Contract: missing input ⇒ skipped, never an empty flux or a throw. A critical fail blocks readiness; a warning is approve-with-reason.

checkId	Class	Category	Severity
`STR_MANDATORY_FIELDS`	MandatoryFieldsCheck	Structural	warning
`FIN_NET_TAX_GROSS`	NetTaxGrossCheck	Financial	warning
`FIN_LINE_SUM`	LineSumCheck	Financial	warning
`TAX_RATE_ALLOWED`	TaxRateAllowedCheck	Tax	warning
`TAX_VATID_FORMAT`	VatIdFormatCheck	Tax	warning
`MD_IBAN_CHECKSUM`	IbanChecksumCheck	Master data	critical
`MD_BIC_FORMAT`	BicFormatCheck	Master data	warning
`MD_BANK_CHANGE`	SupplierBankChangeCheck	Master data	critical
`DUP_INVOICE`	DuplicateInvoiceCheck	Duplicate	critical
`TMP_INVOICE_DATE`	InvoiceDateCheck	Temporal	warning
`TMP_DUE_DATE`	DueDateCheck	Temporal	info
`MATCH_3WAY_QTY`	synthesized in the report service	Match	critical

Outcome rollup. criticalFailures > 0 or over-consumption ⇒ report FAILED; warnings or a plain mismatch / no-reference ⇒ PASSED_WITH_WARNINGS; a gate-skipped match also maps to PASSED_WITH_WARNINGS; clean ⇒ PASSED. Each run is written to an append-only VerificationReportEntity and logged as a VERIFICATION_RUN Timeline activity — never updated in place.

1.5

Then n8n, now native

Verification used to be three n8n webhook workflows the frontend called and waited on. The v10 engine pulled all of that in-process — same output shape (documentPipelines), but reactive, gated, audited, fast.

Before · n8n

Webhook workflows

Invoice-Price · Invoice-Order · Order-price verification

·Kepler POSTs a webhook and waits — up to an 8-minute HTTP timeout.
·Each track its own workflow, reading Mongo, Typesense catalog & a Postgres query.
·Code nodes computed the match; HTTP calls wrote back the verdicts.
·A "final invoice evaluation" sub-workflow stitched the tracks.
·No audit trail, no per-tenant gating beyond "workflow active", no auto-approve.

Now · altair v10

In-process engine

InvoiceMatchingService + checks, reactive WebFlux, no external hop

→Kafka auto-trigger + synchronous REST — runs in-request.
→All three tracks in one engine reading Mongo directly; consumption ledger stops double-billing.
→Per-tenant gate (tenant + project + supplier + status).
→Every run frozen into an append-only report + Timeline activity.
→11-check engine, unit-aware reconciliation, opt-in touchless auto-approve.

Legacy n8n workflow		Native equivalent
Invoice - Price verification	→	`resolvePricelistMatch` — assigned, active price lists only
Invoice - Order automation	→	`resolveOrderMatch` + `order__line_consumption` ledger
Delivery matching	→	`resolveDeliveryMatch` — cross-supplier, unit-aware
pipeline write-back HTTP nodes	→	`persistVerdicts` — same `documentPipelines` shape
"final invoice evaluation" sub-workflow	→	Checks engine + `VerificationReportEntity`

The journey a supplier invoice takes — from the moment its PDF arrives, through AI extraction and human triage, into a verified BusinessDocument, to a reviewer's approval. Verification is done at approved; what happens afterwards is a separate downstream integration, noted at the end.

Sender / user earth + S3 storage n8n + Vertex AI altair domain + engine Kafka event bus kepler reviewer UI

The whole path, in one breath

A PDF arrives → it becomes an IncomingFile (staging record) → AI extracts its fields → a human triages anything unclear → n8n turns the clean file into an invoice BusinessDocument → that save fires a Kafka event → verification runs → a reviewer approves. Five phases, four systems, one document.

Two n8n servers, don't mix them up. Extraction runs on the main n8n.cathago.de; email arrival lives on the separate integration-prod.cathago.de.

Arrival

An invoice PDF is emailed in

n8n · integration-prod

The process email documents workflow fetches the Gmail message + PDF attachments; an LLM reads the header addresses to identify the sender.

wf HzGMOsUjy2WDjzqk

Resolve customer, supplier & automation

Postgres + Mongo

Emails matched to a company account, a supplier, and the tenant's INCOMING_FILE automation. Internal staff addresses excluded; unmatched mail falls back to Unmapped cat_u_aca_1.

Store the PDF, create the IncomingFile

earth + altair

PDF bytes stored in earth (S3), then an IncomingFile created in altair — channel EMAIL, source EXTERNAL. altair forces status PROCESSING on create.

POST /gateways/integration/incomingFiles

Or: a user uploads in the app

kepler

On /company/incoming-files the upload dialog stores the file and creates an IncomingFile (channel WEB, source INTERNAL).

Hand off to the processor

n8n

Arrival fires the pdf-splitter webhook, which continues into the Incoming Files Processor.

Extraction & triage

Build the extraction request

n8n + Vertex

Processor (rkW7jqv75O2JwHR2, ~102 nodes) GETs the IncomingFile, pulls the PDF, extracts raw text, assembles a strict JSON schema (header + li* line fields + tenant custom fields) with a German B2B prompt (temp 0, "null, don't guess").

cache Vertex cachedContent 23h TTL

Gemini extracts header + line items

Vertex AI

gemini-3.5-flash returns documentType, supplier/payment/project details, and every line with qty/prices/tax + any referenced order/delivery numbers. Reading order preserved (feeds sourceIndex).

Match accounts & check duplicates

Postgres + Mongo

Supplier/project/buyer fuzzy-matched (Postgres); a Mongo scan on incoming_file catches duplicates. A duplicate is set REJECTED, not silently dropped.

Persist & set status

altair

Mapped fields PATCHed back. Status becomes PROCESSED, WARNING, or ERROR (e.g. no document number). Errors/warnings pinned to the exact field + line.

Human triage in the inbox

kepler

A user opens /company/incoming-files/{id}/view: correct fields, edit lines inline, use the Fix flow (jumps to the flagged field). Then Re-Run / Apply Changes.

Re-processing skips the AI. "Apply Changes" / "Re-Run" reuse the stored fields and only re-run account-matching + dup-check + BD creation — Vertex is not called again. Extraction only happens on the first pass.

Becomes a BusinessDocument

n8n creates the invoice BD

n8n → altair

Only when PROCESSED and not in-approval, a sub-workflow POSTs into altair. altair builds the BusinessDocumentEntity (INVOICE / CREDIT_NOTE, status OPEN, channel API / source EXTERNAL).

POST /api/gateways/integration/documents

Line items + reference numbers

altair

Lines become LineItemEntity rows (bulkUpdate); extracted order/delivery numbers ride along as documentReferences (raw, not yet resolved).

Save emits a CREATED event

Kafka

On save, altair publishes CREATED to InvoiceBusinessDocumentTopic — the single seam that wakes verification.

REST, not Kafka. The IncomingFileTopic event exists but is unwired inside altair; it's the REST POST above that creates the invoice. The IncomingFile keeps a documentReferenceId → BD; deleting the file cascades to the BD + S3 doc.

Verification

Listener catches the event

altair

InvoiceVerificationListener consumes the topic (INVOICE/CREDIT_NOTE, CREATED/UPDATED), auto-assigns on CREATED, then asks the gate which tracks may run.

Match → checks → report

altair v10

3 tracks + 11 checks + 3-way qty; frozen into an append-only report. (Full internals on the Engine & checks tab.)

Review & approve

Reviewer works the checklist

kepler

Correct fields, tick per-line/per-field values, resolve warnings, @-mention teammates. Approve hard-gated on the mandatory rows. (Full UI on the Reviewer workflow tab.)

Approve — or touchless auto-approve

altair

Approving stamps approvedBy/At → APPROVED. If opted in and all-green with no criticals, InvoiceAutoApproveService approves with no human touch.

After approval — downstream, not verification

Verification's scope ends at APPROVED. What an approved invoice is used for next is separate work, wired per customer.

Example: e-invoice / DATEV export. For one customer today (DATABAU Nahe-Hunsrück), a standalone n8n workflow on integration-prod listens for APPROVED invoices, builds a ZUGFeRD / Factur-X file and drops it in a Google Drive folder the tax advisor imports into DATEV (no direct DATEV API). Other customers have their own export workflows. These are separate integrations, out of scope for this feature.

The IncomingFile status machine

PROCESSING→ PROCESSED· WARNING· ERROR· DUPLICATE· REJECTED

altair pins only the initial state (PROCESSING, forced on create); every later transition is whatever the pipeline or a user PATCHes in — there is no server-side transition guard.

The engine does the matching; a human decides "can I pay this?". The kepler UI spans two screens — the invoice list and the invoice detail — plus a settings dialog. Feature root: cathago/home-layout/company/invoice/.

3.1

Two screens

Invoice list

/company/invoices

Stats bar — Total / Open / Approved / Rejected / Unassigned tiles, each a one-click quick-filter (5 tiny search calls, pageSize=1).
Readiness ratio badge (e.g. "12/18") per row, with a check-by-check quick-view popover + a Mandatory n/m sub-count.
Matched-documents chip is verdict-driven: green matched · red mismatch · amber pending · grey none.
Skonto column (Frist + Betrag, days-left urgency ramp); Assignee avatars from the denormalized snapshot; an "Auto" pill on touchless-approved invoices.
Filters: Assignee (incl. Unassigned), Due-date, Skonto-deadline, document type, invoice-date — persisted per user.

Invoice detail

/company/invoices/:id/view

Left = unified extraction surface: General (Project/Supplier/Buyer + assignee) → Line Items (recon matrix + totals footer) → Delivery → Matched Documents → Approval Readiness → stamp banner.
Right = Files (PDF preview + stamp overlay, "This invoice" + "Linked documents" zones) and Timeline (runs + comment activities).
Bottom toolbar: prev/next, Re-run menu (all / per-track), Skonto chip, Lifecycle affordance, Approve (hard-gated) and Reject (with reason).

3.2

Approval Readiness checklist

getApprovalChecklist() builds 7 rows and gates the Approve button. Bucketing (readinessBucketOf): rejected → blocked; ready|skipped → passed; pending → blocked if the row is mandatory, else warning.

Row	Green when…	Kind
Project	project linked (auto-seeded)	human check
Supplier	supplier account linked	human check
Buyer	buyer linked	human check
Order reference	an ORDER reference exists/matched, or reviewer Verified	engine check
Delivery reference	a DELIVERY reference exists/matched, or reviewer Verified	engine check
Pricelist match	≥1 line's PRICE pipeline is COMPLETED	engine check
Line items	every line approved/skipped	rollup

The mandatory set is configurable per tenant (mandatoryReadinessSteps, default {project, supplier, order, delivery, lineItems}). A bottom-bar Pflicht n/m chip shows positive progress; the list badge and detail eyebrow use the same math so they always agree. Approve gate (canApprove()): every required row ready-or-skipped and nothing rejected.

3.3

Verification report card (the cockpit)

cat-verification-report-card — a single scrollable page; the three check buckets stack in one bounded body with the tiles as a sticky scrollspy nav. Comments and History are lens tabs.

Tiles & buckets

Blockers (red) — reserved for mandatory section rows.
Warnings (amber) — all automated engine checks land here; FAIL and WARN are both advisory since 29bff6b5a.
Passed checks, plus Comments and History lenses.
Match-score SVG ring (grey / red<50 / amber<100 / green=100).
INV vs ORD vs DLV totals strip (net/tax/gross; mismatch beyond €0.01 flagged).
Run-to-run delta ("+2 passed, −1 blockers").

Fix & evidence

Rows expand to detail + evidence (label / observed / expected).
Fix jumps to the owning card: FINANCIAL/STRUCTURAL/TAX/TEMPORAL → line items, MASTER_DATA → supplier, MATCH → references; line-level checks emit a line-focus request.
Header eyebrow: "X / Y checks passed · N blockers · M warnings" (engine + sections combined).
Header "i" quick-view splits Mandatory vs Optional.

3.4

Line-item reconciliation (per-line, per-field)

Each line renders as a card: compact when approved, expandable to a recon matrix with tracks INV / ORD / DLV / PRL. Values surface the counterpart ("Qty 5.00 m — O ✓ 5.00 m").

The per-field tick is tri-state (WYSIWYG: a human sign-off must look different from a machine match)

Green — a reviewer manually approved the field Orange — the engine matched it (system) Grey — open / unmatched

Per-line status badge: Approved (green) only for a manual approval; Matched (orange) for a system-only auto-match; else Open / Rejected. Required line fields = quantity, unitPrice, netPrice, taxRate, grossPrice; footer = net, tax, gross. Pricelist has no stored line net, so that cell reads n/a rather than green-ticking a derived net — net is validated against the ORDER line total. Reviewers can also manually Connect order/delivery line per row when article keys differ.

3.5

Matched Documents

Find matching (AI)

POST /discover-references resolves the order/delivery numbers the invoice carries to real docs and links them, then matches.
Also auto-attaches an unambiguous content match (1 supplier candidate covering all article lines, total within 5%).
If nothing links, opens the manual dialog on Best matches — so number-less invoices still get matched.

Match manually + Best matches

Search dialog with project pre-filter + Suggested filters chips (Supplier default-on; ≈net-amount ±10%; "Since date").
Best matches band = ranked match-suggestions (host-derived counterpart types, supplier-scoped, number/article only — amount/date only refine rank).
Deleting a linked row unlinks it (keeps the number → re-findable) rather than removing the reference.

3.6

Comments · assignee · stamp · settings

Comments & assignee

Google-Docs-style thread on every field / line cell / footer total: add, @-mention autocomplete, assign thread, per-comment resolve/reopen, copy-link — all server-stamped.
Icon states by colour: hover-only empty, warn-orange when open comments exist, distinct resolved state. All aggregate into the card's Comments lens + Timeline.
Assignee = denormalized snapshot (avatar, no per-row fan-out); reassign from list kebab or detail chip; Unassigned filter.

Stamp & settings dialog

On APPROVED, cat-files-panel overlays a rubber-stamp on the PDF (UI overlay, bytes unchanged): reviewer name, timestamp, tenant colour/shape/size + an editable reviewer comment. Rejected shows a red stamp + reason.
Settings dialog (single scrollable page + scrollspy): Tolerances · Auto-assignment · Auto-approval · Mandatory checklist · Stamp. Reviewer field = member dropdown; auto-approval carries a "no human review" warning.

The domain model, tenant configuration, the full API surface, the Mongo collections, and the known gaps — the "under the hood" layer for anyone extending the feature.

4.1

Domain model — key entities

VerificationReportEntity

document__verification_report · C30

Append-only, one doc per run, never updated — the audit trail.

businessDocumentIdengineVersiontriggeredBymatchSummarycheckResults[]overallOutcomecriticalFailureswarnings

InvoiceMatchResult

embedded · matchSummary

Document-level aggregate of one run.

totalLinesorderMatcheddeliveryMatchedpricelistMatchedaggregateScoreallGreenreviewerApprovableskipped/skipReasontotalsComparison

MatchVerdict

per-line

Status MATCHED / MISMATCHED / OVER_CONSUMPTION / NO_REFERENCE. Persisted as documentPipelines (n8n-compatible shape).

matchedDocIdmatchedLineIdscorereasonconsumedQuantity

OrderLineConsumption

order__line_consumption

Anti-double-billing ledger. Row present = claim current; engine delete+insert per run (idempotent).

orderIdorderLineIdinvoiceIdinvoiceLineIdquantityunique{invoiceId,invoiceLineId}

QuantityLineageFinding

3-way

Per-line reconciliation. Issue OK / BILLED_MORE_THAN_DELIVERED (critical) / DELIVERED_MORE_THAN_ORDERED (warning).

invoiceQuantitydeliveredQuantityorderedQuantityissuemessage

ArticleKeyNormalizer

match key

trim → keep letters/digits → uppercase → strip leading zeros. "ABC-123-X" ≡ "abc 123 x" ≡ "0ABC123X". null/blank ⇒ unmatchable.

ReadinessRowDecision

on BusinessDocument

Reviewer decision APPROVED (@JsonAlias VERIFIED) / SKIPPED / REJECTED, server-stamped, + a comment thread.

decisiondecidedBydecidedAtcomments[]commentsAssigneeId

BusinessDocument readiness maps

common__business_document

Four decision maps + assignee + stamp fields drive the whole checklist.

readinessDecisionslineReadinessDecisionslineFieldReadinessDecisionsfooterFieldReadinessDecisionsassigneeId+assigneeapprovedBy/AtdocumentPipelines

Check enums. Category = STRUCTURAL / FINANCIAL / TAX / MASTER_DATA / DUPLICATE / TEMPORAL / MATCH. Severity = CRITICAL (blocks) / WARNING / INFO. Outcome = PASS / FAIL / WARN / SKIPPED / NOT_APPLICABLE. A CheckResult carries evidence {label, observed, expected, refId} and a nullable lineItemId (null = invoice-level).

4.2

Tenant configuration

tenant__verification_config

@Id = tenantId · per tenant

QuantityTolerance / PriceTolerance {mode, value}; mode EXACT / ABSOLUTE / PERCENT. New-tenant default ABSOLUTE / 1.00 (was EXACT/0 — killed rounding-noise false mismatches).
AutoAssignmentConfig — OFF / FIXED_USER / ROUND_ROBIN_ROLE (+ rotation cursor).
arithmeticToleranceAmount (0.01 €), allowedVatRates ({0,7,19}).
StampConfig — colour RED/BLUE/GREEN/BLACK, shape RECTANGLE/CIRCLE, size SMALL/MEDIUM/LARGE (0.8/1/1.25×).
autoApproveAllGreen (default off) · mandatoryReadinessSteps (Pflicht-Checkliste).

invoice__matching_config

per companyAccount · scope

Scopes matching by tenant + project + supplier (tenantProjectAssignments[], allSuppliers, supplierIds).
Empty assignments = applies to all tenants.
Supersedes the legacy INVOICE_VERIFICATION_* automations; in-scope ⇒ all tracks, else legacy fallback.
Configured in settings, not the old automations page (which was removed).

Touchless auto-approve gate (all true): autoApproveAllGreen on AND matchSummary all-green AND criticalFailures == 0 AND every mandatory readiness row satisfied AND invoice still OPEN. On pass → approved as SYSTEM_AUTO_APPROVAL; the list shows an "Auto" pill. Off by default → opt-in per tenant.

4.3

Full API surface

altair under /api/documents (context path /v3 on staging & prod), every call scoped by ?companyAccountId=. Kepler reaches these via BusinessDocumentService.

Endpoint	Purpose
POST/documents/{id}/verification/run	Manual full verification (all tracks + all checks), persist + return the report.
GET/documents/{id}/verification	Latest persisted report (detail load).
GET/documents/{id}/verification/history	All runs newest-first (audit trail).
POST/documents/{id}/rematch?track=	Synchronous v10 match over linked docs; optional single track.
POST/documents/{id}/discover-references	"Find matching document" — resolve captured numbers to real docs, link, match.
POST/documents/{id}/match-suggestions	"Best matches" — ranked candidates, read-only.
PATCH/documents/{id}	All reviewer payloads: readiness decisions, per-line/field ticks, comments, resolve, assignee. Retries on version conflict.
PATCH/documents/{id}/assignee	Reassign reviewer; stamps the Assignee snapshot.
POST/documents/search	List view; each row embeds `verificationSummary`; Assignee + Skonto filters.
GET/tenant/verification-config	Read tenant settings.
PUT/tenant/verification-config	Patch tenant settings (null field = section untouched).
DEL/documents/{id}	Invoices & credit notes → 403 by design (audit trail).

MongoDB collections touched

Collection	Holds
`common__business_document`	The invoice: pipelines, readiness maps, assignee, approval stamp.
`common__line_item`	Line rows (keyed by `documentReferenceId`); verdict evidence + catalog stamp.
`document__verification_report`	Append-only run reports.
`order__line_consumption`	Anti-double-billing ledger.
`tenant__verification_config`	Per-tenant settings.
`incoming_file`	Upstream staging record (ingestion).

4.4

Cross-service & events

Kafka

Consumed: InvoiceBusinessDocumentTopic by InvoiceVerificationListener (group INVOICE_VERIFICATION_GROUP).
Published: no dedicated event — touchless auto-approve reuses the manual approval's UPDATED (status APPROVED) publish. Re-entrant run is a no-op (OPEN guard).
Every ingestion does ≥1 double run (save re-emits UPDATED) — one appended report per run.

Services

earth — EarthMemberClient for assignee snapshots (~80ms/reassign) + round-robin role members.
titan — not involved; PDF stamp is client-rendered (the in-altair PDFBox stamper is currently unwired).
kepler — renders pipelines, report panel, readiness card, stamp overlay, settings dialog.

4.5

Known gaps & sharp edges

"Find matching" does no discovery of unknown docs

It resolves numbers already on the invoice; it doesn't search the account for a candidate by supplier + article overlap. No printed number ⇒ nothing auto-links (mitigated by the content-match + Best-matches fallback).

Over-consumption detected by string match

updateAggregates classifies over-consumption via message.contains("fully consumed"). Reword the reason and the counter (and FAILED outcome) silently breaks.

Delivery track picks findFirst()

No best-candidate scoring or remaining-quantity ledger like the order track; multiple delivery lines with the same article bind to the first.

Evidence writes aren't transactional

Pipeline write, consumption rewrite, references, connections and catalog stamps are separate reactive steps; a mid-chain failure can leave partial evidence (mitigated only by an idempotent re-run).

List vs detail bucketing can drift

readiness-summary.util.ts (list) and the detail checklist must stay in sync by hand; the list still treats engine criticals as failures while the detail folds them into warnings — possible badge-colour drift.

Two 3000+-line components

invoice-detail and invoice-line-item-table far exceed the house 4/5-line-method rule, with a few stale as any casts. Refactor debt.

Dead code on both sides

altair PdfStampServiceImpl has zero callers since a revert; kepler document-verification-header / verification-line-items are off-surface. Candidates for deletion.

Legacy n8n webhooks still wired

kepler reRunAutomation + WORKFLOW_PATH_* coexist with the native endpoints; removal pending full rollout. The dead useNativeVerificationTrigger toggle was already removed.