TOGAF ADM — Phases A–F · The Autonomous Seller

Architecture Development Method

The ADM applied to ClaraVis.

TOGAF's Architecture Development Method provides the process framework. Each phase below produces a specific artifact for the ClaraVis engagement. Requirements Management is continuous — every requirement from Page 02 is live throughout every phase.

Prelim

Preliminary

Architecture Principles · Governance model · Tailoring decisions

Phase A

Architecture Vision

Statement of Architecture Work · Stakeholder map · Solution concept

Phase B

Business Architecture

To-Be value stream · Capability model · Business interaction map

Phase C

IS Architecture

Canonical data model · Application portfolio · Integration catalog

Phase D

Technology Architecture

GCP reference architecture · Network topology · Security zones

Phase E

Opportunities & Solutions

Gap analysis · Work package register · Implementation options

Phase F

Migration Planning

3-horizon roadmap · Transition architectures · Dependency map

Phase G

Implementation Governance

Architecture contracts · Compliance reviews · Change requests

Continuous

Requirements Management

BR · AR · C from Page 02 — live throughout every phase

Preliminary Phase

Architecture Principles — the rules the design cannot break.

Twelve principles established before any architecture work begins. These are not aspirational guidelines — they are binding constraints on every design decision that follows. Any component that violates a principle requires a formal ADR documenting the exception and its consequences.

P-01

Explainability is engineered in, not added on

Every ML model is designed with its explanation contract before training begins. SHAP values are generated at inference time and written to the audit log before any downstream action executes. Post-hoc explanation is not acceptable.

ClaraVis constraint: EU AI Act Annex III · AR-01

P-02

Human oversight is a first-class state machine node

HITL checkpoints are formal states in every agent's state machine — with a defined entry condition, presentation contract, decision interface, timeout behaviour, and immutable audit record. Human oversight is designed, not assumed.

ClaraVis constraint: EU AI Act Art. 14 · AR-02

P-03

Compliance obligations are write-path constraints

Regulatory obligations — EU AI Act, FDA 21 CFR 820, ASC 606 — are encoded as constraints in the data model and enforced by the write path. Compliance is a structural property of every transaction, not a reporting posture applied retrospectively.

ClaraVis constraint: BR-02 · AR-08 · AR-09

P-04

The AS augments existing systems — it does not replace them

Salesforce and SAP remain systems of record. The AS is the orchestration and intelligence layer that operates across them. No design decision requires decommissioning or re-platforming an existing system. Integration is additive.

ClaraVis constraint: ADR-002 · C-06

P-05

Every significant architectural decision is documented

Architecture Decision Records are produced for every significant design choice — technology selection, integration pattern, data model decision. Each ADR states the decision, the alternatives considered, and the consequences. No undocumented decisions.

ClaraVis constraint: AR-10 · TOGAF ADM standard

P-06

Data sovereignty is enforced at the infrastructure layer

Data residency constraints are implemented as VPC-SC perimeter rules and Organisation Policy constraints provisioned via Terraform. They cannot be overridden by application configuration, network policy changes, or ad-hoc IAM grants.

ClaraVis constraint: GDPR · BR-06 · AR-06 · C-04

P-07

Every agent has a documented autonomy boundary

Each agent in the swarm has a formally specified set of actions it executes autonomously and a set that require human approval. The boundary is defined before implementation, expressed in the state machine specification, and enforced by the HITL checkpoint architecture.

ClaraVis constraint: EU AI Act Art. 14 · AR-02

P-08

Infrastructure is code — no manual provisioning

Every GCP resource is provisioned via Terraform. No manual console configuration is acceptable for production or demonstration environments. Infrastructure state is version-controlled, peer-reviewed, and reproducible from a single terraform apply command.

ClaraVis constraint: ISO 27001 · FDA change control

P-09

The event fabric is the integration bus

All cross-system events are published to Pub/Sub topics before downstream systems consume them. This decouples producers from consumers, enables event replay for audit purposes, and provides the foundation for the streaming ML feature pipeline. No direct system-to-system synchronous calls for data that can be event-driven.

ClaraVis constraint: AR-11 · BR-03

P-10

Model Cards are versioned artifacts, not documentation afterthoughts

Every ML model has a Model Card created before training begins and updated with actual evaluation results before promotion. Model Cards are version-controlled alongside the model in Vertex AI Model Registry and are required inputs to the HITL promotion checkpoint.

