pos-system/services/wallet-service-net/docs/en/ARCHITECTURE.md

Wallet Service Architecture

Overview

The Wallet Service manages digital wallets and loyalty point accounts for the GoodGo Platform.

┌─────────────────────────────────────────────────────────────┐
│                     Wallet Service                           │
├─────────────────────────────────────────────────────────────┤
│  API Layer (Controllers, CQRS)                               │
├─────────────────────────────────────────────────────────────┤
│  Domain Layer (Wallet, PointAccount Aggregates)             │
├─────────────────────────────────────────────────────────────┤
│  Infrastructure Layer (EF Core, Repositories)               │
├─────────────────────────────────────────────────────────────┤
│  PostgreSQL Database                                         │
└─────────────────────────────────────────────────────────────┘

Architecture Patterns

Domain-Driven Design (DDD)

• Aggregates: Wallet, PointAccount
• Entities: WalletTransaction, PointTransaction
• Value Objects: Money, PointBalance
• Domain Events: WalletCreated, BalanceChanged, PointsEarned

CQRS Pattern

Commands (Write)              Queries (Read)
    │                             │
    ▼                             ▼
CreateWallet                GetWalletQuery
DepositCommand              GetTransactionsQuery
WithdrawCommand             GetPointAccountQuery
TransferCommand             GetBalanceSummaryQuery
EarnPointsCommand
SpendPointsCommand

Domain Model

Wallet Aggregate

classDiagram
    class Wallet {
        +Guid Id
        +Guid UserId
        +Money Balance
        +WalletStatus Status
        +List~WalletTransaction~ Transactions
        +Deposit(Money, description, ref)
        +Withdraw(Money, description, ref)
        +Freeze()
        +Unfreeze()
        +Close()
    }
    
    class WalletTransaction {
        +Guid Id
        +TransactionType Type
        +Money Amount
        +Money BalanceAfter
        +string Description
        +DateTime CreatedAt
    }
    
    class Money {
        +decimal Amount
        +string Currency
    }
    
    Wallet "1" --> "*" WalletTransaction
    Wallet --> Money

PointAccount Aggregate

classDiagram
    class PointAccount {
        +Guid Id
        +Guid UserId
        +int TotalPoints
        +int AvailablePoints
        +int PendingPoints
        +EarnPoints(points, source, desc, expires)
        +SpendPoints(points, source, desc)
        +AdjustPoints(points, source, desc)
    }
    
    class PointTransaction {
        +Guid Id
        +PointTransactionType Type
        +int Points
        +int BalanceAfter
        +DateTime? ExpiresAt
    }
    
    PointAccount "1" --> "*" PointTransaction

Database Schema

Tables

Table	Description
Wallets	User wallet accounts
WalletTransactions	Wallet transaction history
PointAccounts	User point accounts
PointTransactions	Point transaction history

Key Indexes

• IX_Wallets_UserId - Fast lookup by user
• IX_WalletTransactions_WalletId - Transaction history
• IX_PointAccounts_UserId - Fast lookup by user

API Flow

Deposit Flow

1. Client → POST /api/v1/wallets/deposit
2. Controller → DepositCommand (MediatR)
3. CommandHandler → Validate amount
4. Handler → wallet.Deposit(amount)
5. Domain → Create WalletTransaction + Domain Event
6. Infrastructure → Save to database
7. Response → Updated balance

Transfer Flow

1. Client → POST /api/v1/wallets/transfer
2. Controller → TransferCommand
3. Handler → Get source wallet
4. Handler → Get target wallet
5. Domain → source.Withdraw() + target.Deposit()
6. Infrastructure → Transactional save
7. Response → Transfer confirmation

Inter-Service Communication

IAM Service Integration

Wallet Service ──────► IAM Service
                          │
                          ▼
                    User Validation
                    JWT Verification

Authentication Flow

1. Client sends JWT token in Authorization header
2. Wallet Service validates JWT with IAM Service
3. Extract userId from JWT claims
4. Process wallet operation for user

Deployment

Docker Compose Configuration

wallet-service:
  build:
    context: ../..
    dockerfile: services/wallet-service-net/Dockerfile
  environment:
    - DATABASE_URL=${WALLET_DATABASE_URL}
    - JWT_AUTHORITY=${IAM_SERVICE_URL}
  labels:
    - traefik.http.routers.wallet.rule=PathPrefix(`/api/v1/wallets`)

Health Checks

Endpoint	Check
/health/live	Service is running
/health/ready	Database connected
/health	Full status

Security

Authentication

• JWT Bearer token validation
• IAM Service integration

Authorization

• User can only access own wallet
• Admin endpoints for system operations

Data Protection

• All amounts stored with precision
• Transaction audit trail
• Soft delete for wallets

Performance

Optimizations

• Connection pooling (EF Core)
• Index on frequent queries
• Pagination for transaction history

Scaling

• Horizontal scaling with load balancer
• Read replicas for queries
• Redis caching (future)

Monitoring

Metrics

• Request duration
• Transaction counts
• Error rates

Logging

• Serilog structured logging
• Correlation IDs for tracing
• Seq/Loki integration