proxmox/hybx_jurisdictional_cheat_sheets_technical_plan.md

HYBX Jurisdictional Cheat Sheets — Technical Plan

Purpose

Design a comprehensive Jurisdictional Intelligence System (JIS) that functions as the financial equivalent of a global intelligence reference, similar in concept to the CIA World Factbook but specialized for banking, payments, liquidity movement, settlement routing, and regulatory execution.

This system provides deterministic jurisdiction knowledge used by the Compliance & Routing Sidecar to ensure that every transaction is legally executable within applicable jurisdictions.

Implementation tracking (2026-03-30)

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

---

Core Objective

Create a structured, versioned, queryable Book of Jurisdictional Cheat Sheets covering every jurisdiction where financial activity may occur.

Each jurisdiction profile must provide:

• Regulatory constraints
• Currency permissions
• Settlement rules
• Liquidity restrictions
• Licensing requirements
• Cross-border permissions
• Fee constraints
• Compliance requirements

This becomes the ground truth registry for jurisdictional logic.

---

Core Concept

The Jurisdictional Cheat Sheets system acts as:

1. Jurisdiction Knowledge Base
2. Compliance Reference Library
3. Routing Constraint Source
4. FX Permission Authority
5. Settlement Legality Validator
6. Institutional Licensing Reference

---

System Role in Overall Architecture

Primary Consumers:

• Compliance Sidecar
• Routing Engine
• Liquidity Engine
• Transaction Composer
• Risk Engine

Integration Flow:

Transaction Graph → Sidecar → Jurisdiction Lookup → Decision Output

Mapping to transaction-composer/

transaction-composer/ should be treated as the human-facing authoring client for jurisdiction-aware transaction design.

The practical flow is:

1. Composer generates the transaction graph.
2. Composer compiles the graph into a normalized transaction request.
3. Compliance & Routing Sidecar resolves the relevant jurisdictions.
4. Jurisdictional Cheat Sheets return:
   • currency permissions
   • cross-border restrictions
   • licensing requirements
   • settlement legality
   • reporting thresholds
5. Sidecar returns the decision package back to the composer UI for operator review.

This means the cheat-sheet system is not a standalone reporting tool only. It is an online policy backend for the sidecar and a visible explanation source for the composer.

---

System Architecture Overview

Primary Subsystems

1. Jurisdiction Registry
2. Policy Knowledge Base
3. Currency Rules Engine
4. Licensing Database
5. Cross-Border Rule Engine
6. Reporting and Visualization Layer

---

Jurisdiction Registry Design

Purpose

Maintain canonical jurisdiction definitions.

Each jurisdiction receives a Jurisdiction ID.

---

Core Fields

Each jurisdiction record includes:

Jurisdiction ID Country Name ISO Country Code Region Capital City Primary Financial Regulator Secondary Regulators Legal System Type Central Bank Name Currency Time Zones Languages Political Risk Tier Financial Risk Tier Sanctions Status

---

Regulatory Metadata Layer

Purpose

Capture jurisdiction-specific financial regulations.

---

Regulatory Categories

Banking Regulations

Fields:

Bank Licensing Requirements Minimum Capital Requirements Reserve Requirements Reporting Requirements Audit Requirements

---

Payments Regulations

Fields:

Allowed Payment Types Domestic Settlement Systems Real-Time Gross Settlement Availability Instant Payment Availability Payment Network Participation

---

FX Regulations

Fields:

FX Convertibility Status Allowed Currency Pairs Capital Controls FX Approval Requirements Maximum FX Limits

---

Cross-Border Regulations

Fields:

Outbound Transfer Permissions Inbound Transfer Permissions Restricted Jurisdictions Reporting Thresholds Documentation Requirements

---

Currency Rules Engine

Purpose

Define currency behavior within jurisdiction.

---

Currency Model

Currency Code Convertibility Level Settlement Type Liquidity Availability Central Bank Restrictions Digital Currency Support

---

Licensing Database Design

Purpose

Track institutional permissions.

---

License Types

Commercial Bank License Remittance License Money Services License Broker License Liquidity Provider License

---

License Fields

License ID License Type Issuing Authority Validity Period Operational Scope Restrictions

---

Cross-Border Rule Engine

Purpose

Define international transaction permissions.

---

Rule Types

Country-to-Country Transfer Rules Currency Export Rules Sanctions Restrictions Dual-Control Requirements Capital Flow Restrictions

---

Settlement Infrastructure Registry

Purpose

Catalog financial settlement systems.

---

Settlement System Fields

System Name Settlement Type Operating Hours Supported Currencies Settlement Finality Model Participation Requirements

Examples:

RTGS ACH Instant Payment Systems Cross-border Clearing Networks

---

Liquidity Infrastructure Registry

Purpose

Identify available liquidity channels.

---

Liquidity Fields