ClaraVis constraint: EU AI Act Art. 11 · AR-05

P-11

Security is zero-trust — no implicit network trust

All service-to-service authentication is via Workload Identity Federation. No service account key files. No network-based trust. BeyondCorp enforces identity verification at every access request regardless of network location. Secrets are managed exclusively through Secret Manager.

ClaraVis constraint: ISO 27001 · AR-07 · CISO requirement

P-12

Cost allocation is tagged from day one

Every GCP resource carries a module-level cost allocation label from the first terraform apply. FinOps visibility is not a Phase 2 concern — it is provisioned in the same Terraform run as the resource itself. Budget alerts are configured before any workload is deployed.

ClaraVis constraint: CFO requirement · C-01

Phase A

Architecture Vision

Output: Statement of Architecture Work

Architecture Vision Statement

To deliver a TOGAF-aligned, explainability-first enterprise AI architecture for ClaraVis that orchestrates the full Quote-to-Cash-to-Field-to-Compliance lifecycle — with human oversight engineered into every consequential decision — satisfying EU AI Act Annex III, FDA 21 CFR 820, and ISO 13485 simultaneously.

Statement of Architecture Work

Scope

All four AS modules across the Quote-to-Cash, asset management, revenue recognition, and compliance domains. Salesforce and SAP integration in scope. PHI processing out of scope.

Architecture Sponsor

CTO (S-01) — primary sign-off. CCO (S-02) — compliance co-sponsor. CFO (S-03) — financial outcomes sponsor.

Time Constraint

EU AI Act Annex III compliance for 3 existing models required before Q2 2026 regulatory review. Hard deadline driving Horizon 1 scope.

Architecture Vision — Stakeholder Influence Map

Influence weight and concern domain for all nine ClaraVis stakeholders

Phase B

Business Architecture

Output: To-Be Value Stream · Capability Model

The Business Architecture translates the Architecture Vision into a concrete model of how ClaraVis's commercial operations work after the AS is deployed. The As-Is value stream from Page 02 is the baseline. The To-Be below is the target — every manual handoff replaced by an agent-mediated state transition with a defined SLA and an audit record.

To-Be Quote-to-Cash Value Stream — AS Orchestrated

Agent-mediated state transitions · Defined SLAs · HITL checkpoints at risk thresholds · Immutable audit record at every transition

Salesforce-managed

AS Agent (autonomous)

HITL checkpoint (human required)

SAP-managed

Commercial

Quote-to-Cash

Opportunity · CPQ · Contract · Order · Revenue

Operational

Asset Management

Telemetry · RUL · Anomaly · Maintenance · DHR

Financial

Revenue & Risk

ASC 606 · IFRS 15 · Anomaly detection · FinRisk

Compliance

Governance & Audit

EU AI Act · ISO 13485 · HITL · XAI · Audit trail

Phase C

Information Systems Architecture

Output: Canonical Data Model · Application Portfolio · Integration Catalog

Phase C defines what data the enterprise needs to manage and what applications manage it. The canonical data model below is the single source of truth for how all eight AS modules share state. The ERD formalises the six shared entities — the proof that the AS is a coherent system, not a collection of applications. The application portfolio and integration catalog follow.

Phase C — Canonical Data Model ERD · Six Shared Entities

All eight AS modules reference at least two entities · Crow's-foot notation · PK / FK relationships shown

Contract — ContractGuard · RevRec

Transaction — RevRec AI · FinRisk

Device — Asset IQ · ISO 13485

Asset Event — Asset IQ · GreenOps

Agent Action — All modules (central audit entity)

HITL Event — All HITL checkpoints (immutable)

Application Portfolio — Data Ownership by System

Salesforce

Owns: Account, Opportunity, Quote, Contract object
Reads: Agent Action results, HITL outcomes

SAP S/4HANA

Owns: Transaction (GL), Logistics order
Reads: RevRec classification post-HITL approval

AS Agent Layer

Owns: Agent Action, HITL Event, SHAP output
Orchestrates: all cross-system flows

GCP Data Fabric

Owns: Device, Asset Event, ML features
Serves: all modules via BigQuery + Feature Store

Integration Catalog — Cross-System Data Flows

