Architecture

Overview

Wallet Service is a comprehensive digital wallet solution built with NestJS, designed to act as middleware between consumer applications and different wallet service providers. It exposes a standardized API for managing Verifiable Credentials (VCs) and handling user authentication, ensuring consistency regardless of the underlying wallet provider.

A key strength of the Wallet Service is its pluggable adapter architecture, which allows seamless integration with different wallet providers. New providers can be supported by implementing custom adapters, making the system highly extensible and adaptable to evolving wallet ecosystems without impacting existing consumer applications. Detailed steps on adding and registering new wallet service adapters can be found on the link below. https://piramal-swasthya.gitbook.io/uba/toasters/wallet-toaster/developer-guide/add-new-wallet-adapter-in-wallet-service

High-Level Architecture

Core Components

1. User Management Module (src/users/)

Responsibilities:

• User registration and onboarding

• Authentication and authorization

• User profile management

• Password hashing and validation

Key Files:

• user.entity.ts: Database entity definition

• user.service.ts: Business logic for user operations

• user.module.ts: Module configuration

2. Wallet Module (src/wallet/)

Responsibilities:

• Wallet operations coordination

• VC management and operations

• VC watching and callback processing

• API endpoint definitions

Key Files:

• wallet.controller.ts: REST API endpoints

• wallet.service.ts: Core business logic

• wallet-vc.entity.ts: VC database entity

• wallet-vc-watcher.entity.ts: VC watcher entity

• watcher-cron.service.ts: Scheduled tasks for VC monitoring

3. Adapter Layer (src/adapters/)

Responsibilities:

• External wallet provider integration

• API communication abstraction

• Response transformation

• Error handling for external services

Key Files:

• adapter.factory.ts: Adapter creation factory

• dhiway.adapter.ts: Dhiway-specific implementation

• interfaces/wallet-adapter.interface.ts: Adapter contracts

4. Common Module (src/common/)

Responsibilities:

• Shared utilities and services

• Logging infrastructure

• Authentication guards

• Common decorators

Key Files:

• logger/logger.service.ts: Centralized logging

• guards/auth.guard.ts: Authentication guard

• decorators/user.decorator.ts: User extraction decorator

5. Housekeeping Module (src/housekeeping/)

Responsibilities:

• Automated maintenance tasks

• VC synchronization

• Missing VC detection and registration

• System health monitoring

Data Flow Diagrams

User Registration Flow

VC Upload Flow

VC Watching Flow

Watcher Flow 1 – Watcher registered when VC is added in Wallet

This flow describes the scenario where a watcher is automatically registered when a VC is added to the wallet service.

Flow 1 Description:

• Trigger: When a VC is uploaded/added to the wallet service

• Process: The wallet service automatically registers a watcher with the Dhiway issuance instance

• Monitoring: The watcher monitors for any updates to the VC

• Update Handling: When the VC is updated, the issuance instance sends a callback to the wallet service

• Synchronization: The wallet service fetches the latest VC details and updates its local database

Watcher Flow 2 – Watcher registered when VC is fetched in Beneficiary

This flow describes the scenario where a watcher is registered when a VC is fetched by a beneficiary service.

Flow 2 Description:

• Trigger: When a beneficiary service requests a VC from the wallet service

• Process: The beneficiary service explicitly requests the wallet service to register a watcher

• Registration: The wallet service registers the watcher with the Dhiway issuance instance

• Monitoring: The watcher monitors for any updates to the VC

• Update Handling: When the VC is updated, the issuance instance sends a callback to the wallet service

• Synchronization: Both the wallet service and beneficiary service are notified and updated with the latest VC details

Design Patterns Used

1. Adapter Pattern: Used for wallet provider integration

2. Repository Pattern: Used for data access layer

3. Service Layer Pattern: Used for business logic

4. Observer Pattern: Used for VC watching and callbacks

5. Factory Pattern: Used for adapter creation