# cactus91869/muffin-wallet architecture

> Architecture diagram of the GitHub repository cactus91869/muffin-wallet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cactus91869/muffin-wallet
- Repository: https://github.com/cactus91869/muffin-wallet

## Overview

#### Purpose and Build Shape
Muffin Wallet is a multi-module Java/Spring Boot backend for wallet and transaction persistence and HTTP access. Gradle assembles the modules from `settings.gradle` and `build.gradle`; the runnable server is `muffin-wallet-server`.

#### Runtime Entry Point
Spring Boot starts at `muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/MuffinWalletApplication.java`. Runtime configuration is supplied through `muffin-wallet-server/src/main/resources/application.yaml`, with a localhost-specific profile in `muffin-wallet-server/src/main/resources/application-localhost.yaml`.

#### HTTP/API Boundary
The server exposes wallet operations through `muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/controller/MuffinWalletController.java`. API request/response DTOs are intentionally separate from persistence DTOs, under `muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/dto/MuffinWallet.java` and `muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/dto/MuffinTransaction.java`. The published API contract is `muffin-wallet-api/src/main/resources/static/openapi/muffin-wallet-api-v1.yaml`.

#### Service and Domain Translation
`muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/service/MuffinWalletService.java` defines the application-facing wallet behavior, implemented by `muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/service/DefaultMuffinWalletService.java`. This layer coordinates repository calls, maps data into server DTOs via `muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/mapper/MuffinWalletMapper.java`, and converts missing-wallet conditions into `MuffinWalletNotFoundException`.

#### Persistence Contract Boundary
The data API module isolates consumers from storage implementation. `muffin-wallet-data-api/src/main/java/ru/hse/muffin/wallet/data/api/MuffinWalletRepository.java` and `muffin-wallet-data-api/src/main/java/ru/hse/muffin/wallet/data/api/MuffinTransactionRepository.java` are the repository interfaces; their storage-oriented models live in the adjacent `dto` package. The server should depend on these contracts rather than concrete database classes.

#### Data Implementation and Schema Lifecycle
Concrete repository implementations are `muffin-wallet-data/src/main/java/ru/hse/muffin/wallet/data/repository/DefaultMuffinWalletRepository.java` and `muffin-wallet-data/src/main/java/ru/hse/muffin/wallet/data/repository/DefaultMuffinTransactionRepository.java`. `muffin-wallet-data/src/main/java/ru/hse/muffin/wallet/data/config/DataConfig.java` supplies data-layer configuration and auto-configuration is registered through `muffin-wallet-data/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`. Liquibase-style schema evolution begins at `muffin-wallet-data/src/main/resources/db/changelog/db.changelog-master.yaml`, defining wallet and transaction tables.

#### Primary Flow and Infrastructure
The normal flow is HTTP controller → wallet service → data-api repository contract → data repository implementation → relational database; returned persistence DTOs are mapped back to server API DTOs. Local database infrastructure is provisioned by `local-env/docker-compose.yaml`, with bootstrap SQL in `local-env/init.sql`. CI build execution is defined in `.github/workflows/build.yaml`.

