Architecture Overview

Architecture Overview

Islamic Open Finance™ is built on a modular, rail-based architecture designed for enterprise-grade Islamic financial services.

::: tip Interactive Diagrams All diagrams on this page are interactive. You can:

• Hover over nodes to highlight them
• Click nodes to navigate to related documentation
• Scroll to zoom in/out
• Drag to pan around :::

System Architecture

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#1a5f4a', 'primaryTextColor': '#fff', 'primaryBorderColor': '#0d3d2e', 'lineColor': '#2d8659'}}}%%
flowchart TB
    subgraph FRONTEND["💻 FRONTEND LAYER"]
        direction LR
        F1["<b>API Explorer</b><br/>OpenAPI Docs"]
        F2["<b>Admin Portal</b><br/>Management UI"]
        F3["<b>Customer Dashboard</b><br/>Self-Service"]
        F4["<b>SDKs</b><br/>TS, Python, Go"]
    end

    subgraph GATEWAY["🔒 API GATEWAY"]
        GW["<b>Rail API Gateway</b><br/>Authentication • Rate Limiting • Routing • Caching"]
    end

    subgraph RAILS["⚙️ 89 SPECIALIZED RAILS"]
        direction TB
        subgraph CORE["Core Rails"]
            direction LR
            R1["📋 Contracts"]
            R2["🔍 KYC"]
            R3["✅ Compliance"]
            R4["🛡️ AML"]
        end
        subgraph FINANCIAL["Financial Rails"]
            direction LR
            R5["🏦 Treasury"]
            R6["🔄 Clearing"]
            R7["📒 Ledger"]
            R8["💳 Billing"]
        end
        subgraph OPS["Operations Rails"]
            direction LR
            R9["🔔 Webhooks"]
            R10["🔎 Search"]
            R11["📊 Analytics"]
            R12["📈 Reporting"]
        end
    end

    subgraph ENGINES["🧠 RULES & LOGIC ENGINES"]
        direction LR
        E1["<b>Shariah Rules Engine</b><br/>Compliance Validation"]
        E2["<b>Cerbos</b><br/>Authorization (ABAC)"]
        E3["<b>Pricing Engine</b><br/>Dynamic Calculations"]
    end

    subgraph DATA["🗄️ DATA LAYER"]
        direction LR
        D1[("💾 Primary Database<br/>ACID State")]
        D2[("⚡ Ledger Engine<br/>Double-Entry")]
        D3[("📊 Analytics Engine<br/>OLAP")]
        D4[("🔴 Cache Layer<br/>Sessions & Rate Limits")]
        D5[("🔍 Search Engine<br/>Full-Text")]
    end

    F1 --> GW
    F2 --> GW
    F3 --> GW
    F4 --> GW

    GW --> RAILS
    RAILS --> ENGINES
    ENGINES --> DATA

    style F1 fill:#3b82f6,stroke:#2563eb,color:#fff
    style F2 fill:#3b82f6,stroke:#2563eb,color:#fff
    style F3 fill:#3b82f6,stroke:#2563eb,color:#fff
    style F4 fill:#3b82f6,stroke:#2563eb,color:#fff
    style GW fill:#c9a227,stroke:#8b6914,color:#fff,stroke-width:2px
    style R1 fill:#1a5f4a,stroke:#0d3d2e,color:#fff
    style R2 fill:#1a5f4a,stroke:#0d3d2e,color:#fff
    style R3 fill:#1a5f4a,stroke:#0d3d2e,color:#fff
    style R4 fill:#1a5f4a,stroke:#0d3d2e,color:#fff
    style R5 fill:#10b981,stroke:#059669,color:#fff
    style R6 fill:#10b981,stroke:#059669,color:#fff
    style R7 fill:#10b981,stroke:#059669,color:#fff
    style R8 fill:#10b981,stroke:#059669,color:#fff
    style R9 fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style R10 fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style R11 fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style R12 fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style E1 fill:#ef4444,stroke:#dc2626,color:#fff
    style E2 fill:#ef4444,stroke:#dc2626,color:#fff
    style E3 fill:#ef4444,stroke:#dc2626,color:#fff
    style D1 fill:#336791,stroke:#234567,color:#fff
    style D2 fill:#f59e0b,stroke:#d97706,color:#fff
    style D3 fill:#ffcc00,stroke:#cc9900,color:#000
    style D4 fill:#dc382d,stroke:#a52a21,color:#fff
    style D5 fill:#ff5caa,stroke:#cc4488,color:#fff

