The Autonomous Enterprise · AE Suite · Module 03

RevRec AI
Revenue Recognition
— ASC 606 · SHAP · HITL · SAP.

The most regulated module in the AE Suite. Every transaction classified by XGBoost, explained by SHAP, approved by the Finance Controller, and only then posted to SAP. EU AI Act Article 13 and 14 satisfied in a single workflow — not as compliance features, but as the workflow itself.

EU AI Act — High Risk · Annex III ASC 606 · IFRS 15 Salesforce + SAP XGBoost · SHAP HITL-04 · HITL-05 · HITL-09 Financial ART · H2 · PI-3
System Context — C4 Level 1

What is RevRec AI and who does it talk to?

The system context establishes the boundary of RevRec AI and its relationship to every external actor and system. Everything inside the boundary is designed and owned by the AE. Everything outside is a dependency with a documented integration pattern.

Architecture Overview

Every GCP service. Every data flow. Every control.

The architecture overview expands the RevRec AI system boundary from the context diagram above into its internal component design. This is the diagram that answers how it works — not what it does.

Agent State Machine

Every state. Every transition. Every HITL pause node.

The RevRec AI agent's formal finite state machine — the same specification that drives the ADK implementation. HITL states are first-class nodes with defined entry conditions, timeout behaviour, and immutable audit records. The SAP write is physically unreachable without a committed HITL-04 approval record.

Data Flow & Sequence

One transaction. End to end. Every system. Every message.

The sequence below shows a single ClaraVis MRI-7T + service contract classification — from the Salesforce contract_signed event through to the SAP GL write confirmation. Times are representative. Every step is audited before the next begins.

HITL-04 Presentation

What the Finance Controller actually sees.

EU AI Act Article 14 requires that the human reviewer has access to the information needed to make an informed decision. This is the HITL-04 queue interface — the SHAP chart, classification result, comparable transactions, and the approve/override decision with mandatory reason code.

HITL-04 Approval Interface — Finance Controller Queue
RevRec AI — HITL-04 Review Queue · hitl_20260315_rr_004 · SLA: 3h 47m remaining
ASC 606 CLASSIFICATION
MULTI-ELEMENT ARRANGEMENT
2 performance obligations identified
MODEL CONFIDENCE
0.91
sku_complexity_score
+0.38
recognition_type_prior
+0.29
payment_term_days
+0.19
contract_value_eur
-0.12
customer_type_encoded
+0.08
CV2025-0108 · Hôpital Lariboisière Paris · MRI-7T + 3yr service
€2.1M · MULTI-ELEMENT · similarity: 0.91 · approved by: M. Dupont · 2025-11-14
CV2024-0233 · Charité Berlin · MRI-3T + 5yr service + training
€1.8M · MULTI-ELEMENT · similarity: 0.87 · approved by: K. Bauer · 2024-08-02
CV2025-0044 · AMC Amsterdam · CT-Premium + 2yr service
€1.4M · SALE · similarity: 0.74 · single obligation · different outcome noted
✓ Approve — Post to SAP
✗ Override — Enter reason
⏱ SLA expires in 3h 47m · Timeout escalates to CFO · All decisions are immutably recorded
Contract ID
sfdc_contract_CV2026_0042
Counterparty
Universitätsklinikum München
Contract value
€2,840,000
SKUs
MRI-7T Unit × 1
Premium Service 5yr × 1
Clinical Training × 1
Remote Monitoring × 1
Payment terms
Net 360 · annual instalments
Signed date
2026-03-15
Proposed performance obligations
1. MRI hardware delivery (pt of time)
2. 5yr service + training (over time)
HITL checkpoint
HITL-04 · Always required
SHAP record
Written to BigQuery
ae_audit.shap_explanations
before this queue was created
EU AI Act Art. 13 ✓
Explanation provided to human reviewer before any downstream action.
Architecture Decision Records

Three RevRec AI decisions. Every alternative documented.

