# hei-school/vola architecture

> Architecture diagram of the GitHub repository hei-school/vola, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hei-school/vola
- Repository: https://github.com/hei-school/vola

## Overview

Vola records application payments against a payment-service provider (currently Orange Money Madagascar), verifies them asynchronously, and exposes payment lookup and reporting APIs. Its Orange workflows also retrieve daily transactions for reconciliation and accept spreadsheet imports; payments can be exported as CSV. The graph shows the sampled controller, service, provider, and persistence calls. Event-consumer dispatch wiring and several paths listed in the tree were not sampled, so their links are omitted rather than inferred.

Main entry points: [`src/main/java/school/hei/vola/service/PaymentService.java`](https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/service/PaymentService.java) (Payment Service), [`src/main/java/school/hei/vola/endpoint/rest/controller/PaymentController.java`](https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/endpoint/rest/controller/PaymentController.java) (Payment Controller), [`src/main/java/school/hei/vola/service/OrangeSyncService.java`](https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/service/OrangeSyncService.java) (Orange Sync), [`src/main/java/school/hei/vola/repository/PaymentRepository.java`](https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/repository/PaymentRepository.java) (Payment Repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Payment API"]
  node_payment_controller["Payment Controller"]
  node_authorization["API Authorization"]
  node_file_converter["Multipart Converter"]
end

subgraph group_workflow["Payment Workflows"]
  node_payment_service["Payment Service"]
  node_verification["Payment Verification"]
  node_event_producer["Event Producer<br/>[EventProducer.java]"]
  node_event_consumer["Event Consumer<br/>[EventConsumer.java]"]
  node_mailbox_handler["Mailbox Handler"]
  node_excel_parser["Excel Parser<br/>[ExcelParser.java]"]
  node_csv["CSV Export"]
end

subgraph group_orange["Orange Integration"]
  node_orange_sync["Orange Sync"]
  node_daily_retrieval["Daily Retrieval"]
  node_orange_client["Orange API Client"]
  node_orange_service["Orange PSP Provider<br/>[PspProvider.java]"]
end

subgraph group_storage["Persistence"]
  node_payment_repository["Payment Repository"]
  node_orange_repository["Orange Payment Repository"]
  node_payment_db[("Payment Database<br/>[JPayment.java]")]
  node_orange_db[("Orange Transaction Database")]
  node_bucket[("Transaction File Bucket")]
end

node_client(("API Client"))
node_orange_provider{{"Orange Money"}}

node_client -->|"calls API"| node_payment_controller
node_payment_controller -->|"authorizes"| node_authorization
node_payment_controller -->|"delegates to"| node_payment_service
node_payment_controller -->|"starts sync"| node_orange_sync
node_payment_controller -->|"converts upload"| node_file_converter
node_payment_service -->|"reads and writes"| node_payment_repository
node_payment_service -->|"publishes events"| node_event_producer
node_payment_service -->|"uploads file"| node_bucket
node_payment_service -->|"delegates import"| node_excel_parser
node_payment_service -->|"builds export"| node_csv
node_payment_repository -->|"persists payments"| node_payment_db
node_orange_sync -->|"fetches transactions"| node_orange_client
node_orange_sync -->|"persists transactions"| node_orange_repository
node_orange_sync -->|"finds payments"| node_payment_repository
node_orange_sync -->|"triggers verification"| node_verification
node_daily_retrieval -->|"fetches transactions"| node_orange_client
node_daily_retrieval -->|"saves transactions"| node_orange_db
node_daily_retrieval -->|"looks up payments"| node_payment_repository
node_daily_retrieval -->|"triggers verification"| node_verification
node_orange_repository -->|"reads and writes"| node_orange_db
node_verification -->|"saves result"| node_payment_repository
node_verification -->|"selects provider"| node_orange_service
node_orange_client -->|"requests transactions"| node_orange_provider
node_mailbox_handler -->|"invokes consumer"| node_event_consumer

click node_payment_controller "https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/endpoint/rest/controller/PaymentController.java"
click node_authorization "https://github.com/hei-school/vola/tree/preprod/src/main/java/school/hei/vola/endpoint/rest/security"
click node_payment_service "https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/service/PaymentService.java"
click node_verification "https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/service/event/PaymentVerificationRequestedService.java"
click node_event_producer "https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/endpoint/event/EventProducer.java"
click node_event_consumer "https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/endpoint/event/consumer/EventConsumer.java"
click node_mailbox_handler "https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/handler/MailboxEventHandler.java"
click node_orange_sync "https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/service/OrangeSyncService.java"
click node_daily_retrieval "https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/service/event/OrangeDailyTransactionsRetrievalRequestedService.java"
click node_orange_client "https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/model/psp/orange/OrangeApiClient.java"
click node_orange_service "https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/service/psp/PspProvider.java"
click node_payment_repository "https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/repository/PaymentRepository.java"
click node_orange_repository "https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/repository/OrangePaymentRepository.java"
click node_payment_db "https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/repository/jpa/model/JPayment.java"
click node_orange_db "https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/repository/jpa/model/JOrangeTransaction.java"
click node_bucket "https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/file/bucket/BucketComponent.java"
click node_excel_parser "https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/service/utils/ExcelParser.java"
click node_file_converter "https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/service/MultipartFileConverter.java"
click node_csv "https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/service/PaymentService.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_payment_controller,node_authorization,node_file_converter,node_client toneBlue
class node_payment_service,node_verification,node_event_producer,node_event_consumer,node_mailbox_handler,node_excel_parser,node_csv toneAmber
class node_orange_sync,node_daily_retrieval,node_orange_client,node_orange_service toneMint
class node_payment_repository,node_orange_repository,node_payment_db,node_orange_db,node_bucket toneRose
class node_orange_provider toneIndigo
```

## Components

### Payment API

- [Payment Controller](https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/endpoint/rest/controller/PaymentController.java): `src/main/java/school/hei/vola/endpoint/rest/controller/PaymentController.java`
- [API Authorization](https://github.com/hei-school/vola/tree/preprod/src/main/java/school/hei/vola/endpoint/rest/security): `src/main/java/school/hei/vola/endpoint/rest/security`
- [Multipart Converter](https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/service/MultipartFileConverter.java): `src/main/java/school/hei/vola/service/MultipartFileConverter.java`

### Payment Workflows

- [Payment Service](https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/service/PaymentService.java): `src/main/java/school/hei/vola/service/PaymentService.java`
- [Payment Verification](https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/service/event/PaymentVerificationRequestedService.java): `src/main/java/school/hei/vola/service/event/PaymentVerificationRequestedService.java`
- [Event Producer](https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/endpoint/event/EventProducer.java): `src/main/java/school/hei/vola/endpoint/event/EventProducer.java`
- [Event Consumer](https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/endpoint/event/consumer/EventConsumer.java): `src/main/java/school/hei/vola/endpoint/event/consumer/EventConsumer.java`
- [Mailbox Handler](https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/handler/MailboxEventHandler.java): `src/main/java/school/hei/vola/handler/MailboxEventHandler.java`
- [Excel Parser](https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/service/utils/ExcelParser.java): `src/main/java/school/hei/vola/service/utils/ExcelParser.java`
- [CSV Export](https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/service/PaymentService.java): `src/main/java/school/hei/vola/service/PaymentService.java`

### Orange Integration

- [Orange Sync](https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/service/OrangeSyncService.java): `src/main/java/school/hei/vola/service/OrangeSyncService.java`
- [Daily Retrieval](https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/service/event/OrangeDailyTransactionsRetrievalRequestedService.java): `src/main/java/school/hei/vola/service/event/OrangeDailyTransactionsRetrievalRequestedService.java`
- [Orange API Client](https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/model/psp/orange/OrangeApiClient.java): `src/main/java/school/hei/vola/model/psp/orange/OrangeApiClient.java`
- [Orange PSP Provider](https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/service/psp/PspProvider.java): `src/main/java/school/hei/vola/service/psp/PspProvider.java`

### Persistence

- [Payment Repository](https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/repository/PaymentRepository.java): `src/main/java/school/hei/vola/repository/PaymentRepository.java`
- [Orange Payment Repository](https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/repository/OrangePaymentRepository.java): `src/main/java/school/hei/vola/repository/OrangePaymentRepository.java`
- [Payment Database](https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/repository/jpa/model/JPayment.java): `src/main/java/school/hei/vola/repository/jpa/model/JPayment.java`
- [Orange Transaction Database](https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/repository/jpa/model/JOrangeTransaction.java): `src/main/java/school/hei/vola/repository/jpa/model/JOrangeTransaction.java`
- [Transaction File Bucket](https://github.com/hei-school/vola/blob/preprod/src/main/java/school/hei/vola/file/bucket/BucketComponent.java): `src/main/java/school/hei/vola/file/bucket/BucketComponent.java`

### Other components

- **API Client**
- **Orange Money**

## Connections

- API Client → Payment Controller: calls API (evidence: `src/main/java/school/hei/vola/endpoint/rest/controller/PaymentController.java`)
- Payment Controller → API Authorization: authorizes (evidence: `src/main/java/school/hei/vola/endpoint/rest/controller/PaymentController.java`)
- Payment Controller → Payment Service: delegates to (evidence: `src/main/java/school/hei/vola/endpoint/rest/controller/PaymentController.java`)
- Payment Controller → Orange Sync: starts sync (evidence: `src/main/java/school/hei/vola/endpoint/rest/controller/PaymentController.java`)
- Payment Controller → Multipart Converter: converts upload (evidence: `src/main/java/school/hei/vola/endpoint/rest/controller/PaymentController.java`)
- Payment Service → Payment Repository: reads and writes (evidence: `src/main/java/school/hei/vola/service/PaymentService.java`)
- Payment Service → Event Producer: publishes events (evidence: `src/main/java/school/hei/vola/service/PaymentService.java`)
- Payment Service → Transaction File Bucket: uploads file (evidence: `src/main/java/school/hei/vola/service/PaymentService.java`)
- Payment Service → Excel Parser: delegates import (evidence: `src/main/java/school/hei/vola/service/PaymentService.java`)
- Payment Service → CSV Export: builds export (evidence: `src/main/java/school/hei/vola/service/PaymentService.java`)
- Payment Repository → Payment Database: persists payments (evidence: `src/main/java/school/hei/vola/repository/PaymentRepository.java`)
- Orange Sync → Orange API Client: fetches transactions (evidence: `src/main/java/school/hei/vola/service/OrangeSyncService.java`)
- Orange Sync → Orange Payment Repository: persists transactions (evidence: `src/main/java/school/hei/vola/service/OrangeSyncService.java`)
- Orange Sync → Payment Repository: finds payments (evidence: `src/main/java/school/hei/vola/service/OrangeSyncService.java`)
- Orange Sync → Payment Verification: triggers verification (evidence: `src/main/java/school/hei/vola/service/OrangeSyncService.java`)
- Daily Retrieval → Orange API Client: fetches transactions (evidence: `src/main/java/school/hei/vola/service/event/OrangeDailyTransactionsRetrievalRequestedService.java`)
- Daily Retrieval → Orange Transaction Database: saves transactions (evidence: `src/main/java/school/hei/vola/service/event/OrangeDailyTransactionsRetrievalRequestedService.java`)
- Daily Retrieval → Payment Repository: looks up payments (evidence: `src/main/java/school/hei/vola/service/event/OrangeDailyTransactionsRetrievalRequestedService.java`)
- Daily Retrieval → Payment Verification: triggers verification (evidence: `src/main/java/school/hei/vola/service/event/OrangeDailyTransactionsRetrievalRequestedService.java`)
- Orange Payment Repository → Orange Transaction Database: reads and writes (evidence: `src/main/java/school/hei/vola/repository/OrangePaymentRepository.java`)
- Payment Verification → Payment Repository: saves result (evidence: `src/main/java/school/hei/vola/service/event/PaymentVerificationRequestedService.java`)
- Payment Verification → Orange PSP Provider: selects provider (evidence: `src/main/java/school/hei/vola/service/event/PaymentVerificationRequestedService.java`)
- Orange API Client → Orange Money: requests transactions (evidence: `src/main/java/school/hei/vola/model/psp/orange/OrangeApiClient.java`)
- Mailbox Handler → Event Consumer: invokes consumer (evidence: `src/main/java/school/hei/vola/handler/MailboxEventHandler.java`)