Integration Point	Direction	Protocol	Entity Exchanged	ADR / Constraint
Salesforce → AS	Inbound (event-driven)	REST API · Pub/Sub	Opportunity, Quote, Contract, Account	ADR-001 · AR-04
AS → Salesforce	Outbound (write-back)	REST API (PATCH)	Opportunity stage, Agent Action ref, HITL outcome	ADR-001 · AR-04
SAP → AS	Inbound (seeded)	BAPI/RFC via middleware (BTP)	GL document, logistics order, billing data	ADR-002 · C-03
AS → SAP	Outbound (post-HITL)	BAPI/RFC · middleware	Revenue posting, order confirmation · HITL record required first	ADR-002 · AR-08
Asset Systems → AS	Inbound (streaming)	Pub/Sub ingestion agent	DICOM service events, sensor readings, error codes	ADR-006 · AR-11
Document Store → AS	Inbound (batch upload)	GCS upload → Document AI	Contract documents → Gemini 1.5 Pro analysis	ADR-005 · BR-05

Phase D

Technology Architecture — GCP Reference.

Two diagrams. The concept overview establishes the four-layer model and the principal services. The full technical diagram shows every named GCP service, the VPC-SC perimeter, network topology, IAM boundaries, and data flow paths. This is the diagram that makes a Google Cloud architect stop and read.

Phase D — Concept: Four-Layer Architecture Overview

Principal services per layer · Data flow direction · HITL and XAI integration points

Layer 01 — Experience & Presentation

Layer 02 — Agent Orchestration

Layer 03 — MLOps & Intelligence

Layer 04 — Infrastructure & Governance

VPC-SC perimeter

Phase D — Full Technical: GCP Reference Architecture for ClaraVis

Every named GCP service · IAM boundaries · Network topology · Salesforce and SAP integration points · Data residency enforcement

Agent services (Cloud Run)

Data & ML (managed)

AI services (Vertex AI)

Infrastructure & security

VPC-SC boundary

External integration

Phase E

Opportunities & Solutions

Output: Gap Analysis · Work Package Register

Phase E identifies the gaps between As-Is and To-Be and translates them into work packages — the units of delivery that can be assigned to an Agile Release Train. Each work package has a defined scope, a set of requirements it satisfies, and an explicit dependency on predecessor work. Nothing in H2 starts until its H1 prerequisites are complete.

Gap Analysis — Current vs Target State

Capability Area	Current State (As-Is)	Target State (To-Be)	Horizon
ML Explainability	3 production models — no SHAP, no explanation contract, EU AI Act non-compliant	Every inference produces SHAP values written to audit log before downstream action. Model Cards versioned in Vertex AI Registry.	H1
HITL Architecture	Ad-hoc email/Slack approvals. No formal state machine, no timeout, no audit record of human decision.	HITL is a first-class state machine node in every agent. Named approver, presentation contract, decision interface, immutable Firestore record.	H1
Asset Telemetry	6 disconnected regional systems, no common schema, no cross-regional query capability.	Unified Pub/Sub ingestion pipeline, validated common schema, BigQuery dataset for fleet analytics, RUL model in production.	H1
Revenue Recognition	Manual ASC 606 classification by Finance team. 12-day month-end close. No ML-assisted recognition.	RevRec AI classifies each transaction with SHAP explanation, routes through Finance Controller HITL, posts to SAP automatically post-approval.	H2
Contract Intelligence	Contracts stored in on-premise DMS, not analysed. Legal review triggered manually, no precedent reference.	ContractGuard reads full contract via Gemini 1.5 Pro, scores every clause, routes non-standard terms to Legal HITL with precedents and draft counter-position.	H2
Q2C Orchestration	9 manual handoffs, no SLA, no end-to-end owner, no audit trail, 47-day average cycle.	Agent-mediated state machine with defined SLAs, immutable audit record at every transition, automated SAP write post-HITL approval. Target: ≤ 9 days.	H2
Executive Visibility	C-suite data requires manual pulls from Salesforce, SAP, and 6 regional systems. No unified view.	Strategy Dashboard unifies pipeline, fleet status, revenue posture, and compliance status in a single real-time BigQuery-backed view.	H3
Sales Agent	All inbound inquiries require immediate AS involvement. 3–5 day time-to-qualified-AE.	CCAI Sales Agent handles first 11 turns autonomously. Escalation to AE is a designed state transition with a full briefing document prepared by the agent.	H3

Work Package Register

