C4 Remittance Container & Component Diagrams¶

Field	Value
Status	Draft
Owner	Remittance Squad
Last Updated	2026-04-03
Applies To	Remittance product line

1. Overview¶

The Remittance system enables cross-border money transfers into Simpaisa's operating markets (Pakistan, Bangladesh, Nepal, Iraq, Egypt). It orchestrates FX rate quoting, AML/KYC screening, and final disbursement through existing Pay-Out channel adapters. Temporal provides durable workflow execution for the multi-step remittance lifecycle.

2. Container Diagram¶

graph TB
    RemitPartner["🌍 Remittance Partner<br/>(API Client)"]

    subgraph "API Gateway"
        KrakenD["KrakenD Gateway<br/>(Auth, throttling, routing)"]
    end

    subgraph "Remittance Services"
        RemitSvc["Remittance Service<br/>(Go)<br/>Corridor orchestration"]
        FXEngine["FX Rate Engine<br/>(Go)<br/>Rate fetching, spread, cache"]
        AMLSvc["AML/KYC Service<br/>(Go)<br/>Sanctions screening, PEP checks"]
    end

    subgraph "Workflow Engine"
        Temporal["Temporal Server<br/>Quote → AML → Settle workflows"]
        TemporalWorker["Temporal Worker<br/>(Go)<br/>Executes remittance activities"]
    end

    subgraph "Payout Adapters (shared)"
        PayOutAdapters["Pay-Out Channel Adapters<br/>(1Link, RAAST, bKash, BRAC,<br/>Faysal, Prime, Agrani)"]
    end

    subgraph "Data Stores"
        SurrealDB["SurrealDB<br/>(Remittances, quotes, AML records)"]
        Redis["Redis<br/>(FX rate cache)"]
    end

    subgraph "Messaging"
        NSQ["NSQ<br/>(Event bus)"]
    end

    subgraph "External — Compliance"
        SanctionsDB["Sanctions Lists<br/>(OFAC, UN, EU, local)"]
        PEPDb["PEP Database"]
    end

    RemitPartner -- "HTTPS" --> KrakenD
    KrakenD -- "gRPC" --> RemitSvc
    RemitSvc -- "gRPC" --> FXEngine
    RemitSvc -- "Start workflow" --> Temporal
    Temporal -- "Dispatch" --> TemporalWorker
    TemporalWorker -- "gRPC" --> AMLSvc
    TemporalWorker -- "gRPC" --> PayOutAdapters
    FXEngine --> Redis
    RemitSvc --> SurrealDB
    AMLSvc --> SurrealDB
    AMLSvc -- "Lookup" --> SanctionsDB
    AMLSvc -- "Lookup" --> PEPDb
    TemporalWorker -- "Publish" --> NSQ

3. Component Diagram — Remittance Service Internals¶

graph TB
    subgraph "Remittance Service (Go)"
        API["gRPC API Layer<br/>Request validation"]
        QuoteEngine["Quote Engine<br/>FX calculation, fee application"]
        CorridorRouter["Corridor Router<br/>Source→destination routing"]
        WorkflowStarter["Workflow Starter<br/>Temporal client"]
        ComplianceGate["Compliance Gate<br/>Pre-flight AML threshold check"]
        RemitRepository["Remittance Repository<br/>SurrealDB persistence"]
        EventPublisher["Event Publisher<br/>NSQ domain events"]
    end

    API --> QuoteEngine
    QuoteEngine --> |"gRPC"| FXEng["FX Rate Engine"]
    API --> CorridorRouter
    CorridorRouter --> ComplianceGate
    ComplianceGate --> WorkflowStarter
    WorkflowStarter --> |"Temporal SDK"| TemporalCluster["Temporal Server"]
    RemitRepository --> DB["SurrealDB"]
    EventPublisher --> Q["NSQ"]

4. Remittance Lifecycle — Quote → Lock → Initiate → AML → Settle¶

