Page 10 · The Autonomous Finance Operations[cite: 13]
Architecture
Decision Records.
Six binding decisions — each encoding a constraint that shaped the system's structure[cite: 13]. Written at design time, stored in version control, referenced by every agent that touches financial data[cite: 13]. Not post-hoc documentation[cite: 13]. The architecture is the argument[cite: 13].
ADR-AF-01 · SAP Write Gate[cite: 13]
ADR-AF-02 · IC Anomaly Ensemble[cite: 13]
ADR-AF-03 · Cash Forecast Ensemble[cite: 13]
ADR-AF-04 · Agent Service Topology[cite: 13]
ADR-AF-05 · SOX/SEC Dataset Separation[cite: 13]
ADR-AF-06 · ISO 20022 Bank Connectivity[cite: 13]
ADR-AF-01 · Intercompany Write Gate · Authority: Principal Architect · Supersedes: None[cite: 13]
SAP Write Requires Committed HITL
Approval Record ID as Mandatory Parameter
Write-Gate Flow — IC Journal Correction[cite: 13]
Context
The intercompany reconciliation agent proposes journal corrections in SAP when it detects a mismatch between entity-pair balances[cite: 13]. Without a hard gate, a misconfigured agent, a replay attack, or a latent bug in the correction logic could write directly to the ledger without a human having ever reviewed the entry[cite: 13]. In an EU AI Act Annex III context, automated financial decision-making requires a verifiable human approval step — an application-level flag is insufficient because it can be bypassed by direct API call, environment variable override, or deployment misconfiguration[cite: 13].
Decision
Every SAP BAPI or OData write that modifies the intercompany ledger must carry a committed approval record ID as a mandatory parameter[cite: 13]. The gate validates this ID against the HITL audit table in BigQuery before executing[cite: 13]. An absent, expired, or already-consumed ID causes the write to be rejected at the gate — no exception path exists[cite: 13]. The approval record is written to BigQuery and considered committed only after a named controller has approved the specific correction payload[cite: 13]. The record ID is single-use: a second write attempt with the same ID is rejected[cite: 13].
Alternatives Considered
Application-level flag check: A boolean field on the agent's write request (e.g. hitl_approved: true) rejected because the flag is set by the same application that requests the write[cite: 13]. There is no structural guarantee the flag was set as a result of a real human review — it can be hardcoded in a test environment and promoted to production[cite: 13]. The gate must be external to the agent process and must validate against a durable record[cite: 13].
Row-level SAP authorisation roles: Assigning the agent's service account the SAP role required to post journals, then relying on role governance[cite: 13]. Rejected because role-based access controls who can write, not whether a specific write has been approved[cite: 13]. The same service account would be authorised to post corrections both with and without prior HITL review — the approval constraint is not encoded in the authorisation model[cite: 13].
Pre-write webhook to HITL service: Call the HITL service synchronously before posting; approve inline[cite: 13]. Rejected because inline approval collapses the time gap between proposal and approval to near-zero, defeating the purpose of human review[cite: 13]. Controllers need time to inspect the payload, cross-reference the entity graph, and verify against the IC agreement register — a synchronous call makes that inspection window a latency parameter, not a structural requirement[cite: 13].
Consequences
- No journal correction can reach SAP without a prior committed approval record — structurally enforced, not policy-enforced[cite: 13].
- The approval record ID creates a tamper-evident link between every SAP posting and its HITL audit trail entry[cite: 13].
- Replay protection via single-use IDs prevents duplicate posting from agent retries or infrastructure failures[cite: 13].
- Infrastructure failure between gate validation and SAP write confirmation requires a new HITL approval cycle — by design[cite: 13]. The connector distinguishes gate-passed vs. SAP-confirmed states; a gate-passed-but-SAP-failed write is routed to a dead-letter queue for manual resolution, not silently discarded[cite: 13].
- EU AI Act Art. 14 (human oversight) compliance is structural: the approval record is the evidence artifact for regulatory inspection[cite: 13].
- Adds one round-trip latency to the correction workflow[cite: 13]. Acceptable given the batch-processing nature of month-end reconciliation[cite: 13].
Status
Accepted. Implemented in the IC agent's SAP connector module[cite: 13]. Gate enforced at the connector layer, not the agent layer — agent cannot self-issue an approval record ID[cite: 13].
ADR-AF-02 · IC Anomaly Model Selection · Authority: Principal Architect · Supersedes: None[cite: 13]
Isolation Forest + XGBoost Ensemble
for IC Anomaly Detection
Ensemble Architecture — IC Anomaly Detection[cite: 13]
Context
The intercompany anomaly detection model must satisfy two constraints simultaneously: it must produce explainable outputs at inference time (EU AI Act Article 13 — transparency for high-risk AI in financial services) and it must perform well on the entity-pair mismatch detection task where labelled training data is sparse[cite: 13]. Pure deep learning approaches satisfy neither constraint without significant additional engineering overhead[cite: 13].
Decision
Deploy an ensemble of Isolation Forest (unsupervised anomaly scoring — no labelled data required at initialisation) and XGBoost classifier (supervised refinement trained on HITL override labels as they accumulate)[cite: 13]. Scores are fused via a weighted combiner[cite: 13]. Any fused score above the 0.72 threshold triggers SHAP TreeExplainer — deterministic, not stochastic — which is applied to the XGBoost component only[cite: 13]. Isolation Forest anomaly scores are surfaced as raw input features to the XGBoost layer, not independently explained via SHAP[cite: 13]. The XGBoost SHAP output, which encodes the contribution of all features including the Isolation Forest score, constitutes the explanation payload stored in the HITL audit trail and presented to the controller[cite: 13]. This scoping ensures SHAP determinism is preserved and that the Art. 13 explanation reflects the decision-making component, not the unsupervised scoring layer where SHAP stability guarantees do not hold[cite: 13].
Alternatives Considered
Pure deep learning (LSTM autoencoder): Rejected primarily on EU AI Act Article 13 grounds[cite: 13]. LSTM autoencoders produce reconstruction error as the anomaly score — explaining which input features drove the error requires gradient-based attribution methods (Integrated Gradients, SHAP DeepExplainer) that are non-deterministic across runs on GPU hardware[cite: 13]. A regulator asking for the same explanation twice would receive a different answer[cite: 13]. For IC corrections that modify the legal entity ledger, explanation determinism is a hard requirement[cite: 13].
Single XGBoost classifier (no Isolation Forest component): Rejected because at system initialisation, labelled IC anomaly data does not exist — HITL labels accumulate only after the system is live[cite: 13]. A pure supervised model cannot be deployed without a cold-start solution[cite: 13]. Isolation Forest handles the cold-start period without labels; XGBoost weight increases as HITL labels accumulate[cite: 13]. The ensemble structure allows graceful degradation to unsupervised operation if the supervised component underperforms[cite: 13].
Statistical process control (Z-score over rolling baseline): Rejected because IC mismatch patterns are not normally distributed[cite: 13]. Entity pairs with seasonal intercompany volume (quarter-end sweeps, annual recharges) produce legitimate variance that triggers Z-score alerts[cite: 13]. The SPC approach has no mechanism to condition on entity-pair history, agreement register, or cross-entity FX timing — all of which the XGBoost feature set encodes[cite: 13]. False positive rate in back-testing was 3× higher than the ensemble[cite: 13].
Consequences
- SHAP TreeExplainer determinism satisfies EU AI Act Article 13 — SHAP is applied to the XGBoost component only[cite: 13]. Isolation Forest scores are input features to XGBoost, not independently explained[cite: 13]. The same input produces the same explanation on every run, independent of hardware[cite: 13].
- Isolation Forest component provides production-ready anomaly detection from day one without waiting for labelled data[cite: 13].
- XGBoost component improves over time as HITL override labels are fed back through the retraining pipeline[cite: 13].
- Ensemble fusion logic must be maintained — weight calibration reviewed quarterly or when override rate exceeds the drift threshold[cite: 13].
- SHAP computation adds ~40ms per inference above the 0.72 threshold[cite: 13]. Acceptable for IC reconciliation which is not a real-time workload[cite: 13].
Status
Accepted. Ensemble in production[cite: 13]. SHAP explanations stored in the HITL audit trail[cite: 13]. Weight calibration scheduled for Q2 2026 after the first full quarter of HITL label accumulation[cite: 13].
ADR-AF-03 · Cash Forecasting Model Selection · Authority: Principal Architect · Supersedes: None[cite: 13]
LightGBM + Prophet Ensemble
for Cash Forecasting
Ensemble Forecast Architecture — 13-Week Rolling Cash Horizon[cite: 13]
Context
Cash forecasting for a mid-market European group involves two structurally different signal types: calendar-driven seasonality (payroll runs on fixed dates, VAT settlement on quarter-end, public holidays that delay banking) and structural features that require cross-referencing (FX rates, intercompany sweep history, AP aging, credit line utilisation)[cite: 13]. A single model architecture optimised for one signal type performs poorly on the other[cite: 13]. Additionally, the training dataset spans 36 months of entity-level cash flow — insufficient for LSTMs in financial time series, which require substantially longer histories to learn long-range seasonal dependencies without overfitting[cite: 13].
Decision
Deploy a Prophet + LightGBM stacking ensemble[cite: 13]. Prophet handles calendar seasonality explicitly through its native regressor interface — payroll dates, quarter-end, public holiday calendars per jurisdiction are registered as regressors, not inferred from the time series[cite: 13]. LightGBM handles structural features: FX rates, IC sweep history, AP aging, credit line data[cite: 13]. A meta-learner trained on holdout data determines the MAPE-weighted blend ratio per forecast horizon[cite: 13]. Output is a 13-week rolling forecast with P10/P50/P90 uncertainty bands per entity and consolidated[cite: 13].
Alternatives Considered
LSTM sequence model: Rejected on training data size[cite: 13]. LSTMs for financial time series require substantially more than 36 months of entity-level data to generalise across the full seasonal cycle without memorising noise[cite: 13]. ClaraVis's entity-level cash flow history is 36 months per entity at monthly granularity — insufficient at the daily granularity required for a 13-week rolling forecast[cite: 13]. Additionally, LSTM hyperparameter sensitivity (sequence length, hidden units, dropout) requires a tuning infrastructure disproportionate to the dataset size[cite: 13]. Prophet's additive model converges reliably on datasets of this size[cite: 13].
Pure Prophet (no LightGBM component): Rejected because Prophet's regressor interface cannot encode non-linear interactions between structural features[cite: 13]. The relationship between FX rate movements and IC settlement timing is non-linear and conditional on entity-pair agreement structure — a pattern LightGBM captures naturally but Prophet's additive decomposition cannot represent without significant feature engineering that would replicate LightGBM's function[cite: 13].
Pure LightGBM (no Prophet component): Rejected because LightGBM requires calendar seasonality to be encoded as hand-crafted features (day-of-month, is-quarter-end flags, jurisdiction-specific holiday dummies)[cite: 13]. This feature engineering must be maintained as calendar rules change — payroll schedule changes, new public holidays, VAT payment date changes[cite: 13]. Prophet's regressor interface accepts calendar objects directly, decoupling the model from feature engineering maintenance[cite: 13].
Consequences
- LightGBM's quantile regression mode provides P10/P50/P90 forecast bands per entity and consolidated — the Treasury dashboard surfaces uncertainty range, not a point forecast, to avoid misleading CFO/Treasurer users[cite: 13].
- Prophet component handles calendar seasonality without bespoke feature engineering — calendar updates propagate through the regressor interface[cite: 13].
- LightGBM component captures non-linear structural feature interactions that Prophet's additive model cannot represent[cite: 13].
- Stacking blend requires a holdout evaluation set — 6 months held out from the 36-month history for meta-learner training[cite: 13].
- SHAP attribution via LightGBM's native TreeExplainer provides per-feature contribution at each forecast horizon — satisfies Art. 13 transparency for treasury decisions[cite: 13].
- Two model retraining schedules must be managed independently: Prophet quarterly (calendar drift), LightGBM monthly (structural signal drift)[cite: 13].
Status
Accepted. Ensemble deployed[cite: 13]. Initial blend ratio: Prophet 0.55 / LightGBM 0.45, calibrated on holdout[cite: 13]. To be recalibrated after six months of production MAPE data[cite: 13].
ADR-AF-04 · Agent Service Topology · Authority: Principal Architect · Supersedes: None[cite: 13]
Three Separate Cloud Run Services
over a Single Monolithic Agent
Agent Service Topology — Independent Scaling & Failure Domains[cite: 13]
Context
Three agents handle distinct finance domains: AP exception processing (high volume, invoice-driven, 10× the event rate of IC), intercompany reconciliation (low volume, month-end burst), and treasury visibility (continuous, low latency)[cite: 13]. Their scaling requirements, failure domains, HITL SLA commitments, and deployment cadences are structurally different[cite: 13]. A single service cannot satisfy all three sets of requirements without either over-provisioning (expensive) or creating a single failure domain that takes down all three agents simultaneously[cite: 13].
Decision
Deploy three separate Cloud Run services — one per agent domain — each with independent autoscaling configuration, independent HITL SLA, independent deployment pipeline, and independent failure boundary[cite: 13]. Services share the HITL service, SAP connector, and audit log as separately deployed infrastructure[cite: 13]. Pub/Sub topics route events to the correct agent service[cite: 13]. No cross-service dependencies at the application layer[cite: 13].
Alternatives Considered
Single LangGraph graph with domain subgraphs: Rejected because a failure in one subgraph propagates to the graph executor[cite: 13]. LangGraph's graph runtime is a single process — an unhandled exception in the AP subgraph kills the runtime serving IC and Treasury concurrently[cite: 13]. During month-end, this means a high-volume AP exception (the most likely failure point) can take down the IC reconciliation agent at the moment it is most needed[cite: 13]. Failure isolation requires process isolation, not code modularity[cite: 13].
Single Cloud Run service with internal routing: A single service with route handlers per agent domain[cite: 13]. Rejected because autoscaling is per-service in Cloud Run[cite: 13]. A spike in AP invoice volume scales up instances that also handle IC and Treasury workloads, incurring unnecessary cost[cite: 13]. Conversely, IC month-end bursts compete for instances with steady-state AP volume[cite: 13]. Independent scaling requires independent services[cite: 13].
GKE microservices: Kubernetes-based deployment per agent[cite: 13]. Rejected at this scale — three agents with shared infrastructure do not justify the operational overhead of a Kubernetes cluster (control plane cost, node pool management, network policy maintenance)[cite: 13]. Cloud Run provides equivalent isolation with substantially lower operational surface area[cite: 13]. GKE is reconsidered if agent count exceeds eight or if the mesh routing pattern requires service-mesh capabilities unavailable in Cloud Run[cite: 13].
Consequences
- AP agent scales to max=80 instances during invoice volume peaks without affecting IC or Treasury service capacity[cite: 13].
- A failure in any single agent service does not affect the other two — failure domain isolation is structural[cite: 13].
- Three independent deployment pipelines enable zero-downtime updates to any agent without coordinating with others[cite: 13].
- Three independent HITL SLAs can be negotiated with finance operations — AP may tolerate higher latency than Treasury[cite: 13].
- Shared infrastructure (HITL service, SAP connector, audit log) must be deployed and maintained independently — added operational surface, offset by the isolation benefit[cite: 13].
Status
Accepted. Three Cloud Run services deployed[cite: 13]. AP: min=0, max=80[cite: 13]. IC: min=0, max=8[cite: 13]. Treasury: min=1, max=4[cite: 13]. Pub/Sub routing configured with separate topics per domain[cite: 13].
ADR-AF-05 · SOX/SEC Compliance Pattern · Authority: Principal Architect · Supersedes: None[cite: 13]
SOX/SEC Compliance via Dataset Separation
over Field-Level Tagging
SOX/SEC Data Retention Architecture — BigQuery Dataset Separation[cite: 13]
Context
The treasury visibility agent requires real-time cash position data and payment instruction capability across four banking relationships: Deutsche Bank (EU entities), ING (Netherlands and EU operations), UBS (Swiss entity), and JPMorgan Chase (US entity)[cite: 13]. Three connectivity patterns are available: screen-scraping of bank portals, proprietary bank API integrations, and ISO 20022 Open Banking[cite: 13]. Each represents a different maintenance surface, regulatory position, and integration complexity[cite: 13].
Decision
Separate US entity data into a dedicated BigQuery dataset (af_us_soxsec) deployed in the us-central1 region[cite: 13]. Dataset-level IAM policy restricts access to the US-entity service account only and encodes purpose limitation as a dataset label[cite: 13]. An SEC auditor can verify retention policy from the dataset's configuration metadata and purpose limitation from the IAM policy — neither requires inspecting query logs[cite: 13]. Cross-dataset joins between af_us_soxsec and other datasets are blocked by IAM boundary — enforced structurally, not by application logic[cite: 13].
Alternatives Considered
Field-level tagging with Data Catalog: Tag each field containing US financial records in the shared dataset using BigQuery Data Catalog sensitivity tags[cite: 13]. Rejected because field-level tagging is a labelling mechanism, not an access control mechanism[cite: 13]. Verifying SOX/SEC compliance requires inspecting Data Catalog tag assignments per field across all tables — an audit process that requires BigQuery API access and catalogue query execution[cite: 13]. The dataset separation approach allows audit from the console: the dataset exists, its retention configuration is set, and its IAM policy shows the purpose and access restrictions[cite: 13].
Application-layer filtering: Store all entity data in a shared dataset; filter US data at the application layer by entity code before any processing[cite: 13]. Rejected because application-layer filtering does not constitute structural retention control — the data is governed by whatever retention policy the shared dataset carries, regardless of which entity code the query selects[cite: 13]. SEC auditors evaluate retention controls at the storage layer, not the query layer[cite: 13]. Application-layer filtering also creates a risk of filter bypass in edge cases (bulk analytics, ML training pipelines)[cite: 13].
Separate GCP project for US entity: Deploy the entire infrastructure stack in a US-region GCP project[cite: 13]. Rejected on cost and operational grounds — duplicating Pub/Sub, Cloud Run services, monitoring, and logging infrastructure for a single legal entity that represents approximately 8% of total entity volume is not proportionate[cite: 13]. Dataset separation within the same project achieves the required retention and access boundary at a fraction of the operational cost[cite: 13].
Consequences
- SEC audit can be completed from the BigQuery console without querying production logs — retention policy and purpose limitation are verifiable from metadata[cite: 13].
- IAM boundary prevents cross-dataset joins — consolidated reporting that spans US and EU entities must be implemented via aggregated views in the global dataset, not raw joins[cite: 13].
- US entity ML training must use only the af_us_soxsec dataset — training on the global dataset with US data excluded via WHERE clause does not satisfy the structural separation requirement[cite: 13].
- Dataset provisioning script must be version-controlled and immutable — IAM policy changes require a PR review cycle to maintain audit trail[cite: 13].
- Under review pending legal confirmation that dataset-level separation satisfies external counsel's current interpretation of SEC Rule 17a-4 retention requirements[cite: 13].
Status
Under Review. Implementation complete[cite: 13]. Under review pending written confirmation from ClaraVis's US securities counsel that dataset-level BigQuery separation satisfies SEC Rule 17a-4(f) guidance on electronic recordkeeping[cite: 13]. Expected resolution Q2 2026[cite: 13].
ADR-AF-06 · Bank Connectivity Standard · Authority: Principal Architect · Supersedes: None[cite: 13]
ISO 20022 as the Single Standard
for Bank-to-Corporate Connectivity
ISO 20022 Integration Architecture — Four Banking Relationships via Single Adapter Pattern[cite: 13]
Context
The treasury visibility agent requires real-time cash position data and payment instruction capability across four banking relationships: Deutsche Bank (EU entities), ING (Netherlands and EU operations), UBS (Swiss entity), and JPMorgan Chase (US entity)[cite: 13]. Three connectivity patterns are available: screen-scraping of bank portals, proprietary bank API integrations, and ISO 20022 Open Banking[cite: 13]. Each represents a different maintenance surface, regulatory position, and integration complexity[cite: 13].
Decision
Implement ISO 20022 Open Banking as the single bank connectivity standard[cite: 13]. All four banking relationships support ISO 20022 post-2025 (the EU mandated migration deadline)[cite: 13]. A single adapter handles camt.052 (intraday position), camt.053 (end-of-day statement), pain.001 (payment initiation), and pacs.008 (credit transfer)[cite: 13]. One integration pattern covers all four banks[cite: 13]. Message schema validation is enforced at the adapter layer before any data reaches the agent[cite: 13].
Alternatives Considered
Proprietary bank API integrations (four bespoke integrations): Each bank provides a proprietary REST API with different authentication schemes, data models, rate limits, and versioning cycles[cite: 13]. Rejected because maintaining four independently versioned integrations — each with its own SDK, credential rotation schedule, and regression test suite — represents a disproportionate engineering maintenance burden relative to the connectivity function[cite: 13]. Any change to a bank's API model requires a dedicated integration update cycle[cite: 13]. ISO 20022 provides a stable, standards-based contract[cite: 13].
Screen-scraping via headless browser: Automate bank portal login and position data extraction via Playwright or equivalent[cite: 13]. Rejected categorically — screen-scraping violates bank terms of service, is fragile to portal UI changes, cannot handle MFA requirements reliably in an unattended context, produces no structured data contract, and cannot be used for payment initiation[cite: 13]. Not considered a viable integration pattern for production treasury infrastructure[cite: 13].
SWIFT gpi (global payments innovation): SWIFT's enhanced correspondent banking network with payment tracking[cite: 13]. Rejected as the primary connectivity pattern because SWIFT gpi is oriented toward cross-border payment tracking, not real-time intraday balance reporting[cite: 13]. It also requires SWIFT membership or a correspondent bank relationship, adding cost and onboarding time[cite: 13]. ISO 20022 is the ECB-mandated standard for the TARGET2/T2 migration and covers the real-time balance and payment instruction use cases for EU bank-to-corporate connectivity directly[cite: 13].
Consequences
- Single ISO 20022 adapter covers all four banking relationships — one integration pattern to maintain, test, and version[cite: 13].
- ISO 20022 is the ECB-mandated standard for EU high-value and domestic payment messaging post-2025 (TARGET2/T2 migration) — regulatory longevity is assured for the EU banking relationships, unlike proprietary bank APIs subject to deprecation[cite: 13].
- Adding a fifth banking relationship (if ClaraVis expands) requires bank onboarding only — the adapter code is unchanged if the new bank supports ISO 20022[cite: 13].
- Message schema validation at the adapter layer provides a structural contract — malformed bank responses are rejected before reaching agent logic[cite: 13].
- ISO 20022 message parsing requires XML schema validation — a modest additional compute cost per message accepted relative to JSON REST APIs[cite: 13].
- JPMorgan Chase's ISO 20022 implementation uses the US Faster Payments-aligned profile — minor message field differences from the EU profile require adapter configuration per banking relationship, not code changes[cite: 13].
Status
Accepted. ISO 20022 adapter deployed[cite: 13]. Deutsche Bank and ING connected and validated in staging[cite: 13]. UBS and JPMorgan Chase onboarding in progress — expected production cut-over Q2 2026[cite: 13].
Regulatory encoding across all six ADRs: ADR-AF-01 encodes EU AI Act Art. 14 human oversight structurally via the SAP write gate[cite: 13]. ADR-AF-02 encodes Art. 13 transparency via SHAP determinism (scoped to the XGBoost component; see ADR for scope note)[cite: 13]. ADR-AF-03 satisfies Art. 13 for treasury decisions via LightGBM SHAP attribution with P10/P50/P90 forecast bands[cite: 13]. ADR-AF-04 enables independent HITL SLA management per agent domain — a prerequisite for Art. 14 compliance at scale[cite: 13]. ADR-AF-05 (Under Review) — SOX/SEC retention and purpose limitation encoding is the intended outcome pending written confirmation from US securities counsel; regulatory status is not yet finalised[cite: 13]. ADR-AF-06 ensures bank-to-corporate connectivity via ISO 20022, the mandated standard for EU high-value and domestic payment messaging post-2025 (ECB TARGET2/T2 migration)[cite: 13]. None of these decisions are retrofitted — each is a load-bearing constraint that shaped the architecture from first principles[cite: 13].