# gaurav-gt01/meshpay architecture

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

- Interactive diagram: https://gitdiagram.com/gaurav-gt01/meshpay
- Repository: https://github.com/gaurav-gt01/meshpay

## Overview

#### Purpose and Entry Points
This is a Java payment-mesh demo centered on simulated devices, encrypted payment packets, bridge ingestion, and account settlement. The application starts at `src/main/java/com/demo/upimesh/MeshPayApplication.java`. HTTP-facing entry points are split between API operations in `src/main/java/com/demo/upimesh/controller/ApiController.java` and a dashboard route in `src/main/java/com/demo/upimesh/controller/DashboardController.java`, backed by `src/main/resources/templates/dashboard.html`.

#### Application Configuration
`src/main/java/com/demo/upimesh/config/AppConfig.java` is the central application wiring/configuration boundary. Runtime properties reside in `src/main/resources/application.properties`. Maven packaging and dependency/runtime selection are defined by `pom.xml`; the repository uses the Maven wrapper (`mvnw`, `.mvn/wrapper/maven-wrapper.properties`).

#### Payment and Mesh Domain
Core domain records model account balances, payment requests, mesh transport, and resulting transactions:
- `src/main/java/com/demo/upimesh/model/Account.java`
- `src/main/java/com/demo/upimesh/model/PaymentInstruction.java`
- `src/main/java/com/demo/upimesh/model/MeshPacket.java`
- `src/main/java/com/demo/upimesh/model/Transaction.java`

`PaymentInstruction` is the likely business-level payment payload, while `MeshPacket` establishes a separate transport/envelope boundary for movement through the mesh.

#### Mesh Simulation and Bridge Ingestion
`src/main/java/com/demo/upimesh/service/MeshSimulatorService.java` orchestrates simulated mesh behavior, using `src/main/java/com/demo/upimesh/service/VirtualDevice.java` as the device-level abstraction. `src/main/java/com/demo/upimesh/service/BridgeIngestionService.java` is the boundary where packets arriving from the mesh are accepted into the server-side payment flow.

The principal control path is therefore: controller or simulator creates a payment instruction → it is packaged/transmitted through virtual devices → bridge ingestion accepts it for server processing.

#### Cryptographic Boundary
`src/main/java/com/demo/upimesh/crypto/HybridCryptoService.java` provides cryptographic handling for mesh/payment payloads. `src/main/java/com/demo/upimesh/crypto/ServerKeyHolder.java` owns or exposes server key material. These classes separate encrypted packet handling from controller, device, and settlement logic; mesh-facing data should cross this boundary as `MeshPacket` rather than as trusted business objects.

#### Processing, Idempotency, and Settlement
`src/main/java/com/demo/upimesh/service/IdempotencyService.java` protects the ingestion/processing path from duplicate payment handling, which is important for retransmitted mesh packets or concurrent delivery. `src/main/java/com/demo/upimesh/service/SettlementService.java` applies the resulting financial state transition and creates/updates transaction outcomes. `src/main/java/com/demo/upimesh/service/DemoService.java` likely supplies demo orchestration or seeded scenario behavior around these services.

The expected transactional sequence is: validate/decrypt an ingested packet → enforce idempotency → settle against accounts → record a transaction.

#### Persistence and Operational Boundaries
Persistence is represented by repository interfaces:
- `src/main/java/com/demo/upimesh/model/AccountRepository.java`
- `src/main/java/com/demo/upimesh/model/TransactionRepository.java`

Accounts and transaction history are therefore distinct persistence concerns. Controllers should remain request/response boundaries, services own orchestration and state changes, repositories own storage access, and crypto/device classes own untrusted mesh and key-handling concerns. The included concurrency test at `src/test/java/com/demo/upimesh/IdempotencyConcurrencyTest.java` signals that duplicate/concurrent processing is a material correctness constraint.