ADR-010 governs the model architecture choice. ADR-R01 and ADR-R02 are module-specific decisions unique to RevRec AI — the SAP write guard pattern and the HITL-always-required policy. These are the decisions an interviewer probes first.

ADR-010 (restated)
XGBoost over neural network — deterministic SHAP is a regulatory requirement, not a preference
Neural networks were evaluated (MLP, BERT fine-tuned for structured tabular features). Rejected because EU AI Act Article 13 requires that the explanation provided to the Finance Controller is reproducible — if an auditor asks six months later why contract CV2026-0042 was classified as MULTI-ELEMENT, the SHAP values stored in BigQuery must match what the Finance Controller saw at approval time. XGBoost's TreeExplainer produces exact, deterministic SHAP values that are bit-for-bit reproducible given the same model version and input. Neural network SHAP (DeepExplainer / KernelExplainer) produces approximations that vary between runs — storing approximate explanations in an immutable audit trail is architecturally inconsistent. XGBoost also performs competitively on the 4,800-contract training set and is less prone to overfitting at this dataset size.
Accepted · Phase ML Design · Page 06 ADR-010
ADR-R01 — RevRec AI specific
SAP GL write requires a committed HITL approval record ID as a mandatory API parameter
The alternative design was to implement SAP write authorisation as an application-level check — the agent checks a Firestore document for an approval flag before calling the SAP API. Rejected because application-level checks can be bypassed by a bug, a configuration error, or a future code change that misses the check. The current design makes the SAP write structurally impossible without the HITL approval record: the sap.post_journal_entry() tool requires hitl_id as a typed, non-optional parameter. If the HITL record does not exist in Firestore, the parameter cannot be populated and the SAP call cannot be formed. The constraint is in the function signature, not in conditional logic. This distinction matters for the FDA 21 CFR 820 change control argument — a future developer modifying the SAP integration cannot accidentally remove the HITL requirement without explicitly changing the function signature, which would be caught in PR review.
Accepted · Phase Agent Design · RevRec AI module
ADR-R02 — RevRec AI specific
HITL-04 required for every classification without a confidence threshold exception
A threshold-based HITL policy was evaluated — classifications above 0.95 confidence could be auto-approved, saving the Finance Controller time on straightforward transactions. Rejected for three reasons. (1) EU AI Act Annex III does not distinguish between high-confidence and low-confidence AI decisions for revenue recognition — the human oversight obligation applies to the decision, not the confidence level. (2) The Finance Controller's trust in the model must be earned through the approval process itself — auto-approving high-confidence classifications removes the feedback loop that builds that trust. Override decisions on low-confidence classifications are the training signal for the next model version. (3) The compliance posture is cleaner and more defensible: "every classification has a human approval record" is a statement that requires no caveats. "Every classification above 0.95 confidence is auto-approved" requires explaining the threshold choice, the threshold-setting methodology, and the monitoring for threshold drift — a significantly larger compliance burden.
Accepted · Phase Product Design · Page 04 HITL specification
Stakeholder Rebuttals

Six objections. Each with an architectural answer.

These are the objections that will be raised in the ClaraVis engagement — and the objections an interviewer will probe. Each rebuttal is grounded in a specific design decision already documented in the portfolio. The answer is never "trust us" — it is always "here is the architectural evidence."

