# 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.