Data Flow

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#1a5f4a'}}}%%
sequenceDiagram
    autonumber
    participant Client as 🖥️ Client
    participant Gateway as 🚀 Rail API
    participant Cerbos as 🔐 Authorization
    participant Rail as ⚙️ Business Rail
    participant Rules as 📜 Rules Engine
    participant Ledger as 📒 Ledger
    participant DB as 💾 Database
    participant Events as 📤 Events

    Note over Client,Events: Request Flow with Shariah Compliance

    Client->>+Gateway: 📨 API Request
    Gateway->>+Cerbos: 🔍 Check Permissions
    Cerbos-->>-Gateway: ✅ Authorized
    Gateway->>+Rail: ⚡ Process Request
    Rail->>+Rules: 📜 Validate Shariah Compliance
    Rules-->>-Rail: ✅ Compliant
    Rail->>+DB: 💾 Read/Write Data
    DB-->>-Rail: ✅ Data Response
    Rail->>+Ledger: 💰 Financial Entry
    Ledger-->>-Rail: ✅ Confirmed
    Rail->>Events: 📤 Emit Event
    Rail-->>-Gateway: ✅ Response
    Gateway-->>-Client: 📦 JSON Response

Rail Categories

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#1a5f4a'}}}%%
flowchart LR
    subgraph PLATFORM["🔧 PLATFORM RAILS (14)"]
        direction TB
        P1["metadata"]
        P2["taxonomy"]
        P3["search"]
        P4["events"]
        P5["notifications"]
        P6["webhooks"]
        P7["observability"]
        P8["dev-tools"]
        P9["analytics"]
        P10["health"]
        P11["api-keys"]
        P12["load-testing"]
    end

    subgraph IDENTITY["🔐 IDENTITY RAILS (10)"]
        direction TB
        I1["auth"]
        I2["kyc"]
        I3["kyc-enhanced"]
        I4["aml"]
        I5["consent"]
        I6["access-control"]
        I7["oauth2"]
        I8["saml"]
        I9["mfa"]
        I10["workspace"]
    end

    subgraph DOMAIN["💼 DOMAIN RAILS (19)"]
        direction TB
        D1["contracts"]
        D2["jurisdiction"]
        D3["cases"]
        D4["disputes"]
        D5["zakat"]
        D6["reconciliation"]
        D7["routing"]
        D8["messages"]
        D9["documents"]
        D10["clearing"]
        D11["treasury"]
        D12["risk"]
        D13["portfolio"]
        D14["reporting"]
        D15["compliance"]
        D16["governance"]
        D17["collateral"]
        D18["consent-privacy"]
    end

    subgraph BANKING["🏦 BANKING-GRADE (7)"]
        direction TB
        B1["audit"]
        B2["legal"]
        B3["underwriting"]
        B4["retention"]
        B5["secrets"]
        B6["limits"]
        B7["data-quality"]
    end

    style P1 fill:#10b981,stroke:#059669,color:#fff
    style P2 fill:#10b981,stroke:#059669,color:#fff
    style P3 fill:#10b981,stroke:#059669,color:#fff
    style P4 fill:#10b981,stroke:#059669,color:#fff
    style P5 fill:#10b981,stroke:#059669,color:#fff
    style P6 fill:#10b981,stroke:#059669,color:#fff
    style P7 fill:#10b981,stroke:#059669,color:#fff
    style P8 fill:#10b981,stroke:#059669,color:#fff
    style P9 fill:#10b981,stroke:#059669,color:#fff
    style P10 fill:#10b981,stroke:#059669,color:#fff
    style P11 fill:#10b981,stroke:#059669,color:#fff
    style P12 fill:#10b981,stroke:#059669,color:#fff

    style I1 fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style I2 fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style I3 fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style I4 fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style I5 fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style I6 fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style I7 fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style I8 fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style I9 fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style I10 fill:#8b5cf6,stroke:#7c3aed,color:#fff

    style D1 fill:#3b82f6,stroke:#2563eb,color:#fff
    style D2 fill:#3b82f6,stroke:#2563eb,color:#fff
    style D3 fill:#3b82f6,stroke:#2563eb,color:#fff
    style D4 fill:#3b82f6,stroke:#2563eb,color:#fff
    style D5 fill:#3b82f6,stroke:#2563eb,color:#fff
    style D6 fill:#3b82f6,stroke:#2563eb,color:#fff
    style D7 fill:#3b82f6,stroke:#2563eb,color:#fff
    style D8 fill:#3b82f6,stroke:#2563eb,color:#fff
    style D9 fill:#3b82f6,stroke:#2563eb,color:#fff
    style D10 fill:#3b82f6,stroke:#2563eb,color:#fff
    style D11 fill:#3b82f6,stroke:#2563eb,color:#fff
    style D12 fill:#3b82f6,stroke:#2563eb,color:#fff
    style D13 fill:#3b82f6,stroke:#2563eb,color:#fff
    style D14 fill:#3b82f6,stroke:#2563eb,color:#fff
    style D15 fill:#3b82f6,stroke:#2563eb,color:#fff
    style D16 fill:#3b82f6,stroke:#2563eb,color:#fff
    style D17 fill:#3b82f6,stroke:#2563eb,color:#fff
    style D18 fill:#3b82f6,stroke:#2563eb,color:#fff

    style B1 fill:#f59e0b,stroke:#d97706,color:#fff
    style B2 fill:#f59e0b,stroke:#d97706,color:#fff
    style B3 fill:#f59e0b,stroke:#d97706,color:#fff
    style B4 fill:#f59e0b,stroke:#d97706,color:#fff
    style B5 fill:#f59e0b,stroke:#d97706,color:#fff
    style B6 fill:#f59e0b,stroke:#d97706,color:#fff
    style B7 fill:#f59e0b,stroke:#d97706,color:#fff