WP-01 · Horizon 1

GCP Foundation & Security Baseline

DeliversTerraform-provisioned GCP project, VPC-SC perimeter, CMEK, IAM, Workload Identity, Secret Manager, Cloud Build CI/CD SatisfiesAR-06, AR-07, P-06, P-08, P-11, P-12, C-04 Depends onNone — this is the prerequisite for all other work packages ARTPlatform ART

WP-02 · Horizon 1

Data Fabric & Event Bus

DeliversBigQuery datasets (audit, features, ml), Pub/Sub topics (asset-events, q2c-events, hitl-events), Vertex AI Feature Store, schema validation pipeline SatisfiesAR-11, P-09, BR-03 (partial), AR-03 Depends onWP-01 — GCP Foundation must be provisioned first ARTPlatform ART

WP-03 · Horizon 1

HITL Framework & XAI Layer

DeliversFirestore-backed HITL state machine, SHAP explanation pipeline, Model Cards for 3 existing models, HITL Approval UI, XAI Explanation Viewer SatisfiesAR-01, AR-02, AR-03, AR-05, BR-02, P-01, P-02, P-10 Depends onWP-01, WP-02 — state machine writes to Firestore; SHAP writes to BigQuery audit dataset ARTPlatform ART

WP-04 · Horizon 1

Salesforce Integration & Asset Telemetry Ingestion

DeliversSalesforce Developer Edition REST API integration (ADR-001), unified Pub/Sub asset telemetry ingestion agent, schema validation for 6 regional systems SatisfiesAR-04, AR-11, BR-03, C-02, ADR-001 Depends onWP-02 — Pub/Sub topics must exist before ingestion agent can publish ARTCommercial ART + Operations ART

WP-05 · Horizon 2

ContractGuard & RevRec AI Modules

DeliversContractGuard agent (ADK, Cloud Run), clause scoring model, Legal HITL integration; RevRec AI agent, ASC 606 classification model, Finance HITL integration, SAP write post-approval SatisfiesBR-04, BR-05, AR-08, AR-02, AR-01, EU AI Act Annex III Depends onWP-03 — HITL framework and XAI layer must be live before module deployment ARTCommercial ART + Financial ART

WP-06 · Horizon 2

Asset IQ & FinRisk Sentinel

DeliversAsset IQ RUL model + anomaly detection, fleet-level SHAP attribution, FSM HITL integration; FinRisk Sentinel streaming anomaly detection, CFO HITL integration SatisfiesBR-03, AR-01, AR-02, EU AI Act Annex III, ISO 13485 Depends onWP-03, WP-04 — unified telemetry and HITL framework both required ARTOperations ART + Financial ART

WP-07 · Horizon 2

MLOps Infrastructure

DeliversVertex AI Pipelines for all new models, Model Registry integration, drift detection monitoring jobs, automated retraining trigger + ML Engineer HITL, Model Card versioning workflow SatisfiesAR-05, AR-12, P-10, EU AI Act Art. 9 Depends onWP-02, WP-03 — Feature Store and Model Registry in WP-02; HITL framework in WP-03 ARTPlatform ART

WP-08 · Horizon 3

CCAI Sales Agent, GreenOps & Strategy Dashboard

DeliversCCAI Sales Agent full ADK deployment, turn-11 HITL escalation; GreenOps carbon-aware scheduling + CSRD reporting; Strategy Dashboard BigQuery-backed C-suite view; cross-module shared feature pipelines SatisfiesBR-07, BR-08, EU CSRD, C-07 (SAFe alignment) Depends onWP-04, WP-05, WP-06, WP-07 — all core modules and MLOps infrastructure must be live ARTCommercial ART + Operations ART + Platform ART

Phase F

Migration Planning

Output: 3-Horizon Roadmap · Transition Architectures · Dependency Map

Phase F sequences the work packages into a migration roadmap. The three transition architecture snapshots below show the state of the ClaraVis enterprise at the end of each horizon — what is live, what the compliance posture is, and what remains. The dependency map makes the sequencing constraints explicit.

Migration Roadmap — Three Horizons

Horizon 1

Months 1–3

Foundation & Compliance

WP-01: GCP project provisioning — Terraform, VPC-SC, IAM, CMEK

WP-02: BigQuery data fabric + Pub/Sub event bus

WP-03: HITL framework — state machine + Firestore audit store + XAI layer

