proxmox/hybx_compliance_routing_sidecar_technical_plan.md

HYBX Compliance & Routing Sidecar — Technical Plan

Purpose

Design a dedicated Compliance and Routing Sidecar that integrates with the Transaction Composer engine to evaluate regulatory constraints, liquidity routing, fee paths, and settlement feasibility before execution.

The sidecar acts as a decision intelligence layer, ensuring that all designed transactions are compliant, optimally routed, and operationally executable.

Implementation tracking (2026-03-30)

Ship work is tracked as P1-E02 in docs/00-meta/TODOS_CONSOLIDATED.md (with the jurisdictional cheat sheets plan). This document is design/spec only.

---

Core Concept

The Compliance & Routing Sidecar functions as:

1. Policy Engine
2. Compliance Validator
3. Routing Optimizer
4. Liquidity Resolver
5. Fee Path Generator
6. Risk Decision Engine

It operates alongside the orchestration engine but does not execute transactions.

It evaluates and returns decisions, recommendations, and constraints.

---

High-Level Architecture

Primary Engines

The sidecar consists of six major subsystems:

1. Policy Engine
2. Compliance Engine
3. Routing Engine
4. Liquidity Engine
5. Fee Engine
6. Risk Engine

Each subsystem runs independently but communicates via shared context.

---

Integration Model

Deployment Pattern

Sidecar runs adjacent to orchestration engine.

Architecture Pattern:

Composer UI → Orchestration Engine → Sidecar → Decision Response

Not:

Composer UI → Execution

Execution is blocked until sidecar approval.

---

Core Responsibilities

1 — Validate Transaction Design

Evaluate:

• Entity eligibility
• Jurisdiction constraints
• Currency permissions
• Cross-border restrictions
• Liquidity availability
• Fee compliance

Return:

PASS WARN FAIL

---

2 — Generate Routing Paths

Determine optimal route across:

• Correspondent banks
• Nostro/Vostro accounts
• Settlement rails
• Liquidity partners

Routing considers:

• Latency
• Liquidity availability
• Regulatory constraints
• Fee efficiency

---

3 — Enforce Regulatory Constraints

Validate compliance against:

• AML rules
• KYC requirements
• Sanctions lists
• FX regulations
• Settlement permissions

---

4 — Compute Liquidity Strategy

Determine:

• Liquidity source
• FX conversion path
• Net settlement amount

---

5 — Build Fee Distribution Logic

Construct:

• Fee tiers
• Fee sequence
• Net disbursement schedule

---

6 — Assess Risk

Calculate:

• Transaction exposure
• Counterparty risk
• Settlement risk

---

Core Data Flow

Transaction → Sidecar → Decision Graph → Orchestrator

Sidecar returns:

• Decision Status
• Route Plan
• Liquidity Plan
• Fee Plan
• Risk Score

---

API Design

Core Endpoint

POST /evaluate-transaction

Request:

{ transactionGraph, participants, accounts, liquidity, fees }

Response:

{ status, routingPlan, liquidityPlan, feePlan, complianceResults, riskScore }

---

Policy Engine Design

Role

Policy engine defines regulatory logic.

Policies stored as rule sets.

---

Policy Types

Jurisdiction Policies

Examples:

• Allowed currency pairs
• Cross-border transfer limits

---

Institution Policies

Examples:

• Settlement permissions
• Nostro relationship validity

---

Transaction Policies

Examples:

• Maximum transfer size
• Required approvals

---

Compliance Engine Design

Function

Validates all nodes and edges in transaction graph.

Checks include:

• AML
• Sanctions
• FX permissions
• Participant eligibility

---

Routing Engine Design

Routing Model

Graph-based pathfinding.

Uses:

Weighted directed graph.

Weights include:

• Fee cost
• Latency
• Liquidity availability

Algorithm:

Multi-criteria shortest path.

---

Transaction Composer Mapping

Role of transaction-composer/

The package at transaction-composer/ should be treated as the operator and developer-facing UI/control surface for the Compliance & Routing Sidecar, not as a separate orchestration product.

The intended relationship is:

Transaction Composer UI → Orchestration API → Compliance & Routing Sidecar → Decision Output → Approved Execution Plan

The composer is responsible for:

• designing transaction topology
• capturing user intent
• validating graph structure
• previewing compliance and routing outcomes
• running dry-run simulation
• exporting graph and compiled transaction payloads

The sidecar is responsible for:

• policy evaluation
• jurisdiction checks
• route generation
• liquidity resolution
• fee planning
• risk scoring
• final decision output

The composer does not replace the sidecar. The sidecar does not replace the composer. Together they form the design-time and pre-execution decision layer.

Current Composer Capabilities Already Aligned

The current transaction-composer/ MVP already provides the correct surface for several sidecar inputs:

• typed transaction graph with financial node kinds
• graph edge validation
• transaction compilation into structured payloads
• compliance pre-checks
• dry-run simulation
• AI-assisted graph creation from natural-language prompts
• project save/load and JSON export

This means the composer can already act as:

• graph authoring client
• transaction payload builder
• initial validation client
• operator review console

Functional Mapping: Composer → Sidecar

Composer capability	Current package location	Sidecar responsibility it should feed
Node type system	transaction-composer/src/types/nodeTypes.ts	Canonical transaction graph schema consumed by sidecar
Edge validation	transaction-composer/src/graph/validateConnection.ts	Structural pre-validation before policy/routing evaluation
Transaction compiler	transaction-composer/src/orchestration/transactionCompiler.ts	Normalized request body for /evaluate-transaction
Local compliance checks	transaction-composer/src/compliance/complianceEngine.ts	Fast UI pre-check before full sidecar decision pass
Dry-run simulation	transaction-composer/src/orchestration/dryRunEngine.ts	Operator preview before execution approval
JSON export	transaction-composer/src/export/exportTransaction.ts	Offline review / audit / handoff artifact
AI prompt interpreter	transaction-composer/src/ai/promptInterpreter.ts	Rapid route drafting before formal sidecar evaluation
Action bar / state machine	transaction-composer/src/components/BottomExecutionBar.tsx, transaction-composer/src/state/transactionMachine.ts	User workflow for build → evaluate → simulate → approve

Required Sidecar API Alignment

The composer should become the primary client of the sidecar endpoint:

POST /evaluate-transaction

Recommended request model:

{
  "graph": {
    "nodes": [],
    "edges": []
  },
  "compiledTransaction": {},
  "context": {
    "jurisdictions": [],
    "participants": [],
    "operator": {},
    "executionMode": "dry-run"
  }
}

Recommended response model:

{
  "status": "PASS",
  "routingPlan": {},
  "liquidityPlan": {},
  "feePlan": {},
  "complianceResults": [],
  "riskScore": 0,
  "warnings": [],
  "blockingIssues": []
}

The local complianceEngine.ts should remain as a fast client-side validation layer, while the sidecar becomes the authoritative server-side evaluator.

UI-to-Sidecar Screen Mapping

1. Left Component Palette

Maps to:

• canonical transaction grammar
• supported route primitives
• institution and settlement building blocks

2. Center Graph Canvas

Maps to:

• transaction topology authoring
• route visualization
• structural review before evaluation

3. Right AI Chat Panel

Maps to:

• prompt-to-graph generation
• future policy explanations
• route recommendation explanations
• jurisdictional warnings returned by sidecar

4. Bottom Execution Bar

Maps to:

• Build → local compile
• Validate → local pre-check plus sidecar evaluation
• Dry Run → local simulation plus optional sidecar route simulation
• Execute → only after sidecar approval and orchestration confirmation

Orchestrator Boundary

The composer should call an orchestration API, not external rails directly.

Recommended control sequence:

1. Composer builds graph.
2. Composer compiles transaction.
3. Composer sends evaluation request to Compliance & Routing Sidecar.
4. Sidecar queries:
   • jurisdictional cheat sheets
   • institution policy registry
   • liquidity adapters
   • fee rules
   • risk engines
5. Sidecar returns decision package.
6. Composer renders:
   • PASS / WARN / FAIL
   • route recommendation
   • liquidity strategy
   • fee path
   • risk notes
7. Orchestrator receives approved decision package for execution.

Jurisdictional Cheat Sheet Integration

The sidecar should not hardcode jurisdiction rules.

Instead:

• composer submits transaction context
• sidecar resolves all participating jurisdictions
• sidecar queries the Jurisdictional Intelligence System
• returned jurisdiction constraints become part of the decision package

That means hybx_jurisdictional_cheat_sheets_technical_plan.md is a direct dependency of this sidecar and should be treated as its policy-knowledge backend.

Recommended Immediate Integration Tasks

1. Add a new composer-side API client for POST /evaluate-transaction.
2. Add a sidecar decision panel in the composer UI for:
   • decision status
   • routing plan
   • liquidity plan
   • fee plan
   • risk score