Main entry points: [`muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/controller/MuffinWalletController.java`](https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/controller/MuffinWalletController.java) (Wallet controller), [`muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/service/DefaultMuffinWalletService.java`](https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/service/DefaultMuffinWalletService.java) (Default wallet service), [`muffin-wallet-data/src/main/java/ru/hse/muffin/wallet/data/repository/DefaultMuffinWalletRepository.java`](https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-data/src/main/java/ru/hse/muffin/wallet/data/repository/DefaultMuffinWalletRepository.java) (Wallet repository), [`muffin-wallet-data/src/main/java/ru/hse/muffin/wallet/data/repository/DefaultMuffinTransactionRepository.java`](https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-data/src/main/java/ru/hse/muffin/wallet/data/repository/DefaultMuffinTransactionRepository.java) (Transaction repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Server runtime"]
  node_application{{"Spring Boot application<br/>server entry point"}}
  node_runtime_config["Runtime configuration<br/>Spring YAML<br/>[application.yaml]"]
  node_controller["Wallet controller<br/>HTTP controller"]
  node_openapi["OpenAPI v1 contract<br/>API specification"]
  node_api_dtos["Server API DTOs<br/>request/response models<br/>[MuffinWallet.java]"]
  node_service_contract["Wallet service contract<br/>service interface"]
  node_wallet_service["Default wallet service<br/>service implementation"]
  node_mapper["Wallet mapper<br/>domain translator"]
end

subgraph group_data["Data layer"]
  node_repository_contracts["Repository contracts<br/>data API interfaces"]
  node_wallet_repository["Wallet repository<br/>repository implementation"]
  node_transaction_repository["Transaction repository<br/>repository implementation"]
  node_data_config{{"Data auto-configuration<br/>Spring configuration<br/>[DataConfig.java]"}}
  node_schema["Database changelog<br/>Liquibase schema"]
  node_database[("Relational database")]
end

subgraph group_delivery["Build &amp; infrastructure"]
  node_gradle{{"Gradle multi-module build<br/>[settings.gradle]"}}
  node_ci["CI build<br/>workflow<br/>[build.yaml]"]
  node_local_env{{"Local database environment<br/>Docker Compose"}}
end

node_ci -->|"runs"| node_gradle
node_gradle -->|"builds"| node_application
node_runtime_config -->|"configures"| node_application
node_application -->|"serves"| node_controller
node_openapi -.->|"defines API"| node_controller
node_controller -->|"uses"| node_api_dtos
node_controller -->|"calls"| node_service_contract
node_wallet_service -.->|"implements"| node_service_contract
node_wallet_service -->|"depends on"| node_repository_contracts
node_wallet_service -->|"maps through"| node_mapper
node_mapper -->|"produces"| node_api_dtos
node_wallet_repository -.->|"implements"| node_repository_contracts
node_transaction_repository -.->|"implements"| node_repository_contracts
node_data_config -->|"configures"| node_wallet_repository
node_data_config -->|"configures"| node_transaction_repository
node_wallet_repository -->|"persists wallets"| node_database
node_transaction_repository -->|"persists transactions"| node_database
node_schema -->|"evolves schema"| node_database
node_local_env -->|"provisions"| node_database

click node_gradle "https://github.com/cactus91869/muffin-wallet/blob/main/settings.gradle"
click node_ci "https://github.com/cactus91869/muffin-wallet/blob/main/.github/workflows/build.yaml"
click node_application "https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/MuffinWalletApplication.java"
click node_runtime_config "https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-server/src/main/resources/application.yaml"
click node_controller "https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/controller/MuffinWalletController.java"
click node_openapi "https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-api/src/main/resources/static/openapi/muffin-wallet-api-v1.yaml"
click node_api_dtos "https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/dto/MuffinWallet.java"
click node_service_contract "https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/service/MuffinWalletService.java"
click node_wallet_service "https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/service/DefaultMuffinWalletService.java"
click node_mapper "https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/mapper/MuffinWalletMapper.java"
click node_repository_contracts "https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-data-api/src/main/java/ru/hse/muffin/wallet/data/api/MuffinWalletRepository.java"
click node_wallet_repository "https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-data/src/main/java/ru/hse/muffin/wallet/data/repository/DefaultMuffinWalletRepository.java"
click node_transaction_repository "https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-data/src/main/java/ru/hse/muffin/wallet/data/repository/DefaultMuffinTransactionRepository.java"
click node_data_config "https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-data/src/main/java/ru/hse/muffin/wallet/data/config/DataConfig.java"
click node_schema "https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-data/src/main/resources/db/changelog/db.changelog-master.yaml"
click node_local_env "https://github.com/cactus91869/muffin-wallet/blob/main/local-env/docker-compose.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_application,node_runtime_config,node_controller,node_openapi,node_api_dtos,node_service_contract,node_wallet_service,node_mapper toneBlue
class node_repository_contracts,node_wallet_repository,node_transaction_repository,node_data_config,node_schema,node_database toneAmber
class node_gradle,node_ci,node_local_env toneMint
```

## Components

### Server runtime

- [Spring Boot application](https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/MuffinWalletApplication.java): server entry point · `muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/MuffinWalletApplication.java`
- [Runtime configuration](https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-server/src/main/resources/application.yaml): Spring YAML · Includes a localhost-specific profile. · `muffin-wallet-server/src/main/resources/application.yaml`
- [Wallet controller](https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/controller/MuffinWalletController.java): HTTP controller · `muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/controller/MuffinWalletController.java`
- [OpenAPI v1 contract](https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-api/src/main/resources/static/openapi/muffin-wallet-api-v1.yaml): API specification · `muffin-wallet-api/src/main/resources/static/openapi/muffin-wallet-api-v1.yaml`
- [Server API DTOs](https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/dto/MuffinWallet.java): request/response models · Separate from persistence models. · `muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/dto/MuffinWallet.java`
- [Wallet service contract](https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/service/MuffinWalletService.java): service interface · `muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/service/MuffinWalletService.java`
- [Default wallet service](https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/service/DefaultMuffinWalletService.java): service implementation · Coordinates repositories, mapping, and missing-wallet handling. · `muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/service/DefaultMuffinWalletService.java`
- [Wallet mapper](https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/mapper/MuffinWalletMapper.java): domain translator · Maps persistence data to server DTOs. · `muffin-wallet-server/src/main/java/ru/hse/muffin/wallet/server/mapper/MuffinWalletMapper.java`

### Data layer

- [Repository contracts](https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-data-api/src/main/java/ru/hse/muffin/wallet/data/api/MuffinWalletRepository.java): data API interfaces · Storage-independent wallet and transaction access boundary. · `muffin-wallet-data-api/src/main/java/ru/hse/muffin/wallet/data/api/MuffinWalletRepository.java`
- [Wallet repository](https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-data/src/main/java/ru/hse/muffin/wallet/data/repository/DefaultMuffinWalletRepository.java): repository implementation · `muffin-wallet-data/src/main/java/ru/hse/muffin/wallet/data/repository/DefaultMuffinWalletRepository.java`
- [Transaction repository](https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-data/src/main/java/ru/hse/muffin/wallet/data/repository/DefaultMuffinTransactionRepository.java): repository implementation · `muffin-wallet-data/src/main/java/ru/hse/muffin/wallet/data/repository/DefaultMuffinTransactionRepository.java`
- [Data auto-configuration](https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-data/src/main/java/ru/hse/muffin/wallet/data/config/DataConfig.java): Spring configuration · Registered as a Spring Boot auto-configuration. · `muffin-wallet-data/src/main/java/ru/hse/muffin/wallet/data/config/DataConfig.java`
- [Database changelog](https://github.com/cactus91869/muffin-wallet/blob/main/muffin-wallet-data/src/main/resources/db/changelog/db.changelog-master.yaml): Liquibase schema · Defines wallet and transaction tables. · `muffin-wallet-data/src/main/resources/db/changelog/db.changelog-master.yaml`
- **Relational database**: database

### Build & infrastructure

- [Gradle multi-module build](https://github.com/cactus91869/muffin-wallet/blob/main/settings.gradle): build · Assembles all modules and the runnable server. · `settings.gradle`
- [CI build](https://github.com/cactus91869/muffin-wallet/blob/main/.github/workflows/build.yaml): workflow · `.github/workflows/build.yaml`
- [Local database environment](https://github.com/cactus91869/muffin-wallet/blob/main/local-env/docker-compose.yaml): Docker Compose · Provisions the local database with bootstrap SQL. · `local-env/docker-compose.yaml`

## Connections

- CI build → Gradle multi-module build: runs
- Gradle multi-module build → Spring Boot application: builds
- Runtime configuration → Spring Boot application: configures
- Spring Boot application → Wallet controller: serves
- OpenAPI v1 contract → Wallet controller: defines API
- Wallet controller → Server API DTOs: uses
- Wallet controller → Wallet service contract: calls
- Default wallet service → Wallet service contract: implements
- Default wallet service → Repository contracts: depends on
- Default wallet service → Wallet mapper: maps through
- Wallet mapper → Server API DTOs: produces
- Wallet repository → Repository contracts: implements
- Transaction repository → Repository contracts: implements
- Data auto-configuration → Wallet repository: configures
- Data auto-configuration → Transaction repository: configures
- Wallet repository → Relational database: persists wallets
- Transaction repository → Relational database: persists transactions
- Database changelog → Relational database: evolves schema
- Local database environment → Relational database: provisions