WP-03: SHAP integration on all 3 existing production models

WP-03: Model Cards for 3 existing models — EU AI Act Annex III deadline

WP-04: Salesforce Developer Edition integration (ADR-001)

WP-04: Unified asset telemetry ingestion pipeline

Horizon 2

Months 4–8

Core Module Deployment

WP-05: ContractGuard — clause scoring + Legal HITL

WP-05: RevRec AI — ASC 606 classification + Finance HITL

WP-06: Asset IQ — RUL model + anomaly detection

WP-06: FinRisk Sentinel — real-time anomaly monitoring

WP-07: Vertex AI Pipelines — MLOps for all new models

WP-07: Drift detection + automated retraining triggers

App dashboards for all deployed modules

Horizon 3

Months 9–18

Full AS Suite & Optimisation

WP-08: CCAI Sales Agent — full ADK deployment

WP-08: GreenOps Platform — carbon-aware scheduling

WP-08: Strategy Dashboard — C-suite unified view

WP-08: Cross-module shared feature pipelines

SAP integration productionisation (BTP)

EU AI Act full compliance certification readiness

Transition Architecture Snapshots

End of Horizon 1 · Month 3

Foundation State

GCP InfraLive VPC-SC, CMEK, IAM, Terraform baseline

Data fabricLive BigQuery + Pub/Sub event bus operational

HITL / XAILive State machine + SHAP on all 3 existing models

SalesforceLive REST API integration operational

Asset telemetryLive 6 systems unified into Pub/Sub

EU AI ActPartial Existing models compliant; new models pending

AS modules live0 of 8 — foundation only

End of Horizon 2 · Month 8

Core Capability State

GCP InfraLive All H1 foundation stable

ContractGuardLive Clause scoring + Legal HITL active

RevRec AILive ASC 606 classification + Finance HITL

Asset IQLive RUL predictions active across 12,000 units

FinRisk SentinelLive Streaming anomaly detection operational

MLOpsLive Vertex AI Pipelines + drift detection

EU AI ActLive All deployed models Annex III compliant

AS modules live4 of 8 — core commercial + financial

End of Horizon 3 · Month 18

Full AS Suite State

CCAI AgentLive Full ADK deployment, turn-11 HITL active

GreenOpsLive Carbon-aware scheduling + CSRD reporting

Strategy DashLive C-suite unified BigQuery-backed view

SAP integrationLive BTP Event Mesh productionised

Q2C cycleTarget: ≤ 9 days (from 47 days As-Is)

EU AI ActLive Full certification readiness — all modules

AS modules live8 of 8 — full suite operational

Work Package Dependency Map

Sequencing constraints — what unlocks what

WP-01 · GCP Foundation

→

WP-02 · Data Fabric

WP-03 · HITL + XAI

WP-04 · Salesforce + Telemetry

WP-02 · Data Fabric

→

WP-03 · HITL + XAI (Firestore + BigQuery)

WP-04 · Pub/Sub topics required

WP-07 · MLOps (Feature Store)

WP-03 · HITL + XAI

→

WP-05 · ContractGuard + RevRec AI

WP-06 · Asset IQ + FinRisk

WP-04 · SFDC + Telemetry

→

WP-05 · ContractGuard (SFDC contract events)

WP-06 · Asset IQ (telemetry pipeline)

WP-05 + WP-06 + WP-07

→

WP-08 · CCAI Agent + GreenOps + Dashboard (all core modules must be live)

Requirements Management

Every requirement traced to a phase and artifact.

Requirements Management is continuous throughout the ADM. The matrix below shows how every requirement from Page 02 is satisfied by a specific phase, artifact, and AS module. No requirement is unaddressed. No phase produces an artifact that cannot be traced back to a requirement.