3. Split local validation into:
   • local graph validation
   • authoritative sidecar evaluation
4. Freeze a single canonical request/response schema between composer and sidecar.
5. Add sidecar-backed node and edge annotations so returned warnings/errors paint directly onto the graph.
6. Extend the AI panel so it can also explain sidecar findings, not just create graphs.

Production Architecture Decision

transaction-composer/ should be recognized as:

• the design studio
• the operator console
• the pre-execution validation client

The Compliance & Routing Sidecar should be recognized as:

• the authoritative policy and routing decision service

This mapping allows the broader DBIS/HYBX stack to answer questions about:

• whether a route is legal
• whether liquidity is sufficient
• whether fees are valid
• whether settlement is feasible
• which path should be chosen before execution

---

Liquidity Engine Design

Responsibilities

Determine liquidity sources.

Resolve:

• FX path
• Liquidity pool selection

---

Liquidity Model

Liquidity stored as pools.

Each pool includes:

{ currency, amount, provider, expiry }

---

Fee Engine Design

Responsibilities

Build complete fee map.

Includes:

• Fee percentage
• Flat fees
• Conditional fees

---

Risk Engine Design

Risk Factors

• Counterparty reliability
• Currency volatility
• Liquidity exposure

Output:

Risk Score: 0–100

---

Decision Output Model

Sidecar produces a Decision Graph.

Structure:

{ complianceStatus, routingGraph, liquidityGraph, feeGraph, riskProfile }

---

Routing Intelligence Model

Routing is dynamic.

Supports:

• Multi-hop routing
• Failover paths
• Parallel routing

---

Execution Blocking Logic

Execution permitted only if:

Compliance PASS Risk acceptable Liquidity available

---

Sidecar Communication Protocol

Transport Options:

Preferred:

• gRPC

Alternative:

• REST

---

State Management Model

Each transaction tracked through lifecycle.

States:

Draft Validated Routed Approved Ready Executed Failed

---

Storage Architecture

Databases

Primary:

PostgreSQL

Secondary:

Redis (cache)

Optional:

Graph Database (Neo4j)

---

Decision Caching Model

Cache previous routing decisions.

Speeds repeated transactions.

Cache Key:

Transaction Signature Hash

---

Policy Storage Model

Policies stored as structured JSON.

Supports:

Versioning Rollback Audit

---

Compliance Logging

Every validation logged.

Includes:

Timestamp Policy Version Result

---

Observability Architecture

Metrics captured:

• Decision latency
• Compliance failures
• Routing complexity

---

Monitoring Tools

Recommended:

Prometheus Grafana OpenTelemetry

---

Performance Targets

Validation latency target:

< 200 ms

Routing latency target:

< 500 ms

---

Horizontal Scaling Model

Sidecar must scale independently.

Scaling method:

Container-based horizontal scaling.

---

Container Architecture

Each subsystem deployable independently.

Services:

policy-service compliance-service routing-service liquidity-service fee-service risk-service

---

Event Model

Sidecar reacts to events.

Events:

TransactionCreated TransactionUpdated TransactionValidated TransactionApproved

---

Failure Handling Model

Failures categorized as:

Soft Fail Hard Fail Retryable Fail

---

Security Architecture

Authentication:

mTLS

Authorization:

RBAC

---

Audit Model

Full audit trail required.

Tracks:

All policy decisions All routing changes All risk evaluations

---

Decision Transparency Model

Every decision must be explainable.

Outputs include:

Rule triggered Reason Outcome

---

AI Integration Capability

Sidecar optionally supports AI-based recommendations.

Use cases:

Suggest routing optimizations Suggest liquidity paths Flag anomalous patterns

---

Future Extensions

Planned capabilities:

Adaptive routing Dynamic policy learning Real-time liquidity discovery Predictive compliance risk scoring

---

Minimum Viable Sidecar Components

Required for MVP:

Policy Engine Compliance Engine Routing Engine Liquidity Engine Risk Engine Decision API

---

Production Readiness Milestones

Phase 1:

Basic compliance validation.

Phase 2:

Routing logic integration.

Phase 3:

Liquidity optimization.

Phase 4:

Full decision intelligence.

---

Final Outcome

When complete, the Compliance & Routing Sidecar becomes:

A deterministic decision engine that transforms transaction designs into validated, routable, executable workflows with full regulatory assurance.