The Wallet Management module is a core component of the Wallet Hub system that provides comprehensive wallet lifecycle management, including creation, updates, status management, and financial operations. This module implements Domain-Driven Design principles with a rich domain model that encapsulates wallet behavior and business rules.

The module enables users to:

• Create and manage digital wallets
• Perform financial operations (add/withdraw funds)
• Manage wallet status and lifecycle
• Associate addresses and tokens with wallets
• Track wallet balances and relationships

wallet_management/
├── domain/
│   ├── model/
│   │   ├── Wallet.java              # Main aggregate root
│   │   └── wallet/
│   │       ├── WalletStatus.java    # Status enumeration
│   │       └── WalletToken.java     # Wallet-token relationship entity
│   ├── gateway/
│   │   ├── WalletRepository.java    # Repository interface
│   │   └── WalletTokenRepository.java
│   └── event/
│       └── wallet/                  # Domain events
│           ├── WalletCreatedEvent.java
│           ├── WalletUpdatedEvent.java
│           ├── WalletStatusChangedEvent.java
│           ├── WalletDeletedEvent.java
│           ├── WalletRecoveryInitiatedEvent.java
│           ├── AddressAddedToWalletEvent.java
│           ├── AddressRemovedFromWalletEvent.java
│           ├── TokenAddedToWalletEvent.java
│           ├── TokenRemovedFromWalletEvent.java
│           ├── FundsAddedEvent.java
│           ├── FundsWithdrawnEvent.java
│           └── FundsTransferredEvent.java
├── infrastructure/
│   ├── provider/
│   │   ├── data/
│   │   │   ├── entity/
│   │   │   │   └── WalletEntity.java
│   │   │   ├── repository/
│   │   │   │   ├── JpaWalletRepository.java
│   │   │   │   └── SpringDataWalletRepository.java
│   │   │   └── mapper/
│   │   │       └── WalletMapper.java
│   └── adapter/
│       └── event/
│           └── consumer/
│               └── WalletCreatedEventConsumer.java
└── usecase/
    ├── CreateWalletUseCase.java
    ├── UpdateWalletUseCase.java
    ├── DeleteWalletUseCase.java
    ├── ActivateWalletUseCase.java
    ├── DeactivateWalletUseCase.java
    ├── AddFundsUseCase.java
    ├── WithdrawFundsUseCase.java
    ├── TransferFundsUseCase.java
    ├── AddTokenToWalletUseCase.java
    ├── RemoveTokenFromWalletUseCase.java
    ├── GetWalletDetailsUseCase.java
    ├── ListWalletsUseCase.java
    └── RecoverWalletUseCase.java

graph TB
    subgraph "Presentation Layer"
        API[API Controllers]
    end
    
    subgraph "Application Layer"
        UC[Use Cases]
    end
    
    subgraph "Domain Layer"
        subgraph "Wallet Aggregate"
            W[Wallet<br/>Aggregate Root]
            WT[WalletToken<br/>Entity]
            WS[WalletStatus<br/>Enum]
        end
        
        subgraph "Domain Services"
            REPO[WalletRepository<br/>Interface]
            EVENTS[Domain Events]
        end
    end
    
    subgraph "Infrastructure Layer"
        JPA[JpaWalletRepository]
        SPRING[SpringDataWalletRepository]
        ENTITY[WalletEntity]
        MAPPER[WalletMapper]
        EVENT_PUB[Event Publisher]
    end
    
    subgraph "External Systems"
        DB[(Database)]
        KAFKA[Kafka]
    end
    
    API --> UC
    UC --> W
    UC --> REPO
    W --> EVENTS
    EVENTS --> EVENT_PUB
    REPO --> JPA
    JPA --> SPRING
    JPA --> MAPPER
    MAPPER --> ENTITY
    SPRING --> DB
    EVENT_PUB --> KAFKA

The Wallet class is the central aggregate root that manages wallet state and behavior.

• id: Unique identifier (UUID)
• name: Human-readable wallet name
• description: Optional description
• balance: Current wallet balance (BigDecimal)
• status: Current wallet state (WalletStatus enum)
• userId: Associated user identifier
• addressIds: Set of associated address IDs
• createdAt/updatedAt: Timestamps for audit

// Creation
public static Wallet create(UUID id, String name, String description)

// Financial Operations
public void addFunds(BigDecimal amount)
public void withdrawFunds(BigDecimal amount)

// Status Management
public void activate()
public void deactivate()
public void delete(String reason)
public void lock(String reason)
public void initiateRecovery(String recoveryMethod)

// Address Management
public void addAddress(UUID addressId)
public void removeAddress(UUID addressId)
public boolean containsAddress(UUID addressId)

// Validation
public void validateOperationAllowed()

The wallet supports the following statuses:

The WalletToken entity manages the many-to-many relationship between wallets and tokens.

• walletId: Reference to wallet
• tokenId: Reference to token
• addedAt: Timestamp when token was added
• isEnabled: Whether token is enabled in wallet
• displayName: Custom display name for token
• isVisible: Whether token is visible in UI

The module publishes various domain events to notify other system components about wallet state changes:

The module includes event consumers that process domain events:

1. WalletCreatedEventConsumer

   • Processes wallet creation events from Kafka
   • Extracts trace context for distributed tracing
   • Updates saga state machine for workflow management
   • Validates correlation IDs for event correlation

2. FundsAddedEventConsumer

   • Processes fund addition events
   • Updates related systems (analytics, notifications)

3. FundsWithdrawnEventConsumer

   • Processes withdrawal events
   • Triggers security checks and notifications

4. FundsTransferredEventConsumer

   • Processes transfer events
   • Updates both source and destination wallet systems

The wallet module integrates with the saga state machine for managing distributed transactions:

• State Transitions: WALLET_CREATED event triggers state transitions
• Correlation ID: Events include correlation IDs for tracking distributed workflows
• Error Handling: Missing correlation IDs trigger SAGA_FAILED state
• Trace Propagation: CloudEvents with W3C Trace Context for distributed tracing

sequenceDiagram
    participant User
    participant API as API Controller
    participant UC as CreateWalletUseCase
    participant Wallet as Wallet Aggregate
    participant Repo as WalletRepository
    participant EventPub as EventPublisher
    
    User->>API: POST /wallets
    API->>UC: createWallet(userId, correlationId)
    UC->>Wallet: Wallet.create()
    Wallet-->>UC: New wallet instance
    UC->>Repo: save(wallet)
    Repo-->>UC: Saved wallet
    UC->>EventPub: publish(WalletCreatedEvent)
    EventPub-->>UC: Event published
    UC-->>API: Wallet DTO
    API-->>User: 201 Created

sequenceDiagram
    participant User
    participant API as API Controller
    participant UC as AddFundsUseCase
    participant Repo as WalletRepository
    participant Wallet as Wallet Aggregate
    participant EventPub as EventPublisher
    
    User->>API: POST /wallets/{id}/funds
    API->>UC: execute(walletId, amount)
    UC->>Repo: findById(walletId)
    Repo-->>UC: Wallet
    UC->>Wallet: addFunds(amount)
    Wallet-->>UC: Funds added
    UC->>Repo: update(wallet)
    UC->>EventPub: publish(FundsAddedEvent)
    UC-->>API: Updated wallet
    API-->>User: 200 OK

1. Common Foundation Module (common_foundation.md)

   • AggregateRoot base class
   • Entity base class
   • Domain event infrastructure

2. User Management Module (user_management.md)

   • User association via userId
   • User authentication and authorization

3. Address Management Module (address_management.md)

   • Address entities and management
   • Address-wallet relationships

4. Token Management Module (token_management.md)

   • Token entities
   • Token balance tracking

1. Spring Data JPA - Data persistence
2. MapStruct - Object mapping
3. Kafka - Event publishing
4. PostgreSQL - Database storage

public interface WalletRepository {
    Wallet save(Wallet wallet);
    void update(Wallet wallet);
    Optional<Wallet> findById(UUID id);
    List<Wallet> findAll();
    void delete(UUID id);
    List<Wallet> findByName(String name);
    boolean existsById(UUID id);
    List<Wallet> findByUserId(UUID userId);
    List<Wallet> findByUserIdAndStatus(UUID userId, WalletStatus status);
    List<Wallet> findActiveByUserId(UUID userId);
}

The JpaWalletRepository implements the repository interface using:

• Spring Data JPA for CRUD operations
• WalletMapper for domain-entity conversion
• WalletEntity as JPA entity representation

1. Create Wallet (CreateWalletUseCase)

   • Creates new wallet with default settings
   • Publishes WalletCreatedEvent
   • Returns created wallet

2. Update Wallet (UpdateWalletUseCase)

   • Updates wallet name and description
   • Publishes WalletUpdatedEvent
   • Validates operation permissions

3. Manage Funds (AddFundsUseCase, WithdrawFundsUseCase, TransferFundsUseCase)

   • Handles financial transactions
   • Validates balance constraints
   • Publishes financial events

4. Status Management (ActivateWalletUseCase, DeactivateWalletUseCase, DeleteWalletUseCase)

   • Controls wallet lifecycle
   • Enforces business rules
   • Publishes status change events

5. Token Management (AddTokenToWalletUseCase, RemoveTokenFromWalletUseCase)

   • Manages wallet-token relationships
   • Updates token visibility and settings

1. Balance Validation

   • Withdrawals require sufficient balance
   • Amounts must be positive
   • Balance cannot be negative

2. Status Constraints

   • Only ACTIVE wallets can perform operations
   • DELETED wallets cannot be modified
   • LOCKED wallets require administrative action

3. Address Management

   • Addresses must be unique per wallet
   • Address operations require wallet to be ACTIVE

1. Amount Validation: All financial amounts must be > 0
2. Status Validation: Operations require ACTIVE status
3. Balance Validation: Withdrawals require sufficient balance
4. Address Validation: Addresses must exist before association

• Wallet aggregate behavior
• Business rule validation
• State transition correctness

• Repository operations
• Use case execution
• Event publishing

• API endpoints
• Complete workflows
• Error scenarios

• Frequently accessed wallets
• User wallet lists
• Balance information

• Indexes on userId, status
• Partitioning by user or date
• Query optimization for common operations

• Async event publishing
• Batch processing for high-volume operations
• Dead letter queues for failed events

• User-specific wallet access
• Role-based permissions
• Operation-level authorization

• Sensitive data encryption
• Audit logging
• Tamper detection

• Wallet backup procedures
• Recovery key management
• Disaster recovery plans

• Wallet creation rate
• Transaction volume
• Average wallet balance
• Status distribution

• Repository connectivity
• Event publishing status
• Database performance

• Unusual activity detection
• System error thresholds
• Performance degradation

1. Multi-currency Support

   • Multiple currency balances
   • Exchange rate integration
   • Cross-currency transfers

2. Advanced Security

   • Multi-signature wallets
   • Hardware wallet integration
   • Biometric authentication

3. Analytics Integration

   • Spending patterns
   • Portfolio analysis
   • Tax reporting

4. API Extensions

   • WebSocket notifications
   • Batch operations
   • Advanced filtering

• User Management Module - User authentication and profiles
• Address Management Module - Address creation and validation
• Token Management Module - Token definitions and balances
• Transaction Management Module - Transaction processing
• Common Foundation Module - Base classes and patterns