Liquidity Providers Supported Currency Pools Liquidity Windows Collateral Requirements Liquidity Limits

---

Fee Governance Model

Purpose

Define jurisdictional fee constraints.

---

Fee Fields

Maximum Allowed Fees Regulated Fee Categories Mandatory Fee Disclosures Taxation Rules Stamp Duty Rules

---

Risk Intelligence Layer

Purpose

Provide jurisdictional risk indicators.

---

Risk Indicators

Political Stability Index Regulatory Stability Index Financial Crime Risk AML Risk Tier Sanctions Risk Tier Currency Volatility Index

---

Sanctions Intelligence Module

Purpose

Track restricted jurisdictions.

---

Sanctions Fields

Sanctioning Authority Sanctions Type Restricted Activities Blocked Entities Sector Restrictions

---

Documentation Requirements Engine

Purpose

Define required transaction documentation.

---

Documentation Types

Customer Identification Beneficiary Documentation Source of Funds Declaration Purpose of Payment Regulatory Filings

---

Data Model Design

Core Structure

Each jurisdiction stored as structured object.

Example:

{ jurisdictionId, regulator, currencyRules, fxRules, settlementSystems, licensingRules, crossBorderRules, riskProfile }

---

Versioning Architecture

Every jurisdiction profile is versioned.

Supports:

Historical snapshots Policy rollback Audit tracking

---

Update Model

Updates triggered by:

Regulatory change Policy update Market changes

---

Data Acquisition Model

Sources include:

Official regulatory publications Central bank releases Financial supervisory authorities International financial organizations Licensed legal intelligence providers

---

Data Normalization Layer

Normalize all incoming jurisdiction data.

Ensure consistent schema alignment.

---

Validation Model

Each jurisdiction profile must pass validation checks.

Checks include:

Field completeness Logical consistency Policy compatibility

---

Query Interface Design

Provide high-speed lookup capability.

Example Queries:

Get FX permissions for USD → IDR Check cross-border transfer legality Retrieve settlement options Fetch licensing requirements

---

API Architecture

Primary Endpoint:

GET /jurisdiction/{id}

Returns full jurisdiction profile.

---

Search Capability

Enable multi-dimensional search.

Search filters:

Country Currency Regulator Risk Tier Settlement Availability

---

Integration with Sidecar

Sidecar queries jurisdiction data during validation.

Used for:

Routing validation Compliance validation Liquidity validation

---

Caching Model

Frequently accessed jurisdictions cached.

Cache TTL configurable.

---

Storage Architecture

Primary Storage:

PostgreSQL

Secondary Storage:

ElasticSearch (search index)

Optional:

Graph Database

---

Visualization Interface

Provide UI dashboard.

Displays:

Jurisdiction Overview Currency Rules Risk Indicators Settlement Systems

---

Dashboard Components

Interactive maps Jurisdiction comparison tables Risk heat maps Compliance summaries

---

Policy Linking Model

Each jurisdiction links to policy references.

Policies stored separately.

Referenced dynamically.

---

Multi-Jurisdiction Simulation Support

Support modeling of multi-country flows.

Example:

USD → Indonesia → Botswana → Malta

Simulate legal pathway.

---

Localization Support

Support multilingual output.

Languages configurable.

---

Audit Trail Model

All changes logged.

Includes:

User Timestamp Change Summary Previous Version

---

Security Architecture

Access Control:

Role-Based Access Control (RBAC)

Encryption:

Data-at-rest encryption Data-in-transit encryption

---

Observability Architecture

Track:

Lookup latency Query frequency Update frequency

---

Performance Targets

Lookup latency target:

< 100 ms

Search latency target:

< 300 ms

---

Horizontal Scaling Model

Scale by:

Jurisdiction clusters

Regions grouped geographically.

---

Global Coverage Requirement

System must support:

All sovereign states Dependent territories Special financial jurisdictions

---

Jurisdiction Classification Model

Classify jurisdictions into tiers.

Example:

Tier 1 — Major Financial Centers Tier 2 — Regional Banking Hubs Tier 3 — Restricted or Emerging Jurisdictions

---

Deployment Model

Deploy as independent service.

Accessible via API.

---

Backup Strategy

Nightly backups required.

Geo-redundant storage recommended.

---

Minimum Viable Jurisdiction Dataset

Initial coverage:

Top 50 global financial jurisdictions.

Includes:

United States Indonesia Singapore Switzerland Malta United Kingdom European Union jurisdictions

---

Production Expansion Plan

Phase 1:

Core jurisdictions.

Phase 2:

Full global coverage.

Phase 3:

Real-time regulatory updates.

---

Final Outcome

When complete, the Jurisdictional Cheat Sheets system becomes:

A continuously updated, machine-readable global financial intelligence reference that enables compliant, optimized, jurisdiction-aware financial transaction execution.