🪙 WalletManager

WalletManager is a backend service for managing users, wallets, balances, and transactions. The project is built using Clean Architecture / DDD-lite principles with a clear separation of domain logic, infrastructure, and application use cases.

🚀 Key Features

• 👤 User management (registration, login, blocking)
• 👛 Wallet management (creation, blocking, closing)
• 💰 Balance management:

• 💳 Transaction management:

• 🏭 Factory + Registry pattern for all domain entities
• 🔄 Mapper layer (domain ↔ database)
• 🧠 Domain invariants (DomainInvariant)
• 🪝 Event signaling via blinker
• 🗄 SQLAlchemy + PostgreSQL integration
• 📦 Facade layer for use cases

🧠 Project Architecture

The project is structured according to Clean Architecture principles.

📌 Domain Layer

Pure business logic. Does not depend on database, frameworks, or infrastructure.

👤 Users

• UserBase, Client, Admin
• domain invariants (email, name, password)
• user status handling

👛 Wallets

• DebitWallet, CreditWallet
• ownership relation
• blocking / closing logic

💰 Balances

• RegularBalance — single currency
• ForeignBalance — multiple currencies
• stored internally as dict[currency -> amount]

💳 Transactions

• DepositTransaction
• WithdrawTransaction
• ExchangeTransaction

• no ORM
• no SQL
• only business rules and invariants

📌 Infrastructure Layer

Handles persistence and external dependencies.

🗄 Database (SQLAlchemy)

• UserTable
• WalletTable
• BalanceTable
• TransactionTable

🔄 Mappers

Responsible for transforming:

Domain ↔ ORM (SQLAlchemy models)

• UserMapper
• WalletMapper
• BalanceMapper
• TransactionMapper

• ForeignBalance is stored as multiple rows in DB
• and reconstructed via grouping

📦 Repositories

Split into:

• commands — write operations (insert/update/delete)
• queries — read operations

• UserCommandsRepository
• WalletQueriesRepository
• BalanceCommandsRepository

⚙️ Application / Use-cases Layer

Encapsulates business workflows.

👤 Users

• CreateUserService
• LoginUserService
• BlockUserService
• CloseUserService

👛 Wallets

• CreateWalletService
• BlockWalletService
• CloseWalletService

💰 Balances

• CreateBalanceService
• FreezeBalanceService
• ShowBalanceService

💳 Transactions

• CreateTransactionService
• ShowTransactionService
• SortTransactionService

🎭 Facade Layer

Provides a simplified interface:

• UserServiceFacade
• WalletServiceFacade
• BalanceServiceFacade
• TransactionServiceFacade

🏭 Factory + Registry

Each domain has:

• Factory — creates instances
• Registry — maps type → class

BalanceTypesEnum.FOREIGN → ForeignBalance

📌 Benefits:

• extensibility
• no hardcoded conditionals
• easy addition of new types

🧩 Core Layer

Shared components:

• 🔢 Enums (User, Wallet, Balance, Transaction)
• ⚠️ DomainInvariant (validation rules)
• 🪝 Signals (blinker)
• 🧰 utilities / decorators
• 📊 logging

🔥 Implementation Highlights

1. Multi-currency balance

Stored in DB as:

wallet_id | currency | amount

In domain:

{ "BTC": 2, "USDT": 3, "TON": 5 }

📌 Reconstructed using:

grouped[obj.balance_id]

2. Domain invariants

Validation happens inside domain models:

DomainInvariant.no_empty(...)
DomainInvariant.is_instance(...)

📌 Ensures consistent object state

3. Signals (blinker)

On state change:

userupgradesignal.send(...)

📌 Enables:

• logging
• auditing
• event-driven extensions

4. Mapper layer

Clear separation:

Database model ≠ Domain model

📌 Prevents ORM leakage into business logic

🧩 Design Patterns Used

• 🏭 Factory Pattern
• 🗂 Registry Pattern
• 🎭 Facade Pattern
• 🧱 Mapper Pattern
• 🪝 Observer Pattern (via signals)
• 🧠 DDD-lite principles

🔮 Possible Improvements

🔹 Architecture

• Unit of Work pattern
• CQRS (separate read/write models)
• Domain Events (instead of direct signals)

🔹 Infrastructure

• Proper Alembic migration setup
• Async SQLAlchemy
• Redis (caching / locks)

🔹 Dependency Injection

• Integrate DI container (e.g. Dishka)

🔹 API Layer

• FastAPI integration
• Pydantic DTOs for request/response

🎯 Project Goal

This project demonstrates:

• strong backend architecture design skills
• separation of concerns
• clean domain modeling
• practical usage of design patterns
• building scalable, production-ready systems