wallet

99.99%

Consistency

Strong Consistency

Latency

<200 ms

Scalability

Horizontal

Security

PCI DSS

Encryption

Audit

High Level Architecture

                        Client

                           |

                    API Gateway

                           |

               Authentication Service

                           |

        +------------------+----------------+

        |                                   |

 Wallet Service                    Transaction Service

        |                                   |

        +------------+----------------------+

                     |

              Ledger Service

                     |

              Kafka Event Bus

                     |

      +--------------+------------------+

      |                                 |

 Notification                  Audit Service

      |

Email / SMS / Push

                     |

             PostgreSQL Cluster

                     |

               Redis Cluster

چرا Ledger Service جداست؟

در سیستم بانکی

Wallet فقط موجودی نیست.

اصل حقیقت (Source of Truth)

همیشه Ledger است.

مثلاً

Wallet A

100$

↓

Transfer 30$

↓

Wallet B

Ledger

Debit Wallet A

Credit Wallet B

اگر Wallet خراب شود

Ledger هنوز حقیقت را نگه داشته است.

Entity Diagram

+-----------+
| User      |
+-----------+
| userId PK |
| name      |
| kycStatus |
+-----------+

        1

        |

        *

+------------+
| Wallet     |
+------------+
| walletId   |
| userId FK  |
| currency   |
| status     |
+------------+

        1

        |

        *

+----------------+
| LedgerAccount  |
+----------------+
| accountId      |
| walletId       |
| balance        |
+----------------+

        1

        |

        *

+----------------+
| Transaction    |
+----------------+
| transactionId  |
| type           |
| amount         |
| status         |
| createdAt      |
+----------------+

        1

        |

        *

+----------------+
| LedgerEntry    |
+----------------+
| entryId        |
| debitAccount   |
| creditAccount  |
| amount         |
+----------------+

مهم‌ترین نکته طراحی

هیچوقت Balance را مستقیماً Update نکن.

اشتباه

UPDATE wallet

SET balance=balance-100

در سیستم بانکی این کار ممنوع است.

در عوض

Ledger Entry

Debit

Credit

بعداً

Balance

از روی Ledger محاسبه می‌شود.

Double Entry Accounting

فرض کنید

Wallet A

100$

Wallet B

50$

Transfer

30$

Ledger

Wallet A   -30

Wallet B   +30

جمع کل

-30 +30 = 0

هیچ پولی خلق نشد.

Sequence Diagram

Transfer Money

Client

 |

Wallet Service

 |

Validate Wallet

 |

Transaction Service

 |

Check Balance

 |

Ledger Service

 |

Create Debit Entry

 |

Create Credit Entry

 |

Commit

 |

Publish Kafka

 |

Notification

 |

Return Success

جزئیات

Client

 |

API Gateway

 |

Wallet Service

 |

Ledger Service

 |

PostgreSQL

 |

Kafka

 |

Notification

 |

Client

C4 Model

Level 1

Customer

      |

      |

Digital Wallet Platform

Level 2

API Gateway

Authentication

Wallet Service

Ledger Service

Transaction Service

Notification Service

Audit Service

Fraud Detection

KYC Service

Level 3

داخل Wallet Service

Wallet API

Wallet Validation

Limit Checker

Balance Calculator

Ledger Adapter

Transaction Coordinator

Event Publisher

ADR

ADR-001

PostgreSQL به جای Mongo

Decision

PostgreSQL

Reason

ACID

Transaction

Consistency

ADR-002

Double Entry Accounting

Decision

Ledger

Reason

Audit

Financial Safety

Recovery

ADR-003

Kafka

Decision

Kafka

Reason

Async Notification

Audit

Analytics

Retry

ADR-004

Redis

Decision

Redis Cache

Reason

Balance Cache

Rate Limit

Session

ADR-005

Idempotency Key

تمام درخواست‌های انتقال باید دارای شناسه یکتای Idempotency-Key باشند تا در صورت Retry یا دوبار کلیک کاربر، تراکنش تکراری ایجاد نشود.

ADR-006

Saga Pattern

برای انتقال بین سرویس‌های مختلف از Saga استفاده می‌شود تا در صورت شکست بخشی از فرآیند، عملیات جبرانی (Compensation) انجام شود.

Database

DataDatabaseUserPostgreSQLWalletPostgreSQLLedgerPostgreSQLTransactionPostgreSQLCacheRedisEventsKafkaSearchElasticsearch

Sequence برای Transfer

Client

↓

Gateway

↓

Wallet Service

↓

Transaction Service

↓

Ledger

↓

Commit

↓

Kafka

↓

Notification

Failure Scenarios

Notification Down

Transfer موفق است.

Kafka بعداً Notification را ارسال می‌کند.

Wallet Service Crash

Transaction Rollback

Kafka Down

از Outbox Pattern استفاده می‌شود؛ ابتدا تراکنش و رویداد در یک تراکنش دیتابیس ثبت می‌شوند و سپس یک Outbox Publisher رویداد را به Kafka ارسال می‌کند. بنابراین هیچ رویدادی از دست نمی‌رود.

Database Crash

Replication

Automatic Failover

Duplicate Request

Idempotency Key

Concurrent Withdraw

SELECT ...

FOR UPDATE

یا

Optimistic Lock

امنیت

• 
  TLS برای تمام ارتباطات
  

• 
  Encryption at Rest
  

• 
  HSM برای نگهداری کلیدها
  

• 
  JWT + OAuth2
  

• 
  RBAC
  

• 
  Audit Log غیرقابل تغییر (Immutable)
  

• 
  Tokenization برای اطلاعات حساس
  

• 
  KYC/AML و موتور تشخیص Fraud
  

Bottleneckها

BottleneckSolutionLedger WritePartition بر اساس WalletId + Connection PoolBalance ReadRedis Cache با Invalidating پس از CommitNotificationKafka + Consumer GroupAuditAsync ConsumerReportingRead ReplicaHot WalletSharding بر اساس WalletId