# tavwo/virtual-wallet-fintech-web-application architecture
> Architecture diagram of the GitHub repository tavwo/virtual-wallet-fintech-web-application, 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/tavwo/virtual-wallet-fintech-web-application
- Repository: https://github.com/tavwo/virtual-wallet-fintech-web-application
## Overview
#### Purpose and Runtime
Virtual Wallet is a Spring Boot fintech application for wallet creation, card-backed funding, user-to-user transfers, donations, referrals, and transaction history. It serves both server-rendered Thymeleaf pages and REST endpoints. Boot entry point: `src/main/java/a16team1/virtualwallet/VirtualWalletApplication.java`.
#### Delivery Surfaces
MVC controllers drive browser flows for home/dashboard, accounts, wallets/cards, PIN, transactions, assistant, and admin pages: `src/main/java/a16team1/virtualwallet/controllers/mvc/TransactionsController.java`, `src/main/java/a16team1/virtualwallet/controllers/mvc/UserAccountController.java`, `src/main/resources/views/transaction-history.html`. REST exposes JWT authentication, transaction/user APIs, and assistant integration: `src/main/java/a16team1/virtualwallet/controllers/rest/JwtAuthenticationController.java`, `src/main/java/a16team1/virtualwallet/controllers/rest/TransactionsRestController.java`.
#### Domain and Persistence Boundary
Core persistent aggregates are users, wallets, payment instruments/cards, transactions, categories, and expiring verification/invitation tokens: `src/main/java/a16team1/virtualwallet/models/User.java`, `src/main/java/a16team1/virtualwallet/models/Wallet.java`, `src/main/java/a16team1/virtualwallet/models/Transaction.java`. Service implementations contain application rules and depend on repository contracts/implementations, which form the Hibernate data-access boundary: `src/main/java/a16team1/virtualwallet/services/TransactionServiceImpl.java`, `src/main/java/a16team1/virtualwallet/repositories/contracts/TransactionRepository.java`, `src/main/java/a16team1/virtualwallet/repositories/TransactionRepositoryImpl.java`.
#### Money Movement Flow
Funding starts from a card/payment instrument and creates funding transactions; transfers debit one wallet and credit another, while donations route an added amount to designated donation-project accounts. Transaction state, references, direction/type/status, DTO conversion, and idempotency are explicit concerns: `src/main/java/a16team1/virtualwallet/services/PaymentInstrumentServiceImpl.java`, `src/main/java/a16team1/virtualwallet/services/IdempotencyManager.java`, `src/main/java/a16team1/virtualwallet/utilities/TransactionReferenceGenerator.java`. Large transfers require a verification-token confirmation/expiry stage: `src/main/java/a16team1/virtualwallet/models/TransactionVerificationToken.java`, `src/main/java/a16team1/virtualwallet/services/email_tokens/TokenServiceImpl.java`.
#### Identity, Authorization, and User Safeguards
Spring Security configuration supports browser authentication plus JWT-filtered API access; user details are loaded through custom security services. MFA and PIN workflows add separate verification gates, including an MVC interceptor that enforces PIN setup: `src/main/java/a16team1/virtualwallet/configuration/SecurityConfig.java`, `src/main/java/a16team1/virtualwallet/security/JwtRequestFilter.java`, `src/main/java/a16team1/virtualwallet/interceptors/PinSetupInterceptor.java`. Registration, referral invitations, and account/transaction confirmation use email token services: `src/main/java/a16team1/virtualwallet/services/email_tokens/EmailVerificationServiceImpl.java`, `src/main/java/a16team1/virtualwallet/services/email_tokens/EmailSenderServiceImpl.java`.
#### Presentation and Mapping Boundary
Controllers translate request/form DTOs into services and prepare models for Thymeleaf; mappers isolate domain-to-presentable DTO conversion. Shared layouts, pages, and static browser assets are packaged with the application: `src/main/java/a16team1/virtualwallet/utilities/mappers/TransactionDtoMapper.java`, `src/main/resources/views/fragments/layout.html`, `src/main/resources/static/js/wallet-assistant.js`.
#### Infrastructure and External Dependencies
The application uses Java/Spring Boot, Spring MVC/Security, Hibernate, and MariaDB. Hibernate/web/template configuration and schema seed scripts establish runtime persistence: `src/main/java/a16team1/virtualwallet/configuration/HibernateConfig.java`, `src/main/resources/application.properties`, `src/main/resources/sql/schema.sql`. Container and deployment artifacts indicate Docker-based execution and CI deployment: `Dockerfile`, `docker-compose.yml`, `.github/workflows/deploy.yml`. The README identifies an external banking API for card top-ups; its repository-facing adapter is `src/main/java/a16team1/virtualwallet/repositories/ExternalCardRepositoryImpl.java`.
Main entry points: [`src/main/java/a16team1/virtualwallet/controllers/mvc/TransactionsController.java`](https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/controllers/mvc/TransactionsController.java) (MVC controllers), [`src/main/java/a16team1/virtualwallet/services/PaymentInstrumentServiceImpl.java`](https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/services/PaymentInstrumentServiceImpl.java) (Money movement), [`src/main/java/a16team1/virtualwallet/services/TransactionServiceImpl.java`](https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/services/TransactionServiceImpl.java) (Application services), [`src/main/java/a16team1/virtualwallet/VirtualWalletApplication.java`](https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/VirtualWalletApplication.java) (Spring Boot application)
## Diagram (Mermaid)
```mermaid
flowchart TD
subgraph group_delivery["Delivery surfaces"]
node_mvc["MVC controllers
browser controllers"]
node_rest["REST controllers
API controllers"]
node_views["Thymeleaf views
server-rendered UI"]
node_mapper["Transaction DTO mapper
presentation mapper"]
end
subgraph group_security["Security & safeguards"]
node_security_config["Spring Security
security configuration"]
node_jwt_filter["JWT request filter
API authentication"]
node_pin_gate["PIN setup gate
MVC interceptor"]
end
subgraph group_core["Application core"]
node_services["Application services
service layer"]
node_money_flow["Money movement
funding, transfer & donation"]
node_idempotency["Idempotency manager
transaction safeguard"]
node_verification["Verification tokens
large-transfer confirmation"]
node_email_tokens["Email token services
email verification"]
node_domain["Wallet domain
persistent aggregates
[Transaction.java]"]
end
subgraph group_persistence["Persistence & integrations"]
node_repository_contract["Repository contracts
data-access interfaces"]
node_hibernate_repos["Hibernate repositories
repository implementations"]
node_mariadb[("MariaDB
relational database
[schema.sql]")]
node_card_api["External banking API
card top-up adapter"]
end
node_app{{"Spring Boot application
boot entry point"}}
node_app -->|"boots"| node_mvc
node_app -->|"boots"| node_rest
node_app -->|"loads"| node_security_config
node_mvc -->|"renders"| node_views
node_mvc -->|"intercepted by"| node_pin_gate
node_mvc -->|"invokes"| node_services
node_mvc -->|"maps DTOs"| node_mapper
node_rest -->|"authenticated by"| node_jwt_filter
node_rest -->|"invokes"| node_services
node_jwt_filter -->|"configured by"| node_security_config
node_services -->|"orchestrates"| node_money_flow
node_services -->|"depends on"| node_repository_contract
node_money_flow -->|"deduplicates requests"| node_idempotency
node_money_flow -->|"requires for large transfers"| node_verification
node_money_flow -->|"tops up cards through"| node_card_api
node_verification -->|"confirmation email"| node_email_tokens
node_repository_contract -->|"implemented by"| node_hibernate_repos
node_hibernate_repos -->|"persists"| node_domain
node_hibernate_repos -->|"uses Hibernate"| node_mariadb
click node_app "https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/VirtualWalletApplication.java"
click node_mvc "https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/controllers/mvc/TransactionsController.java"
click node_rest "https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/controllers/rest/TransactionsRestController.java"
click node_views "https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/resources/views/transaction-history.html"
click node_mapper "https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/utilities/mappers/TransactionDtoMapper.java"
click node_security_config "https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/configuration/SecurityConfig.java"
click node_jwt_filter "https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/security/JwtRequestFilter.java"
click node_pin_gate "https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/interceptors/PinSetupInterceptor.java"
click node_services "https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/services/TransactionServiceImpl.java"
click node_money_flow "https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/services/PaymentInstrumentServiceImpl.java"
click node_idempotency "https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/services/IdempotencyManager.java"
click node_verification "https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/models/TransactionVerificationToken.java"
click node_email_tokens "https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/services/email_tokens/EmailVerificationServiceImpl.java"
click node_domain "https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/models/Transaction.java"
click node_repository_contract "https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/repositories/contracts/TransactionRepository.java"
click node_hibernate_repos "https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/repositories/TransactionRepositoryImpl.java"
click node_mariadb "https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/resources/sql/schema.sql"
click node_card_api "https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/repositories/ExternalCardRepositoryImpl.java"
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_mvc,node_rest,node_views,node_mapper toneBlue
class node_security_config,node_jwt_filter,node_pin_gate toneAmber
class node_services,node_money_flow,node_idempotency,node_verification,node_email_tokens,node_domain toneMint
class node_repository_contract,node_hibernate_repos,node_mariadb,node_card_api toneRose
class node_app toneNeutral
```
## Components
### Delivery surfaces
- [MVC controllers](https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/controllers/mvc/TransactionsController.java): browser controllers · Serve dashboard, wallet, PIN, transaction, assistant, and admin flows. · `src/main/java/a16team1/virtualwallet/controllers/mvc/TransactionsController.java`
- [REST controllers](https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/controllers/rest/TransactionsRestController.java): API controllers · Expose JWT authentication and transaction/user APIs. · `src/main/java/a16team1/virtualwallet/controllers/rest/TransactionsRestController.java`
- [Thymeleaf views](https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/resources/views/transaction-history.html): server-rendered UI · `src/main/resources/views/transaction-history.html`
- [Transaction DTO mapper](https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/utilities/mappers/TransactionDtoMapper.java): presentation mapper · `src/main/java/a16team1/virtualwallet/utilities/mappers/TransactionDtoMapper.java`
### Security & safeguards
- [Spring Security](https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/configuration/SecurityConfig.java): security configuration · Supports browser authentication and JWT-protected API access. · `src/main/java/a16team1/virtualwallet/configuration/SecurityConfig.java`
- [JWT request filter](https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/security/JwtRequestFilter.java): API authentication · `src/main/java/a16team1/virtualwallet/security/JwtRequestFilter.java`
- [PIN setup gate](https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/interceptors/PinSetupInterceptor.java): MVC interceptor · Blocks browser flows until PIN setup is complete. · `src/main/java/a16team1/virtualwallet/interceptors/PinSetupInterceptor.java`
### Application core
- [Application services](https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/services/TransactionServiceImpl.java): service layer · Own application rules for users, wallets, cards, and transactions. · `src/main/java/a16team1/virtualwallet/services/TransactionServiceImpl.java`
- [Money movement](https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/services/PaymentInstrumentServiceImpl.java): funding, transfer & donation · Creates funding transactions, transfers wallet balances, and routes donation amounts. · `src/main/java/a16team1/virtualwallet/services/PaymentInstrumentServiceImpl.java`
- [Idempotency manager](https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/services/IdempotencyManager.java): transaction safeguard · `src/main/java/a16team1/virtualwallet/services/IdempotencyManager.java`
- [Verification tokens](https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/models/TransactionVerificationToken.java): large-transfer confirmation · Confirmation tokens expire before large transfers can complete. · `src/main/java/a16team1/virtualwallet/models/TransactionVerificationToken.java`
- [Email token services](https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/services/email_tokens/EmailVerificationServiceImpl.java): email verification · Handles registration, referral, and confirmation messages. · `src/main/java/a16team1/virtualwallet/services/email_tokens/EmailVerificationServiceImpl.java`
- [Wallet domain](https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/models/Transaction.java): persistent aggregates · Users, wallets, cards, transactions, categories, and tokens. · `src/main/java/a16team1/virtualwallet/models/Transaction.java`
### Persistence & integrations
- [Repository contracts](https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/repositories/contracts/TransactionRepository.java): data-access interfaces · `src/main/java/a16team1/virtualwallet/repositories/contracts/TransactionRepository.java`
- [Hibernate repositories](https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/repositories/TransactionRepositoryImpl.java): repository implementations · `src/main/java/a16team1/virtualwallet/repositories/TransactionRepositoryImpl.java`
- [MariaDB](https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/resources/sql/schema.sql): relational database · Schema and seed scripts establish persistent storage. · `src/main/resources/sql/schema.sql`
- [External banking API](https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/repositories/ExternalCardRepositoryImpl.java): card top-up adapter · `src/main/java/a16team1/virtualwallet/repositories/ExternalCardRepositoryImpl.java`
### Other components
- [Spring Boot application](https://github.com/tavwo/virtual-wallet-fintech-web-application/blob/master/src/main/java/a16team1/virtualwallet/VirtualWalletApplication.java): boot entry point · `src/main/java/a16team1/virtualwallet/VirtualWalletApplication.java`
## Connections
- Spring Boot application → MVC controllers: boots
- Spring Boot application → REST controllers: boots
- Spring Boot application → Spring Security: loads
- MVC controllers → Thymeleaf views: renders
- MVC controllers → PIN setup gate: intercepted by
- MVC controllers → Application services: invokes
- MVC controllers → Transaction DTO mapper: maps DTOs
- REST controllers → JWT request filter: authenticated by
- REST controllers → Application services: invokes
- JWT request filter → Spring Security: configured by
- Application services → Money movement: orchestrates
- Application services → Repository contracts: depends on
- Money movement → Idempotency manager: deduplicates requests
- Money movement → Verification tokens: requires for large transfers
- Money movement → External banking API: tops up cards through
- Verification tokens → Email token services: confirmation email
- Repository contracts → Hibernate repositories: implemented by
- Hibernate repositories → Wallet domain: persists
- Hibernate repositories → MariaDB: uses Hibernate