835 lines
14 KiB
Markdown
835 lines
14 KiB
Markdown
# 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.
|
||
|
||
---
|
||
|
||
# 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:
|
||
|
||
```json
|
||
{
|
||
"graph": {
|
||
"nodes": [],
|
||
"edges": []
|
||
},
|
||
"compiledTransaction": {},
|
||
"context": {
|
||
"jurisdictions": [],
|
||
"participants": [],
|
||
"operator": {},
|
||
"executionMode": "dry-run"
|
||
}
|
||
}
|
||
```
|
||
|
||
Recommended response model:
|
||
|
||
```json
|
||
{
|
||
"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.
|