Req ID	Requirement (summary)	ADM Phase	Artifact	AS Module / Component
BR-01	Q2C cycle orchestration with SLAs	Phase B	To-Be Value Stream	CCAI Agent · ContractGuard · RevRec AI · Orchestrator
BR-02	EU AI Act compliance — 3 models	Phase D	XAI Layer · HITL Framework	RevRec AI · Asset IQ · ContractGuard · Vertex AI
BR-03	Unified asset telemetry + predictive maintenance	Phase C/D	Data Model · GCP Architecture	Asset IQ · Pub/Sub · BigQuery · Vertex AI
BR-04	ASC 606 revenue recognition automation	Phase B/D	Value Stream · Data Model	RevRec AI · Finance HITL · SAP integration
BR-05	Contract clause intelligence + risk scoring	Phase B/D	Value Stream · GCP Arch.	ContractGuard · Document AI · Gemini 1.5 Pro
BR-06	Data sovereignty — no data leaves EU	Phase D	GCP Reference Arch.	VPC-SC · CMEK · Organisation Policy · Terraform
BR-07	CCAI Sales Agent — autonomous qualification	Phase B/E	Value Stream · WP-08	CCAI Sales Agent · ADK · Salesforce integration
BR-08	Executive strategy dashboard	Phase B/E	Capability Model · WP-08	Strategy Dashboard · BigQuery · all modules
AR-01	SHAP explanation per ML inference	Phase D	XAI Layer design	SHAP layer · BigQuery audit · all ML modules
AR-02	HITL as formal state machine node	Prelim + D	P-02 principle · HITL spec	Firestore state machine · all agent modules
AR-03	Immutable audit trail for all agent actions	Phase C/D	Data Model · Firestore	Agent Action entity · Firestore · BigQuery
AR-04	Salesforce as system of record	Prelim	ADR-001 · ADR-002	SFDC REST API · Developer Edition
AR-05	Model Cards for every ML model	Phase D/E	WP-03 · WP-07 · Model Registry	Vertex AI Model Registry · all ML models
AR-06	VPC-SC for data sovereignty	Phase D	GCP Reference Arch.	VPC-SC · Terraform Organisation Policy
AR-07	CMEK encryption — ClaraVis key custody	Phase D	GCP Reference Arch. · WP-01	Cloud KMS · CMEK on all storage services
AR-08	ASC 606 as write-path constraints	Phase C	Data Model · Transaction entity	RevRec AI · Transaction entity · BigQuery
AR-09	Device History Record atomic write	Phase C/D	Data Model · Device entity	Device entity · Pub/Sub · BigQuery · SAP integration
AR-10	ADR documentation for every significant decision	All phases	ADR-001 through ADR-006	All components — ADR index maintained in repo
AR-11	Pub/Sub event fabric as integration bus	Phase C/D	Integration Catalog · WP-02	Cloud Pub/Sub · all cross-system events
AR-12	Drift detection + automated retraining trigger	Phase D/E	WP-07 · Vertex AI monitoring	Vertex AI Model Monitoring · HITL-10 · retraining pipeline
C-01	Zero additional licensing cost	Prelim	P-12 · ADR-001	Free tier · SFDC Dev Edition · GCP credits
C-02	Salesforce Developer Edition integration pattern	Prelim	ADR-001 · WP-04	SFDC REST API · Developer Edition · standard objects only
C-03	SAP integration via middleware abstraction	Phase D	ADR-002 · GCP Architecture	BAPI/RFC middleware abstraction · BigQuery mock for demo
C-04	EU data residency — europe-west3	Phase D	GCP Reference Arch.	Terraform region var · Org Policy constraint
C-05	MVP-plus build standard	Phase E/F	Work Package register · H1–H3 scope	H1–H3 scope definition · demo pathways
C-06	Existing Salesforce and SAP preserved	Prelim	ADR-002 · P-04	AS augments — no decommissioning of SFDC or SAP
C-07	SAFe delivery governance — light touch	Phase E/F	Work Package register · ART mapping	WP-01 through WP-08 mapped to ARTs · Page 04 SAFe detail

Architecture Decision Records

Six decisions. Every alternative documented.

ADR-001 and ADR-002 were established in Phase A. ADR-003 through ADR-006 are produced in Phase D. Every ADR states the decision, the alternatives considered, the alternatives rejected and why, and the consequences — the pattern Google and major engineering organisations use to make architecture reasoning persistent.

ADR-001 · Phase A

Salesforce Developer Edition — REST API integration

Decision

Salesforce Developer Edition REST API is the integration pattern for all Salesforce-to-AS data flows. Live API makes Q2C domain depth observable in demos. Developer Edition is free and permanent.

Alternatives rejected

BigQuery Data Transfer rejected — no real-time event capability; CSV export rejected — no bidirectional write-back; Google Sheets mock rejected — cannot demonstrate actual Salesforce data model depth; Salesforce SOAP API rejected — deprecated for new integrations; MuleSoft rejected — C-01 cost constraint violated.

