Wallet-Core Architecture

This document covers the internal architecture of Wallet-Core, including the service layer, ledger, and data access patterns.

Layer Overview

Service Layer

Services Overview

Service	File	Responsibility
`SubscriberService`	`subscriber_service.go`	User registration, KYC, PIN management
`CardService`	`card_service.go`	Card linking, blocking, child cards
`AgentService`	`agent_service.go`	Agent registration, float, cashin
`WalletService`	`wallet_service.go`	Payments, balances, transfers
`ComplianceService`	`compliance_service.go`	Monitoring rules, alerts
`POSService`	`pos_service.go`	Terminal payments, verification
`ProcessorService`	`processor_service.go`	External processor integration
`FeeService`	`fee_calculator.go`	Fee calculation
`AuditService`	`audit_service.go`	Audit log management
`APIKeyService`	`apikey_service.go`	API key CRUD
`PEPAccessService`	`pep_access_service.go`	Privileged access flows

Service Pattern

// Standard service structure
type SubscriberService struct {
    repo   *repository.SubscriberRepository
    ledger *ledger.Service
    audit  *AuditService
}

func NewSubscriberService(
    repo *repository.SubscriberRepository,
    ledger *ledger.Service,
    audit *AuditService,
) *SubscriberService {
    return &SubscriberService{
        repo:   repo,
        ledger: ledger,
        audit:  audit,
    }
}

func (s *SubscriberService) Register(ctx context.Context, req *RegisterRequest) (*Subscriber, error) {
    // Validate
    if err := validateRequest(req); err != nil {
        return nil, err
    }
    
    // Create subscriber
    subscriber, err := s.repo.Create(ctx, req)
    if err != nil {
        return nil, err
    }
    
    // Create account
    _, err = s.ledger.CreateAccount(ctx, subscriber.ID, "SLE")
    if err != nil {
        // Rollback or handle
    }
    
    // Audit
    s.audit.Log(ctx, "subscriber_registered", subscriber.ID)
    
    return subscriber, nil
}

Ledger

The ledger is the core transaction engine, handling all financial operations.

Core Operations

Operation	Description
`ExecutePayment`	Atomic payment between accounts
`GetBalance`	Retrieve account balance
`CreateAccount`	Create new account for user+currency
`GetTransaction`	Retrieve transaction by ID
`ListTransactions`	Query transaction history
`GetAccountStatement`	Generate account statements

Payment Execution

// ledger/service.go
func (l *Service) ExecutePayment(ctx context.Context, req *PaymentRequest) (*Transaction, error) {
    // Check idempotency
    existing, err := l.txRepo.GetByRequestID(ctx, req.RequestID)
    if err == nil && existing != nil {
        return existing, nil  // Return existing for duplicate
    }
    
    // Start transaction
    tx, err := l.db.BeginTx(ctx, nil)
    if err != nil {
        return nil, err
    }
    defer tx.Rollback()
    
    // Get or create accounts
    senderAcc, err := l.getOrCreateAccount(ctx, tx, req.UserID, req.Currency)
    if err != nil {
        return nil, err
    }
    
    recipientAcc, err := l.getOrCreateAccount(ctx, tx, req.RecipientID, req.Currency)
    if err != nil {
        return nil, err
    }
    
    // Validate balance
    if senderAcc.Balance < req.Amount {
        return nil, ErrInsufficientBalance
    }
    
    // Debit sender
    if err := l.debit(ctx, tx, senderAcc.ID, req.Amount); err != nil {
        return nil, err
    }
    
    // Credit recipient
    if err := l.credit(ctx, tx, recipientAcc.ID, req.Amount); err != nil {
        return nil, err
    }
    
    // Create transaction record
    txn := &Transaction{
        ID:          generateID(),
        RequestID:   req.RequestID,
        UserID:      req.UserID,
        RecipientID: req.RecipientID,
        Amount:      req.Amount,
        Currency:    req.Currency,
        Status:      "COMPLETED",
        CreatedAt:   time.Now(),
        CompletedAt: time.Now(),
    }
    
    if err := l.txRepo.Create(ctx, tx, txn); err != nil {
        return nil, err
    }
    
    // Audit log
    if err := l.auditLog(ctx, tx, txn); err != nil {
        return nil, err
    }
    
    // Commit
    if err := tx.Commit(); err != nil {
        return nil, err
    }
    
    return txn, nil
}

Repository Layer

Repositories provide data access and encapsulate SQL queries.

Repository Pattern

// repository/account_repository.go
type AccountRepository struct {
    db *sql.DB
}