Event-Driven Architecture

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#1a5f4a'}}}%%
flowchart LR
    subgraph PRODUCERS["📤 Event Producers"]
        P1["Contract Rail"]
        P2["KYC Rail"]
        P3["Treasury Rail"]
        P4["Compliance Rail"]
    end

    subgraph BUS["📬 Event Bus"]
        EB["<b>Event Fabric</b><br/>Pub/Sub • Routing • Replay"]
    end

    subgraph CONSUMERS["📥 Event Consumers"]
        C1["Webhook Service"]
        C2["Analytics Pipeline"]
        C3["Notification Service"]
        C4["Audit Logger"]
    end

    subgraph EXTERNAL["🌐 External Systems"]
        E1["Partner APIs"]
        E2["Core Banking"]
        E3["Regulatory"]
    end

    P1 -->|"ContractCreated"| EB
    P2 -->|"KYCCompleted"| EB
    P3 -->|"PaymentProcessed"| EB
    P4 -->|"ComplianceChecked"| EB

    EB -->|"Filter & Route"| C1
    EB -->|"Aggregate"| C2
    EB -->|"Notify"| C3
    EB -->|"Log"| C4

    C1 -->|"POST"| E1
    C1 -->|"Callback"| E2
    C1 -->|"Report"| E3

    style P1 fill:#1a5f4a,stroke:#0d3d2e,color:#fff
    style P2 fill:#1a5f4a,stroke:#0d3d2e,color:#fff
    style P3 fill:#1a5f4a,stroke:#0d3d2e,color:#fff
    style P4 fill:#1a5f4a,stroke:#0d3d2e,color:#fff
    style EB fill:#c9a227,stroke:#8b6914,color:#fff,stroke-width:2px
    style C1 fill:#3b82f6,stroke:#2563eb,color:#fff
    style C2 fill:#3b82f6,stroke:#2563eb,color:#fff
    style C3 fill:#3b82f6,stroke:#2563eb,color:#fff
    style C4 fill:#3b82f6,stroke:#2563eb,color:#fff
    style E1 fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style E2 fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style E3 fill:#8b5cf6,stroke:#7c3aed,color:#fff

Data Storage Strategy