CTO · S-01
Why does a classification model need to be this complex?
"We already have a Finance team that does this manually. Why do we need XGBoost, SHAP, Vertex AI Pipelines, a Feature Store, and a HITL framework just to classify a contract?"
Architectural response
The complexity is not in the model — XGBoost is a relatively simple algorithm. The complexity is in the compliance obligations. The EU AI Act requires a documented explanation for every high-risk AI decision. The FDA requires a change control record for every software modification that affects a production AI system. ASC 606 requires a defensible classification basis for every revenue recognition event. Each of those obligations drives a specific architectural component. The SHAP layer satisfies EU AI Act Art. 13. The HITL-11 pipeline gate satisfies FDA change control. The Feature Store lineage satisfies the ASC 606 documentation requirement. Remove any one of those components and a specific regulatory obligation becomes unmet. The architecture is as simple as the regulatory environment allows it to be.
Evidence in design: Architecture Principles P-03 (compliance as write-path constraints) · ADR-010 (XGBoost chosen for SHAP determinism, not arbitrary) · Page 03 ADM Phase D
CCO · S-02
Will this satisfy the EU AI Act auditor?
"When the regulator asks me to demonstrate EU AI Act Annex III compliance for this system, what exactly do I show them? An architecture diagram isn't an audit trail."
Architectural response
The audit evidence package is queryable from BigQuery in under 30 seconds. For any inference: SELECT * FROM ae_audit.shap_explanations WHERE transaction_id = 'X' returns the exact SHAP values presented to the Finance Controller. SELECT * FROM ae_audit.hitl_events WHERE hitl_id = 'Y' returns the approval record — approver identity, decision, reason code, timestamp, and the SHAP explanation ID it references. The SHAP explanation is written to BigQuery before the HITL checkpoint is created — so the audit record cannot be retrospectively amended to match the decision. The Model Cards for the ASC 606 model are versioned in Vertex AI Model Registry alongside the model itself — the model the auditor can inspect is the same model that produced the classifications in the audit trail.
Evidence in design: HITL-04 specification · Page 04 · BigQuery shap_explanations schema · Page 06 Model Card · EU AI Act Art. 11/13/14 compliance checklist · RevRec AI Model Card
Finance Controller
I don't trust a black-box model to classify revenue
"I've been classifying these contracts for twelve years. I know when something is a multi-element arrangement. I'm not going to let an AI decide this and just rubber-stamp it."
Architectural response
You won't be rubber-stamping it — you'll be reviewing it with more information than you have today. The HITL-04 queue shows you the model's classification, the five contract features that drove it, their direction and magnitude, and three comparable contracts you have personally approved in the past. If the model is wrong, you override it with a reason code and the override becomes a training example for the next model version — making the model learn from your judgment. The model does not replace your expertise. It pre-processes the contract, surfaces the most relevant features, and presents a recommendation. The decision — and the immutable record of it — remains yours. The SAP GL write will not execute without your explicit approval on this specific checkpoint.
Evidence in design: HITL-04 UI mockup above · SHAP chart · comparable transactions · override with reason code · ADR-R02 (HITL required for all classifications)
Enterprise Architect · S-08
How does this integrate with our Salesforce data model without customising it?
"We have a heavily customised Salesforce org. If RevRec AI needs specific fields or objects that don't exist in our standard Contract object, that's a Salesforce project on its own."
Architectural response
RevRec AI reads from Salesforce using the standard Contract and OpportunityLineItem objects — no custom fields, no custom objects, no Salesforce configuration changes required. The 18 contract features are all derivable from standard Salesforce fields: contract value from Amount, payment terms from PaymentTerms, SKU complexity from OpportunityLineItems count and service ratio. The Feature Store computation logic handles the feature engineering from standard fields. RevRec AI writes back a single Activity record on the Contract object using the standard Activity API — again, no custom fields. The Salesforce Developer Edition integration (ADR-001) was specifically designed and tested against the standard object model to validate this claim before the architecture was frozen.
Evidence in design: ADR-001 (SFDC Developer Edition validation) · Feature Store contract feature group definition · Page 06 · standard object read list · Page 05 agent tool manifest
CISO · S-09
Does the SAP write send ClaraVis financial data outside the VPC-SC perimeter?
"When RevRec AI posts to SAP, is that financial transaction data leaving our GCP VPC-SC boundary? SAP is on-premise — that data is crossing a network boundary I need to understand and approve."
Architectural response
The SAP write in the portfolio design uses a mock BigQuery table for the demo environment — SAP is on-premise and the production integration would be via a SAP BTP Event Mesh bridge or RFC middleware, both of which are standard enterprise integration patterns documented in ADR-R01. The data flow is directional: RevRec AI sends a classification result and performance obligation tags to SAP — it does not receive or store SAP financial data within the GCP environment. The HITL approval record and audit trail stay entirely within the VPC-SC perimeter in Firestore and BigQuery. The SAP write message carries only the classification output — contract ID, recognition type, performance obligation tags, and the HITL record ID. No sensitive financial transaction data from SAP is pulled into the GCP environment at any point in the RevRec AI workflow.
Evidence in design: Page 07 VPC-SC perimeter diagram · ADR-R01 (SAP write as output-only) · Page 05 agent tool manifest (sap.post_journal_entry parameters) · Page 03 ADR-006 (Pub/Sub event bus for decoupling)
CFO · S-03
Why does every single classification need human approval?
"If the model is right 94% of the time with confidence above 0.90, why are we paying a Finance Controller to approve thousands of routine transactions? Auto-approve the high-confidence ones and use HITL for the edge cases."
Architectural response
ADR-R02 documents this decision in full — the short answer is that "every classification has a human approval record" is a cleaner compliance posture than "every classification above threshold X has a human approval record." The threshold choice, the threshold-setting methodology, and the monitoring for threshold drift all become additional compliance obligations. The Finance Controller's actual workload is lower than it sounds: the HITL-04 queue presents the classification with a SHAP chart and comparable transactions — a straightforward approval takes approximately 90 seconds. The volume of contracts ClaraVis signs per month is not so large that this creates an operational bottleneck. And the override decisions — which would not exist under auto-approval — are the highest-value training signal for improving the model over time. The cost of auto-approving high-confidence classifications is not just regulatory: it removes the feedback loop that makes the model better.
Evidence in design: ADR-R02 · HITL-04 UI mockup (90-second approval flow) · Page 06 Model Card (override rate metric as quality signal) · Page 06 concept drift detection (override rate as drift indicator)
Demo Pathway