func (r *AccountRepository) GetByUserAndCurrency(
    ctx context.Context,
    userID, currency string,
) (*models.Account, error) {
    query := `
        SELECT id, user_id, currency, balance, created_at, updated_at
        FROM accounts
        WHERE user_id = $1 AND currency = $2
    `
    
    var acc models.Account
    err := r.db.QueryRowContext(ctx, query, userID, currency).Scan(
        &acc.ID, &acc.UserID, &acc.Currency, 
        &acc.Balance, &acc.CreatedAt, &acc.UpdatedAt,
    )
    
    if err == sql.ErrNoRows {
        return nil, ErrAccountNotFound
    }
    
    return &acc, err
}

func (r *AccountRepository) UpdateBalance(
    ctx context.Context,
    tx *sql.Tx,
    accountID string,
    delta int64,
) error {
    query := `
        UPDATE accounts 
        SET balance = balance + $1, updated_at = NOW()
        WHERE id = $2
    `
    
    _, err := tx.ExecContext(ctx, query, delta, accountID)
    return err
}

Available Repositories

Repository	Table	Operations
`AccountRepository`	`accounts`	CRUD, balance updates
`TransactionRepository`	`transactions`	Create, query, list
`SubscriberRepository`	`subscribers`	CRUD, lookup by phone
`CardRepository`	`nfc_cards`	Link, block, list
`AgentRepository`	`agents`	CRUD, float management
`AuditLogRepository`	`audit_log`	Create, query
`APIKeyRepository`	`api_keys`	CRUD
`ComplianceAlertRepository`	`compliance_alerts`	Create, resolve
`MonitoringRuleRepository`	`monitoring_rules`	CRUD

gRPC Server

The server layer maps gRPC requests to service calls:

// server/server.go
type WalletServer struct {
    wallet.UnimplementedWalletServiceServer
    ledger *ledger.Service
}

func (s *WalletServer) ExecutePayment(
    ctx context.Context,
    req *wallet.PaymentRequest,
) (*wallet.PaymentResponse, error) {
    // Map proto to domain
    payment := &ledger.PaymentRequest{
        RequestID:   req.RequestId,
        UserID:      req.UserId,
        RecipientID: req.RecipientId,
        Amount:      req.Amount,
        Currency:    req.Currency,
        Memo:        req.Memo,
    }
    
    // Execute
    txn, err := s.ledger.ExecutePayment(ctx, payment)
    if err != nil {
        return nil, mapToGRPCError(err)
    }
    
    // Map to proto response
    return &wallet.PaymentResponse{
        TransactionId: txn.ID,
        Status:        txn.Status,
        NewBalance:    txn.NewBalance,
    }, nil
}

Database Migrations

Migrations are run at startup:

// database/database.go
func Migrate(db *sql.DB) error {
    migrations := []string{
        `CREATE TABLE IF NOT EXISTS accounts (...)`,
        `CREATE TABLE IF NOT EXISTS transactions (...)`,
        `CREATE TABLE IF NOT EXISTS subscribers (...)`,
        // ... more tables
    }
    
    for _, m := range migrations {
        if _, err := db.Exec(m); err != nil {
            return err
        }
    }
    
    return nil
}

Error Handling

Domain errors are defined and mapped:

// errors.go
var (
    ErrAccountNotFound     = errors.New("account not found")
    ErrInsufficientBalance = errors.New("insufficient balance")
    ErrDuplicateRequest    = errors.New("duplicate request")
    ErrCardAlreadyLinked   = errors.New("card already linked")
)

// Map to gRPC status codes
func mapToGRPCError(err error) error {
    switch {
    case errors.Is(err, ErrAccountNotFound):
        return status.Error(codes.NotFound, err.Error())
    case errors.Is(err, ErrInsufficientBalance):
        return status.Error(codes.FailedPrecondition, err.Error())
    case errors.Is(err, ErrDuplicateRequest):
        return status.Error(codes.AlreadyExists, err.Error())
    default:
        return status.Error(codes.Internal, "internal error")
    }
}

Getting Started

Agent-TS

Gateway

Wallet-Core

Concepts

Architecture

Wallet-Core Architecture

Layer Overview

Service Layer

Services Overview

Service Pattern

Ledger

Core Operations

Payment Execution

Repository Layer

Repository Pattern

Available Repositories

gRPC Server

Database Migrations

Error Handling

Next Steps

Ledger

Configuration

​Wallet-Core Architecture

​Layer Overview

​Service Layer

​Services Overview

​Service Pattern

​Ledger

​Core Operations

​Payment Execution

​Repository Layer

​Repository Pattern

​Available Repositories

​gRPC Server

​Database Migrations

​Error Handling

​Next Steps

Ledger

Configuration

Wallet-Core Architecture

Layer Overview

Service Layer

Services Overview

Service Pattern

Ledger

Core Operations

Payment Execution

Repository Layer

Repository Pattern

Available Repositories

gRPC Server

Database Migrations

Error Handling

Next Steps