Consequences

Standard objects only (Opportunity, Account, Quote, Contract). No paid AppExchange connectors. Integration is demonstrable and reproducible on a free org.

Accepted · Phase A

ADR-002 · Phase A

GCP alongside Salesforce — augmentation, not replacement

Decision

AS addresses five domains outside Einstein's structural boundary. Salesforce remains system of record. Integration is additive. No existing system is decommissioned.

Alternatives rejected

Full Salesforce Einstein expansion rejected — structurally unable to satisfy EU AI Act Annex III (no SHAP exposure, proprietary model internals); SAP BTP as orchestration layer rejected — no ML explainability capability at required depth; single-vendor strategy rejected — no single vendor spans SFDC + SAP + IoT + EU AI Act compliance simultaneously.

Consequences

Requires maintained integration with two external systems. AS has no single system of record — it is the orchestration layer across them. ADR-001 defines the Salesforce integration pattern.

Accepted · Phase A

ADR-003 · Phase D

Cloud Run over GKE for stateless agent services

Decision

Stateless agent invocations (ContractGuard, RevRec AI) deploy to Cloud Run. Only batch ML workloads use GKE Autopilot. Cloud Run scales to zero, reducing costs and operational complexity at demo scale.

Alternatives rejected

GKE for all services rejected — operational overhead disproportionate for stateless per-request agents; C-01 cost constraint makes always-on node pools unacceptable for demo scale; Cloud Functions rejected — 9MB payload limit and 60-second timeout too restrictive for contract analysis workloads.

Consequences

Cold start latency on first request (typically <2s). Batch ML training still uses GKE Autopilot for GPU access. Production would add min-instances=1 to eliminate cold starts on SLA-critical agents.

Accepted · Phase D

ADR-004 · Phase D

Firestore for agent state and HITL audit — not Spanner

Decision

Firestore selected for agent state machine and HITL audit store. Document model maps naturally to agent state and HITL event schemas. Cost at demo scale is negligible.

Alternatives rejected

Cloud Spanner rejected — global distribution and 5-nines SLA are not required for a single EU region deployment; Spanner's relational model adds schema rigidity that doesn't match the variable HITL event payload; cost significantly higher at demo scale. BigQuery rejected for agent state — no low-latency point reads; OLAP store not appropriate for transactional agent state.

Consequences

HITL event records are immutable by Firestore security rules — no application-level update path. If global distribution or strong ACID across regions is needed in production, Spanner would replace Firestore for audit storage.

Accepted · Phase D

ADR-005 · Phase D

SHAP over LIME for the XAI explanation layer

Decision

SHAP provides consistent, theoretically grounded (Shapley values) feature attribution across tree-based and linear models. SHAP values are deterministic given a fixed model and input.

Alternatives rejected

LIME rejected — local approximations introduce stochasticity on repeated calls; an immutable audit record requires deterministic explanation values. Integrated Gradients rejected — gradient-based methods are appropriate for deep neural networks but the AS uses tree-based and linear models where SHAP TreeExplainer/LinearExplainer are both faster and exact. Proprietary explanation tools (Einstein, Vertex AI Explainability API only) rejected — operator transparency required by EU AI Act Art. 13 mandates open, auditable explanation method.

Consequences

SHAP computation adds latency at inference time (typically 50–200ms). Accepted tradeoff — EU AI Act compliance is not optional. SHAP values are written to BigQuery before any downstream action commits.

Accepted · Phase D

ADR-006 · Phase D

Pub/Sub as the integration event bus — not direct API calls

Decision

All cross-system events publish to Pub/Sub before consumption. Decouples producers from consumers, enables at-least-once delivery, and provides the event stream for the streaming ML feature pipeline.

Alternatives rejected

Direct synchronous Salesforce-to-SAP calls rejected — tight coupling and no event replay for audit purposes; a single system failure cascades across the full Q2C flow. Eventarc rejected — insufficient control over retry semantics and dead-letter queue configuration for regulated workloads. Cloud Tasks rejected — no persistent event log for audit replay; tasks are consumed and discarded.

Consequences

At-least-once delivery requires idempotent consumers. All event handlers must be idempotent by design. The event bus introduces eventual consistency — accepted because immutable Firestore records provide the single source of truth for decision state.

Accepted · Phase D