Three minutes. One contract. One HITL moment.

This is the scripted demo pathway for RevRec AI. Use it as a rehearsal script. The scenario: ClaraVis AG signs an MRI-7T + 5-year service contract with University Hospital Munich (€2.84M). The model classifies it as MULTI-ELEMENT. The Finance Controller approves in the HITL queue. SAP posts. Full audit trail committed.

00
Setup · 30 seconds before
Pre-load the Salesforce Developer Edition org
Open the Salesforce Developer Edition org. Show the Contract object for ClaraVis AG — Universitätsklinikum München — status: Activated. Show the OpportunityLineItems: MRI-7T unit, Premium Service 5yr, Clinical Training package, Remote Monitoring subscription. This is the contract RevRec AI is about to classify.
Salesforce Developer Edition Contract object OpportunityLineItems
01
Trigger · 0:00
Change the Contract status to Activated — trigger the classification
In Salesforce, move the Contract status to Activated. This fires a Salesforce trigger that publishes a contract_signed event to the ae-q2c-events Pub/Sub topic. Show the Pub/Sub monitoring console — the message appears within 2 seconds.
"The moment this contract is activated in Salesforce, RevRec AI is already working. There's no batch job, no manual trigger — the event bus picks it up immediately."
Salesforce REST API Pub/Sub ae-q2c-events Cloud Run RevRec agent
02
Inference · 0:15
Show the Cloud Run logs — feature extraction, inference, SHAP
Open Cloud Run logs for the revrec-ai service. Show the log sequence: "Extracting contract features from Salesforce…", "Fetching 18 features from Feature Store…", "Running XGBoost inference…", "Computing SHAP explanation…", "Writing SHAP to BigQuery shap_explanations BEFORE creating HITL…", "Creating HITL-04 checkpoint…". The entire sequence completes in under 12 seconds.
"Notice that SHAP is written to BigQuery before the HITL checkpoint is created — not after. This means the explanation the Finance Controller sees is the same explanation that's in the audit trail. There's no gap between what was explained and what was recorded."
Cloud Run logs Vertex AI Feature Store Vertex AI endpoint SHAP TreeExplainer BigQuery shap_explanations
03
HITL-04 · 0:45 — this is the moment
Open the Finance Controller's HITL queue — show the approval interface
Navigate to the HITL Approval UI. Show the Finance Controller's queue — one item: Contract CV2026-0042. Open it. The interface shows: classification (MULTI-ELEMENT ARRANGEMENT), confidence (0.91), the SHAP bar chart with five features, and three comparable contracts the Finance Controller has approved before.
"This is what HITL-04 looks like in practice. The Finance Controller sees the model's recommendation, the reasoning behind it in plain feature language, and three contracts they've approved before that are similar. They're not rubber-stamping a black box — they're reviewing a recommendation with context. The approval takes about 90 seconds for a straightforward case. Click Approve."
HITL Approval UI Firestore HITL state SHAP chart Comparable transactions
04
SAP Write · 1:30
Show the SAP GL write — and the write guard in action
After the Finance Controller clicks Approve, show the Cloud Run logs again: "HITL decision received: APPROVE", "Committing immutable HITL record to Firestore…", "hitl_id: hitl_20260315_rr_004 committed", "Initiating SAP GL write with hitl_id parameter…", "SAP GL posting confirmed: doc_id SAP-2026-031501". Navigate to the mock SAP BigQuery table — show the posted entry with the HITL record ID as a foreign key.
"The SAP write only executed because a HITL record existed. If I show you the sap.post_journal_entry function signature — hitl_id is a required parameter. You literally cannot call this function without one. The write guard isn't an if-statement — it's the function signature."
Firestore immutable write SAP mock (BigQuery) Cloud Run logs
05
Audit Trail · 2:15
Query the complete audit trail in BigQuery
Open BigQuery. Run: SELECT s.feature_name, s.shap_value, h.decision, h.approver_id, h.ts FROM ae_audit.shap_explanations s JOIN ae_audit.hitl_events h ON s.transaction_id = h.task_id WHERE s.transaction_id = 'CV2026-0042'. The result shows every SHAP value alongside the human decision and approver identity — the complete EU AI Act Article 13 + 14 evidence package in one query.
"When the EU AI Act auditor asks for the evidence package for this classification — this is it. One BigQuery query. Under 30 seconds. The SHAP explanation, the human decision, the approver, and the timestamp. Everything they need to verify that Article 13 and Article 14 were satisfied for this specific transaction."
BigQuery ae_audit shap_explanations table hitl_events table
06
Optional extension · 2:45
Show what happens when the Finance Controller overrides
If time permits: trigger a second classification on a simpler contract. In the HITL queue, click Override instead of Approve. Enter reason code "OR-03: Revenue not in current period". Show the override being committed to Firestore. Show the Cloud Run log: "Override decision committed · creating training example for next retraining cycle". Navigate to the BigQuery ground_truth_labels table — the override appears as a labelled training example. Point to the concept drift monitoring section on Page 06 — this override just moved the HITL override rate metric.
"An override is not a failure. It's the highest-value signal the model can receive. The Finance Controller just told the model it was wrong, explained why, and that explanation is now a training example. The model improves from every override decision."
HITL override flow BigQuery ground_truth_labels Concept drift monitoring
AE Suite Navigation
Module 03 complete.
Return to the suite.

RevRec AI is the template for every subsequent module page — the same seven sections, the same depth, the same pattern of context → architecture → state machine → data flow → HITL UI → ADRs → rebuttals → demo. The remaining seven modules follow.

PG 09
← AE Suite Index
All 8 modules · dependency matrix · demo pathway index
PG 06
ML Engineering & MLOps
RevRec AI model card · pipeline · drift detection
PG 05
Agent Swarm Architecture
RevRec AI agent specification · A2A · tool manifest