Data Type	Storage	Purpose
Transactional	Primary Database	ACID-compliant primary state
Financial	Ledger Engine	High-performance double-entry ledger
Analytics	Analytics Engine	OLAP queries & reporting
Cache	Cache Layer	Session, cache, rate limiting
Search	Search Engine	Full-text search indexing

Multi-Tenant Architecture

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#1a5f4a'}}}%%
flowchart TB
    subgraph TENANTS["🏢 Tenant Isolation"]
        T1["Tenant A<br/>(Bank)"]
        T2["Tenant B<br/>(Takaful)"]
        T3["Tenant C<br/>(Fund)"]
    end

    subgraph GATEWAY["🔒 Tenant Router"]
        GW["API Gateway<br/>Tenant Resolution • Data Isolation"]
    end

    subgraph SCHEMA["📊 Schema Isolation"]
        S1[("tenant_a.*")]
        S2[("tenant_b.*")]
        S3[("tenant_c.*")]
    end

    T1 --> GW
    T2 --> GW
    T3 --> GW

    GW --> S1
    GW --> S2
    GW --> S3

    style T1 fill:#3b82f6,stroke:#2563eb,color:#fff
    style T2 fill:#10b981,stroke:#059669,color:#fff
    style T3 fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style GW fill:#c9a227,stroke:#8b6914,color:#fff,stroke-width:2px
    style S1 fill:#336791,stroke:#234567,color:#fff
    style S2 fill:#336791,stroke:#234567,color:#fff
    style S3 fill:#336791,stroke:#234567,color:#fff

Security Architecture

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#1a5f4a'}}}%%
flowchart TB
    subgraph AUTH["🔐 Authentication"]
        A1["JWT Tokens"]
        A2["OAuth 2.0"]
        A3["SAML SSO"]
        A4["MFA/TOTP"]
    end

    subgraph AUTHZ["🛡️ Authorization"]
        B1["Cerbos ABAC"]
        B2["Role Policies"]
        B3["Resource Policies"]
        B4["Audit Logging"]
    end

    subgraph CRYPTO["🔒 Cryptography"]
        C1["AES-256-GCM"]
        C2["RSA-4096"]
        C3["HMAC-SHA256"]
        C4["Vault Secrets"]
    end

    AUTH --> AUTHZ
    AUTHZ --> CRYPTO

    style A1 fill:#3b82f6,stroke:#2563eb,color:#fff
    style A2 fill:#3b82f6,stroke:#2563eb,color:#fff
    style A3 fill:#3b82f6,stroke:#2563eb,color:#fff
    style A4 fill:#3b82f6,stroke:#2563eb,color:#fff
    style B1 fill:#ef4444,stroke:#dc2626,color:#fff
    style B2 fill:#ef4444,stroke:#dc2626,color:#fff
    style B3 fill:#ef4444,stroke:#dc2626,color:#fff
    style B4 fill:#ef4444,stroke:#dc2626,color:#fff
    style C1 fill:#1a5f4a,stroke:#0d3d2e,color:#fff
    style C2 fill:#1a5f4a,stroke:#0d3d2e,color:#fff
    style C3 fill:#1a5f4a,stroke:#0d3d2e,color:#fff
    style C4 fill:#1a5f4a,stroke:#0d3d2e,color:#fff

