# saur1sh/asset-tokenization architecture

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

- Interactive diagram: https://gitdiagram.com/saur1sh/asset-tokenization
- Repository: https://github.com/saur1sh/asset-tokenization

## Overview

This is a microservices platform for fractionalized real-world assets, wallet compliance, trading, and settlement. The primary issuance workflow begins at settlement, which starts a saga; wallet and asset services lock funds and reserve inventory, then settlement completes or compensates the saga. A separate secondary-market path matches orders and triggers blockchain settlement. Pricing and periodic yield distribution are parallel capabilities. The source excerpts confirm the principal service calls and event producers; some consumer wiring is documented in the README but not sampled.

Main entry points: [`settlement-service/src/main/java/com/rwa/settlement/service/SettlementService.java`](https://github.com/saur1sh/asset-tokenization/blob/main/settlement-service/src/main/java/com/rwa/settlement/service/SettlementService.java) (Saga coordinator), [`asset-service/src/main/java/com/rwa/asset/service/AssetService.java`](https://github.com/saur1sh/asset-tokenization/blob/main/asset-service/src/main/java/com/rwa/asset/service/AssetService.java) (Asset inventory), [`identity-wallet-service/src/main/java/com/rwa/wallet/service/WalletService.java`](https://github.com/saur1sh/asset-tokenization/blob/main/identity-wallet-service/src/main/java/com/rwa/wallet/service/WalletService.java) (Wallet service), [`order-service/src/main/java/com/rwa/order/service/OrderService.java`](https://github.com/saur1sh/asset-tokenization/blob/main/order-service/src/main/java/com/rwa/order/service/OrderService.java) (Order matching)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_saga["Issuance Saga"]
  node_settlement_api["Settlement API"]
  node_settlement["Saga coordinator"]
  node_saga_db[("Saga store")]
  node_settlement_outbox[("Saga outbox")]
end

subgraph group_assets["Asset Management"]
  node_asset_api["Asset API"]
  node_asset_service["Asset inventory<br/>[AssetService.java]"]
  node_asset_db[("Assets and reservations")]
  node_asset_outbox[("Inventory outbox")]
  node_price_consumer["Price update consumer"]
  node_yield_service["Yield distribution"]
end

subgraph group_wallet["Wallet Compliance"]
  node_wallet_api["Wallet API"]
  node_wallet_service["Wallet service<br/>[WalletService.java]"]
  node_wallet_db[("Wallet and locks")]
  node_wallet_outbox[("Wallet outbox")]
  node_yield_consumer["Yield credit consumer"]
end

subgraph group_markets["Market Services"]
  node_order_api["Order API"]
  node_order_service["Order matching<br/>[OrderService.java]"]
  node_order_db[("Order store")]
  node_price_oracle["Price oracle"]
end

subgraph group_chain["On-chain Settlement"]
  node_web3_listener["Trade settlement listener"]
  node_contract_service["Contract transfer service"]
end

node_client(("Platform user"))
node_kafka["Kafka event backbone"]
node_besu["Hyperledger Besu"]

node_client -->|"initiates trade"| node_settlement_api
node_settlement_api -->|"starts or reads saga"| node_settlement
node_settlement -->|"stores saga"| node_saga_db
node_settlement -->|"records events"| node_settlement_outbox
node_settlement_outbox -->|"dispatches events"| node_kafka
node_kafka -->|"trade initiated"| node_wallet_service
node_kafka -->|"trade initiated"| node_asset_service
node_wallet_service -->|"checks and locks funds"| node_wallet_db
node_wallet_service -->|"records lock result"| node_wallet_outbox
node_wallet_outbox -->|"dispatches result"| node_kafka
node_asset_service -->|"reserves fractions"| node_asset_db
node_asset_service -->|"records reservation result"| node_asset_outbox
node_asset_outbox -->|"dispatches result"| node_kafka
node_kafka -->|"funds and inventory results"| node_settlement
node_settlement -->|"completes or fails saga"| node_saga_db
node_settlement -->|"emits match or failure"| node_kafka
node_kafka -->|"failure compensation"| node_wallet_service
node_kafka -->|"failure compensation"| node_asset_service
node_client -->|"manages wallet"| node_wallet_api
node_wallet_api -->|"requests wallet operation"| node_wallet_service
node_client -->|"creates asset"| node_asset_api
node_asset_api -->|"creates asset"| node_asset_service
node_client -->|"places order"| node_order_api
node_order_api -->|"submits order"| node_order_service
node_order_service -->|"stores and finds orders"| node_order_db
node_order_service -->|"publishes matched trade"| node_kafka
node_price_oracle -->|"publishes price update"| node_kafka
node_kafka -->|"price update"| node_price_consumer
node_price_consumer -->|"updates asset price"| node_asset_service
node_yield_service -->|"publishes yield"| node_kafka
node_kafka -->|"yield distribution"| node_yield_consumer
node_yield_consumer -->|"credits holders"| node_wallet_service
node_kafka -->|"matched trade"| node_web3_listener
node_web3_listener -->|"requests transfer"| node_contract_service
node_contract_service -.->|"submits transaction"| node_besu

click node_settlement_api "https://github.com/saur1sh/asset-tokenization/blob/main/settlement-service/src/main/java/com/rwa/settlement/controller/SettlementController.java"
click node_settlement "https://github.com/saur1sh/asset-tokenization/blob/main/settlement-service/src/main/java/com/rwa/settlement/service/SettlementService.java"
click node_saga_db "https://github.com/saur1sh/asset-tokenization/blob/main/settlement-service/src/main/java/com/rwa/settlement/repository/TradeSagaRepository.java"
click node_settlement_outbox "https://github.com/saur1sh/asset-tokenization/blob/main/settlement-service/src/main/java/com/rwa/settlement/repository/OutboxEventRepository.java"
click node_wallet_api "https://github.com/saur1sh/asset-tokenization/blob/main/identity-wallet-service/src/main/java/com/rwa/wallet/controller/WalletController.java"
click node_wallet_service "https://github.com/saur1sh/asset-tokenization/blob/main/identity-wallet-service/src/main/java/com/rwa/wallet/service/WalletService.java"
click node_wallet_db "https://github.com/saur1sh/asset-tokenization/blob/main/identity-wallet-service/src/main/java/com/rwa/wallet/repository/WalletRepository.java"
click node_wallet_outbox "https://github.com/saur1sh/asset-tokenization/blob/main/identity-wallet-service/src/main/java/com/rwa/wallet/repository/OutboxEventRepository.java"
click node_asset_api "https://github.com/saur1sh/asset-tokenization/blob/main/asset-service/src/main/java/com/rwa/asset/controller/AssetController.java"
click node_asset_service "https://github.com/saur1sh/asset-tokenization/blob/main/asset-service/src/main/java/com/rwa/asset/service/AssetService.java"
click node_asset_db "https://github.com/saur1sh/asset-tokenization/blob/main/asset-service/src/main/java/com/rwa/asset/repository/AssetRepository.java"
click node_asset_outbox "https://github.com/saur1sh/asset-tokenization/blob/main/asset-service/src/main/java/com/rwa/asset/repository/OutboxEventRepository.java"
click node_order_api "https://github.com/saur1sh/asset-tokenization/blob/main/order-service/src/main/java/com/rwa/order/controller/OrderController.java"
click node_order_service "https://github.com/saur1sh/asset-tokenization/blob/main/order-service/src/main/java/com/rwa/order/service/OrderService.java"
click node_order_db "https://github.com/saur1sh/asset-tokenization/blob/main/order-service/src/main/java/com/rwa/order/repository/OrderRepository.java"
click node_price_oracle "https://github.com/saur1sh/asset-tokenization/blob/main/pricing-service/src/main/java/com/rwa/pricing/service/PriceOracleService.java"
click node_price_consumer "https://github.com/saur1sh/asset-tokenization/blob/main/asset-service/src/main/java/com/rwa/asset/event/PriceEventConsumer.java"
click node_yield_service "https://github.com/saur1sh/asset-tokenization/blob/main/asset-service/src/main/java/com/rwa/asset/service/YieldDistributionService.java"
click node_yield_consumer "https://github.com/saur1sh/asset-tokenization/blob/main/identity-wallet-service/src/main/java/com/rwa/wallet/event/YieldEventConsumer.java"
click node_web3_listener "https://github.com/saur1sh/asset-tokenization/blob/main/settlement-service/src/main/java/com/rwa/settlement/service/Web3SettlementService.java"
click node_contract_service "https://github.com/saur1sh/asset-tokenization/blob/main/settlement-service/src/main/java/com/rwa/settlement/service/SmartContractService.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_settlement_api,node_settlement,node_saga_db,node_settlement_outbox,node_client toneBlue
class node_asset_api,node_asset_service,node_asset_db,node_asset_outbox,node_price_consumer,node_yield_service toneAmber
class node_wallet_api,node_wallet_service,node_wallet_db,node_wallet_outbox,node_yield_consumer toneMint
class node_order_api,node_order_service,node_order_db,node_price_oracle toneRose
class node_web3_listener,node_contract_service,node_kafka,node_besu toneIndigo
```

## Components

### Issuance Saga

- [Settlement API](https://github.com/saur1sh/asset-tokenization/blob/main/settlement-service/src/main/java/com/rwa/settlement/controller/SettlementController.java): `settlement-service/src/main/java/com/rwa/settlement/controller/SettlementController.java`
- [Saga coordinator](https://github.com/saur1sh/asset-tokenization/blob/main/settlement-service/src/main/java/com/rwa/settlement/service/SettlementService.java): `settlement-service/src/main/java/com/rwa/settlement/service/SettlementService.java`
- [Saga store](https://github.com/saur1sh/asset-tokenization/blob/main/settlement-service/src/main/java/com/rwa/settlement/repository/TradeSagaRepository.java): `settlement-service/src/main/java/com/rwa/settlement/repository/TradeSagaRepository.java`
- [Saga outbox](https://github.com/saur1sh/asset-tokenization/blob/main/settlement-service/src/main/java/com/rwa/settlement/repository/OutboxEventRepository.java): `settlement-service/src/main/java/com/rwa/settlement/repository/OutboxEventRepository.java`

### Asset Management

- [Asset API](https://github.com/saur1sh/asset-tokenization/blob/main/asset-service/src/main/java/com/rwa/asset/controller/AssetController.java): `asset-service/src/main/java/com/rwa/asset/controller/AssetController.java`
- [Asset inventory](https://github.com/saur1sh/asset-tokenization/blob/main/asset-service/src/main/java/com/rwa/asset/service/AssetService.java): `asset-service/src/main/java/com/rwa/asset/service/AssetService.java`
- [Assets and reservations](https://github.com/saur1sh/asset-tokenization/blob/main/asset-service/src/main/java/com/rwa/asset/repository/AssetRepository.java): `asset-service/src/main/java/com/rwa/asset/repository/AssetRepository.java`
- [Inventory outbox](https://github.com/saur1sh/asset-tokenization/blob/main/asset-service/src/main/java/com/rwa/asset/repository/OutboxEventRepository.java): `asset-service/src/main/java/com/rwa/asset/repository/OutboxEventRepository.java`
- [Price update consumer](https://github.com/saur1sh/asset-tokenization/blob/main/asset-service/src/main/java/com/rwa/asset/event/PriceEventConsumer.java): `asset-service/src/main/java/com/rwa/asset/event/PriceEventConsumer.java`
- [Yield distribution](https://github.com/saur1sh/asset-tokenization/blob/main/asset-service/src/main/java/com/rwa/asset/service/YieldDistributionService.java): `asset-service/src/main/java/com/rwa/asset/service/YieldDistributionService.java`

### Wallet Compliance

- [Wallet API](https://github.com/saur1sh/asset-tokenization/blob/main/identity-wallet-service/src/main/java/com/rwa/wallet/controller/WalletController.java): `identity-wallet-service/src/main/java/com/rwa/wallet/controller/WalletController.java`
- [Wallet service](https://github.com/saur1sh/asset-tokenization/blob/main/identity-wallet-service/src/main/java/com/rwa/wallet/service/WalletService.java): `identity-wallet-service/src/main/java/com/rwa/wallet/service/WalletService.java`
- [Wallet and locks](https://github.com/saur1sh/asset-tokenization/blob/main/identity-wallet-service/src/main/java/com/rwa/wallet/repository/WalletRepository.java): `identity-wallet-service/src/main/java/com/rwa/wallet/repository/WalletRepository.java`
- [Wallet outbox](https://github.com/saur1sh/asset-tokenization/blob/main/identity-wallet-service/src/main/java/com/rwa/wallet/repository/OutboxEventRepository.java): `identity-wallet-service/src/main/java/com/rwa/wallet/repository/OutboxEventRepository.java`
- [Yield credit consumer](https://github.com/saur1sh/asset-tokenization/blob/main/identity-wallet-service/src/main/java/com/rwa/wallet/event/YieldEventConsumer.java): `identity-wallet-service/src/main/java/com/rwa/wallet/event/YieldEventConsumer.java`

### Market Services

- [Order API](https://github.com/saur1sh/asset-tokenization/blob/main/order-service/src/main/java/com/rwa/order/controller/OrderController.java): `order-service/src/main/java/com/rwa/order/controller/OrderController.java`
- [Order matching](https://github.com/saur1sh/asset-tokenization/blob/main/order-service/src/main/java/com/rwa/order/service/OrderService.java): `order-service/src/main/java/com/rwa/order/service/OrderService.java`
- [Order store](https://github.com/saur1sh/asset-tokenization/blob/main/order-service/src/main/java/com/rwa/order/repository/OrderRepository.java): `order-service/src/main/java/com/rwa/order/repository/OrderRepository.java`
- [Price oracle](https://github.com/saur1sh/asset-tokenization/blob/main/pricing-service/src/main/java/com/rwa/pricing/service/PriceOracleService.java): `pricing-service/src/main/java/com/rwa/pricing/service/PriceOracleService.java`

### On-chain Settlement

- [Trade settlement listener](https://github.com/saur1sh/asset-tokenization/blob/main/settlement-service/src/main/java/com/rwa/settlement/service/Web3SettlementService.java): `settlement-service/src/main/java/com/rwa/settlement/service/Web3SettlementService.java`
- [Contract transfer service](https://github.com/saur1sh/asset-tokenization/blob/main/settlement-service/src/main/java/com/rwa/settlement/service/SmartContractService.java): `settlement-service/src/main/java/com/rwa/settlement/service/SmartContractService.java`

### Other components

- **Platform user**
- **Kafka event backbone**
- **Hyperledger Besu**

## Connections

- Platform user → Settlement API: initiates trade
- Settlement API → Saga coordinator: starts or reads saga
- Saga coordinator → Saga store: stores saga
- Saga coordinator → Saga outbox: records events
- Saga outbox → Kafka event backbone: dispatches events
- Kafka event backbone → Wallet service: trade initiated
- Kafka event backbone → Asset inventory: trade initiated
- Wallet service → Wallet and locks: checks and locks funds
- Wallet service → Wallet outbox: records lock result
- Wallet outbox → Kafka event backbone: dispatches result
- Asset inventory → Assets and reservations: reserves fractions
- Asset inventory → Inventory outbox: records reservation result
- Inventory outbox → Kafka event backbone: dispatches result
- Kafka event backbone → Saga coordinator: funds and inventory results
- Saga coordinator → Saga store: completes or fails saga
- Saga coordinator → Kafka event backbone: emits match or failure
- Kafka event backbone → Wallet service: failure compensation
- Kafka event backbone → Asset inventory: failure compensation
- Platform user → Wallet API: manages wallet
- Wallet API → Wallet service: requests wallet operation
- Platform user → Asset API: creates asset
- Asset API → Asset inventory: creates asset
- Platform user → Order API: places order
- Order API → Order matching: submits order
- Order matching → Order store: stores and finds orders
- Order matching → Kafka event backbone: publishes matched trade
- Price oracle → Kafka event backbone: publishes price update
- Kafka event backbone → Price update consumer: price update
- Price update consumer → Asset inventory: updates asset price
- Yield distribution → Kafka event backbone: publishes yield
- Kafka event backbone → Yield credit consumer: yield distribution
- Yield credit consumer → Wallet service: credits holders
- Kafka event backbone → Trade settlement listener: matched trade
- Trade settlement listener → Contract transfer service: requests transfer
- Contract transfer service → Hyperledger Besu: submits transaction