Main entry points: [`src/main/java/com/demo/upimesh/service/SettlementService.java`](https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/service/SettlementService.java) (Settlement), [`src/main/java/com/demo/upimesh/service/MeshSimulatorService.java`](https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/service/MeshSimulatorService.java) (Mesh simulator), [`src/main/java/com/demo/upimesh/crypto/HybridCryptoService.java`](https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/crypto/HybridCryptoService.java) (Hybrid crypto), [`src/main/java/com/demo/upimesh/service/BridgeIngestionService.java`](https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/service/BridgeIngestionService.java) (Bridge ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application & UI"]
  node_application["MeshPay application<br/>Spring Boot entry point"]
  node_api_controller["Payment API<br/>HTTP controller<br/>[ApiController.java]"]
  node_dashboard_controller["Dashboard route<br/>HTTP controller"]
  node_dashboard["Dashboard<br/>HTML template<br/>[dashboard.html]"]
  node_app_config["Application wiring<br/>configuration<br/>[AppConfig.java]"]
end

subgraph group_mesh["Mesh Transport"]
  node_payment_instruction["Payment instruction<br/>domain payload"]
  node_mesh_simulator["Mesh simulator<br/>simulation service"]
  node_virtual_device["Virtual device<br/>device abstraction<br/>[VirtualDevice.java]"]
  node_mesh_packet["Encrypted mesh packet<br/>transport envelope<br/>[MeshPacket.java]"]
end

subgraph group_processing["Payment Processing"]
  node_bridge_ingestion["Bridge ingestion<br/>ingestion service"]
  node_hybrid_crypto{{"Hybrid crypto<br/>cryptographic service"}}
  node_server_keys{{"Server keys<br/>key holder"}}
  node_idempotency["Idempotency guard<br/>processing service"]
  node_settlement["Settlement<br/>financial service"]
  node_demo_service["Demo orchestration<br/>demo service<br/>[DemoService.java]"]
end

subgraph group_persistence["Persistence"]
  node_account["Account<br/>domain record<br/>[Account.java]"]
  node_transaction["Transaction<br/>domain record<br/>[Transaction.java]"]
  node_accounts[("Account repository")]
  node_transactions[("Transaction repository")]
end

node_application -->|"boots"| node_app_config
node_api_controller -->|"creates payment flow"| node_mesh_simulator
node_dashboard_controller -->|"renders"| node_dashboard
node_dashboard -.->|"invokes"| node_api_controller
node_mesh_simulator -->|"creates"| node_payment_instruction
node_mesh_simulator -->|"orchestrates"| node_virtual_device
node_virtual_device -->|"encrypts with"| node_hybrid_crypto
node_hybrid_crypto -->|"produces"| node_mesh_packet
node_mesh_packet -->|"arrives at"| node_bridge_ingestion
node_bridge_ingestion -->|"decrypts and validates"| node_hybrid_crypto
node_hybrid_crypto -->|"uses"| node_server_keys
node_bridge_ingestion -->|"deduplicates"| node_idempotency
node_idempotency -->|"authorizes processing"| node_settlement
node_settlement -->|"updates"| node_account
node_settlement -->|"creates"| node_transaction
node_settlement -->|"persists balances"| node_accounts
node_settlement -->|"persists outcome"| node_transactions
node_demo_service -.->|"drives scenarios"| node_mesh_simulator

click node_application "https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/MeshPayApplication.java"
click node_api_controller "https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/controller/ApiController.java"
click node_dashboard_controller "https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/controller/DashboardController.java"
click node_dashboard "https://github.com/gaurav-gt01/meshpay/blob/main/src/main/resources/templates/dashboard.html"
click node_app_config "https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/config/AppConfig.java"
click node_payment_instruction "https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/model/PaymentInstruction.java"
click node_mesh_simulator "https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/service/MeshSimulatorService.java"
click node_virtual_device "https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/service/VirtualDevice.java"
click node_mesh_packet "https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/model/MeshPacket.java"
click node_bridge_ingestion "https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/service/BridgeIngestionService.java"
click node_hybrid_crypto "https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/crypto/HybridCryptoService.java"
click node_server_keys "https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/crypto/ServerKeyHolder.java"
click node_idempotency "https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/service/IdempotencyService.java"
click node_settlement "https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/service/SettlementService.java"
click node_account "https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/model/Account.java"
click node_transaction "https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/model/Transaction.java"
click node_accounts "https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/model/AccountRepository.java"
click node_transactions "https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/model/TransactionRepository.java"
click node_demo_service "https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/service/DemoService.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_application,node_api_controller,node_dashboard_controller,node_dashboard,node_app_config toneBlue
class node_payment_instruction,node_mesh_simulator,node_virtual_device,node_mesh_packet toneAmber
class node_bridge_ingestion,node_hybrid_crypto,node_server_keys,node_idempotency,node_settlement,node_demo_service toneMint
class node_account,node_transaction,node_accounts,node_transactions toneRose
```

## Components

### Application & UI

- [MeshPay application](https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/MeshPayApplication.java): Spring Boot entry point · `src/main/java/com/demo/upimesh/MeshPayApplication.java`
- [Payment API](https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/controller/ApiController.java): HTTP controller · `src/main/java/com/demo/upimesh/controller/ApiController.java`
- [Dashboard route](https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/controller/DashboardController.java): HTTP controller · `src/main/java/com/demo/upimesh/controller/DashboardController.java`
- [Dashboard](https://github.com/gaurav-gt01/meshpay/blob/main/src/main/resources/templates/dashboard.html): HTML template · `src/main/resources/templates/dashboard.html`
- [Application wiring](https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/config/AppConfig.java): configuration · `src/main/java/com/demo/upimesh/config/AppConfig.java`

### Mesh Transport

- [Payment instruction](https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/model/PaymentInstruction.java): domain payload · Business-level payment request. · `src/main/java/com/demo/upimesh/model/PaymentInstruction.java`
- [Mesh simulator](https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/service/MeshSimulatorService.java): simulation service · `src/main/java/com/demo/upimesh/service/MeshSimulatorService.java`
- [Virtual device](https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/service/VirtualDevice.java): device abstraction · `src/main/java/com/demo/upimesh/service/VirtualDevice.java`
- [Encrypted mesh packet](https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/model/MeshPacket.java): transport envelope · Untrusted packet crossing the mesh boundary. · `src/main/java/com/demo/upimesh/model/MeshPacket.java`

### Payment Processing

- [Bridge ingestion](https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/service/BridgeIngestionService.java): ingestion service · `src/main/java/com/demo/upimesh/service/BridgeIngestionService.java`
- [Hybrid crypto](https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/crypto/HybridCryptoService.java): cryptographic service · Decrypts and validates mesh payloads. · `src/main/java/com/demo/upimesh/crypto/HybridCryptoService.java`
- [Server keys](https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/crypto/ServerKeyHolder.java): key holder · `src/main/java/com/demo/upimesh/crypto/ServerKeyHolder.java`
- [Idempotency guard](https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/service/IdempotencyService.java): processing service · Prevents duplicate or concurrent settlement. · `src/main/java/com/demo/upimesh/service/IdempotencyService.java`
- [Settlement](https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/service/SettlementService.java): financial service · Applies balance changes and records outcomes. · `src/main/java/com/demo/upimesh/service/SettlementService.java`
- [Demo orchestration](https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/service/DemoService.java): demo service · `src/main/java/com/demo/upimesh/service/DemoService.java`

### Persistence

- [Account](https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/model/Account.java): domain record · `src/main/java/com/demo/upimesh/model/Account.java`
- [Transaction](https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/model/Transaction.java): domain record · `src/main/java/com/demo/upimesh/model/Transaction.java`
- [Account repository](https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/model/AccountRepository.java): repository · `src/main/java/com/demo/upimesh/model/AccountRepository.java`
- [Transaction repository](https://github.com/gaurav-gt01/meshpay/blob/main/src/main/java/com/demo/upimesh/model/TransactionRepository.java): repository · `src/main/java/com/demo/upimesh/model/TransactionRepository.java`

## Connections

- MeshPay application → Application wiring: boots
- Payment API → Mesh simulator: creates payment flow
- Dashboard route → Dashboard: renders
- Dashboard → Payment API: invokes
- Mesh simulator → Payment instruction: creates
- Mesh simulator → Virtual device: orchestrates
- Virtual device → Hybrid crypto: encrypts with
- Hybrid crypto → Encrypted mesh packet: produces
- Encrypted mesh packet → Bridge ingestion: arrives at
- Bridge ingestion → Hybrid crypto: decrypts and validates
- Hybrid crypto → Server keys: uses
- Bridge ingestion → Idempotency guard: deduplicates
- Idempotency guard → Settlement: authorizes processing
- Settlement → Account: updates
- Settlement → Transaction: creates
- Settlement → Account repository: persists balances
- Settlement → Transaction repository: persists outcome
- Demo orchestration → Mesh simulator: drives scenarios