Deployment Architecture

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#1a5f4a'}}}%%
flowchart TB
    subgraph EDGE["🌐 Edge Layer"]
        direction LR
        CF["<b>Cloudflare</b><br/>CDN • WAF • DDoS"]
        DNS["DNS<br/>islamicopenfinance.com"]
    end

    subgraph LB["⚖️ Load Balancing"]
        direction LR
        ALB["<b>AWS ALB</b><br/>Application Load Balancer"]
        NLB["<b>AWS NLB</b><br/>Network Load Balancer"]
    end

    subgraph K8S["☸️ Kubernetes Cluster (EKS)"]
        direction TB
        subgraph APPS["Application Pods"]
            direction LR
            API["Rail API<br/>3 replicas"]
            LEDGER["Ledger Service<br/>2 replicas"]
            ANALYTICS["Analytics API<br/>2 replicas"]
            OBP["OBP Gateway<br/>2 replicas"]
        end
        subgraph SUPPORT["Support Services"]
            direction LR
            CERBOS["Cerbos<br/>Authorization"]
            WEBHOOK["Webhook Worker<br/>2 replicas"]
            JOBS["Background Jobs"]
        end
    end

    subgraph DATA["🗄️ Managed Data Services"]
        direction LR
        RDS[("Primary Database<br/>Multi-AZ")]
        CACHE[("Cache Cluster<br/>High Availability")]
        SEARCH[("Search Engine<br/>Managed")]
    end

    subgraph STORAGE["📦 Object Storage"]
        S3["S3 Buckets<br/>Documents • Backups"]
    end

    subgraph MONITORING["📊 Observability"]
        direction LR
        CW["CloudWatch<br/>Metrics & Logs"]
        XRAY["X-Ray<br/>Tracing"]
        ALERTS["SNS<br/>Alerting"]
    end

    DNS --> CF
    CF --> ALB
    CF --> NLB
    ALB --> APPS
    NLB --> SUPPORT
    APPS --> DATA
    SUPPORT --> DATA
    APPS --> S3
    APPS --> CW
    SUPPORT --> CW

    style CF fill:#f48120,stroke:#d46a0d,color:#fff
    style ALB fill:#ff9900,stroke:#cc7a00,color:#fff
    style NLB fill:#ff9900,stroke:#cc7a00,color:#fff
    style API fill:#1a5f4a,stroke:#0d3d2e,color:#fff
    style LEDGER fill:#1a5f4a,stroke:#0d3d2e,color:#fff
    style ANALYTICS fill:#1a5f4a,stroke:#0d3d2e,color:#fff
    style OBP fill:#1a5f4a,stroke:#0d3d2e,color:#fff
    style CERBOS fill:#ef4444,stroke:#dc2626,color:#fff
    style WEBHOOK fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style JOBS fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style RDS fill:#336791,stroke:#234567,color:#fff
    style CACHE fill:#dc382d,stroke:#a52a21,color:#fff
    style SEARCH fill:#ff5caa,stroke:#cc4488,color:#fff
    style S3 fill:#569a31,stroke:#3d6b22,color:#fff
    style CW fill:#ff9900,stroke:#cc7a00,color:#fff

Contract Lifecycle Flow

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#1a5f4a'}}}%%
stateDiagram-v2
    [*] --> Draft: Create Contract
    Draft --> PendingApproval: Submit for Review
    PendingApproval --> Approved: Shariah Board Approval
    PendingApproval --> Rejected: Compliance Issues
    Approved --> Active: Execute Contract
    Active --> Executed: All Terms Met
    Active --> Defaulted: Payment Default
    Active --> Terminated: Early Termination
    Executed --> Matured: Reach Maturity
    Defaulted --> Terminated: Write-off
    Rejected --> Draft: Revise & Resubmit
    Matured --> [*]
    Terminated --> [*]

Payment Processing Flow

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#1a5f4a'}}}%%
sequenceDiagram
    autonumber
    participant Client as 🖥️ Client
    participant API as 🚀 Rail API
    participant Compliance as ✅ Compliance
    participant AML as 🛡️ AML
    participant Treasury as 🏦 Treasury
    participant Ledger as 📒 Ledger Engine
    participant Webhook as 📤 Webhooks

    Note over Client,Webhook: Islamic Payment Processing Flow

    Client->>+API: 💳 Submit Payment
    API->>+Compliance: 📋 Check Shariah Rules
    Compliance-->>-API: ✅ Compliant

    API->>+AML: 🔍 Screen Transaction
    AML-->>-API: ✅ Cleared

    API->>+Treasury: 💰 Authorize Funds
    Treasury-->>-API: ✅ Authorized

    API->>+Ledger: 📝 Double-Entry Booking
    Note right of Ledger: Debit: Customer Account<br/>Credit: Financier Account
    Ledger-->>-API: ✅ Booked

    API->>Webhook: 📤 payment.completed
    API-->>-Client: ✅ Payment Confirmed

Next Steps

• Rails & SKUs - Learn about specialized rails
• Deployment Guide - Deploy your instance
• API Reference - Explore the API