sequenceDiagram
    participant RP as Remittance Partner
    participant K as KrakenD
    participant R as Remit Service
    participant FX as FX Rate Engine
    participant T as Temporal
    participant W as Temporal Worker
    participant AML as AML/KYC Service
    participant PO as Pay-Out Adapter
    participant DB as SurrealDB
    participant Q as NSQ

    Note over RP,Q: Phase 1 — Quote
    RP->>K: POST /v1/remittances/quote {corridor, amount, currency}
    K->>R: gRPC CreateQuote
    R->>FX: gRPC GetRate(GBP→PKR)
    FX-->>R: Rate + spread
    R->>DB: Insert quote (status: quoted, ttl: 30s)
    R-->>K: QuoteResponse {quote_id, rate, fee, receive_amount}
    K-->>RP: 200 OK

    Note over RP,Q: Phase 2 — Lock & Initiate
    RP->>K: POST /v1/remittances {quote_id, sender, beneficiary}
    K->>R: gRPC CreateRemittance
    R->>DB: Lock quote, insert remittance (status: initiated)
    R->>T: StartWorkflow(RemittanceWorkflow)
    R-->>K: 202 Accepted {remit_id}
    K-->>RP: 202 Accepted

    Note over RP,Q: Phase 3 — AML Screening
    T->>W: Execute ScreenSender activity
    W->>AML: gRPC ScreenIndividual(sender)
    AML-->>W: CLEAR / MATCH / REVIEW
    alt AML Match
        W->>DB: Update remittance (status: blocked)
        W->>Q: Publish txn.remit.aml.blocked
    end

    T->>W: Execute ScreenBeneficiary activity
    W->>AML: gRPC ScreenIndividual(beneficiary)
    AML-->>W: CLEAR

    Note over RP,Q: Phase 4 — Settlement
    T->>W: Execute DisburseFunds activity
    W->>PO: gRPC Transfer (reuses Pay-Out adapter)
    PO-->>W: Transfer confirmed
    W->>DB: Update remittance (status: completed)
    W->>Q: Publish txn.remit.aml.cleared
    Q-->>RP: Webhook notification

5. Cross-Border Data Flow Markers¶

Remittance transactions cross jurisdictional boundaries. The following markers are attached to every remittance record for regulatory traceability:

Marker	Description	Example
`source_country`	Originating country (ISO 3166-1 alpha-2)	`GB`
`destination_country`	Receiving country	`PK`
`source_currency`	Currency sent	`GBP`
`destination_currency`	Currency received	`PKR`
`corridor`	Corridor identifier	`GB-PK`
`fx_rate_locked`	Rate at time of lock	`356.42`
`aml_screening_result`	Screening outcome	`CLEAR`
`aml_screening_ts`	Timestamp of screening	`2026-04-03T10:15Z`
`regulatory_report_ref`	Reference to filed regulatory report	`SBP-2026-Q2-00412`

6. FX Rate Engine¶

The FX Rate Engine fetches rates from upstream providers, applies Simpaisa's spread, and caches results in Redis.

Parameter	Value
Rate refresh	Every 60 seconds
Cache TTL	120 seconds
Quote lock TTL	30 seconds
Spread	Configurable per corridor
Fallback	Last known rate + stale flag

7. AML/KYC Service¶

Check	Source	SLA
Sanctions screening	OFAC, UN, EU, local lists	< 2 s
PEP screening	Commercial PEP database	< 2 s
Fuzzy name matching	Levenshtein + phonetic matching	< 1 s
Threshold alerting	Configurable per corridor	Real-time

Matches are escalated to the compliance team via notification-svc. The Temporal workflow pauses in a REVIEW state until manual clearance.

8. Supported Corridors¶

Source	Destination	Payout Channels
GB	PK	1Link, RAAST, Easypaisa, JazzCash
AE	PK	1Link, RAAST, Easypaisa
GB	BD	bKash, BRAC, Faysal, Prime
AE	BD	bKash, BRAC, Agrani
GB	NP	Bank transfer (via partner)
AE	IQ	Bank transfer (via partner)

9. Non-Functional Requirements¶

Metric	Target
Availability	99.95%
Quote response P99	< 500 ms
End-to-end settlement	< 60 s (real-time rails)
AML screening P99	< 3 s

10. Architectural Decision Records¶

Changes to Remittance architecture require an ADR in /Standards/ADR/.