# narutchai01/solpay-core-service architecture

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

- Interactive diagram: https://gitdiagram.com/narutchai01/solpay-core-service
- Repository: https://github.com/narutchai01/solpay-core-service

## Overview

Solpay Core Service exposes account, identity, balance, quote, swap, and transaction APIs, with RabbitMQ-driven processing for deposits and withdrawals. The principal transaction workflow accepts an API request, records it, then advances asynchronous blockchain, balance, and payment stages before finalizing status; off-chain withdrawals also generate and store a slip. The README documents those event relationships. Several domain modules are unsampled, so their internal calls are not inferred here.

Main entry points: [`internal/core/services/transaction_service.go`](https://github.com/narutchai01/solpay-core-service/blob/main/internal/core/services/transaction_service.go) (Transaction orchestration), [`internal/infra/rabbitmq/consumer.go`](https://github.com/narutchai01/solpay-core-service/blob/main/internal/infra/rabbitmq/consumer.go) (Event consumers), [`internal/server/server.go`](https://github.com/narutchai01/solpay-core-service/blob/main/internal/server/server.go) (HTTP server), [`internal/routes/routes.go`](https://github.com/narutchai01/solpay-core-service/blob/main/internal/routes/routes.go) (API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_entry["HTTP server<br/>[server.go]"]
  node_routes["API routes<br/>[routes.go]"]
  node_txhandler["Transaction handlers"]
  node_userhandler["User handlers<br/>[user_handler.go]"]
  node_accounthandler["Account handlers<br/>[account_handler.go]"]
end

subgraph group_domain["Domain Services"]
  node_services["Domain services"]
  node_userservice["KYC &amp; user service<br/>[user_service.go]"]
  node_quotes["Quote &amp; swap<br/>[quote_service.go]"]
  node_solanaservice["On-chain service<br/>[onchain_service.go]"]
  node_balance["Balance service<br/>[balance_service.go]"]
end

subgraph group_async["Transaction Processing"]
  node_txservice["Transaction orchestration"]
  node_rabbit["RabbitMQ queues"]
  node_workers["Event consumers<br/>[consumer.go]"]
end

subgraph group_infra["Persistence &amp; Integrations"]
  node_db[("PostgreSQL<br/>[db.go]")]
  node_txrepo["Transaction repository"]
  node_repositories["Domain repositories"]
  node_solana["Solana transaction client"]
  node_payment["Payment gateway<br/>[omise_gateway.go]"]
  node_slip["Slip generation<br/>[slip.go]"]
  node_storage["Supabase storage<br/>[upload.go]"]
end

subgraph group_realtime["Realtime"]
  node_hub["WebSocket hub<br/>[hub.go]"]
  node_wsroutes["WebSocket routes<br/>[websocket_route.go]"]
end

node_user(("User"))
node_supabase["Supabase"]

node_user -->|"sends requests"| node_entry
node_entry -->|"configures routes"| node_routes
node_routes -.->|"routes transactions"| node_txhandler
node_routes -.->|"routes users"| node_userhandler
node_routes -.->|"routes accounts"| node_accounthandler
node_txhandler -->|"invokes"| node_txservice
node_userhandler -->|"invokes"| node_userservice
node_accounthandler -->|"invokes"| node_services
node_entry -->|"sets up queues"| node_rabbit
node_entry -->|"starts"| node_hub
node_entry -->|"configures"| node_wsroutes
node_txservice -->|"records transaction"| node_txrepo
node_txrepo -->|"reads and writes"| node_db
node_txservice -->|"publishes events"| node_rabbit
node_rabbit -.->|"dispatches messages"| node_workers
node_workers -->|"reports status"| node_txservice
node_workers -->|"dispatches on-chain work"| node_solana
node_workers -->|"dispatches balance work"| node_balance
node_workers -->|"dispatches payment work"| node_payment
node_workers -->|"updates transaction"| node_db
node_userservice -->|"uploads KYC images"| node_storage
node_storage -.->|"stores files"| node_supabase
node_txservice -->|"generates slip"| node_slip
node_txservice -->|"uploads slip"| node_storage
node_txservice -.->|"notifies clients"| node_hub
node_routes -->|"exposes quotes and swaps"| node_quotes
node_quotes -.->|"uses repositories"| node_repositories
node_solanaservice -.->|"uses client"| node_solana
node_balance -.->|"uses repositories"| node_repositories
node_userservice -.->|"uses repositories"| node_repositories

click node_entry "https://github.com/narutchai01/solpay-core-service/blob/main/internal/server/server.go"
click node_routes "https://github.com/narutchai01/solpay-core-service/blob/main/internal/routes/routes.go"
click node_txhandler "https://github.com/narutchai01/solpay-core-service/blob/main/internal/handler/transaction_handler.go"
click node_userhandler "https://github.com/narutchai01/solpay-core-service/blob/main/internal/handler/user_handler.go"
click node_accounthandler "https://github.com/narutchai01/solpay-core-service/blob/main/internal/handler/account_handler.go"
click node_services "https://github.com/narutchai01/solpay-core-service/tree/main/internal/core/services"
click node_txservice "https://github.com/narutchai01/solpay-core-service/blob/main/internal/core/services/transaction_service.go"
click node_userservice "https://github.com/narutchai01/solpay-core-service/blob/main/internal/core/services/user_service.go"
click node_quotes "https://github.com/narutchai01/solpay-core-service/blob/main/internal/core/services/quote_service.go"
click node_solanaservice "https://github.com/narutchai01/solpay-core-service/blob/main/internal/core/services/onchain_service.go"
click node_balance "https://github.com/narutchai01/solpay-core-service/blob/main/internal/core/services/balance_service.go"
click node_db "https://github.com/narutchai01/solpay-core-service/blob/main/internal/db/db.go"
click node_txrepo "https://github.com/narutchai01/solpay-core-service/blob/main/internal/infra/repositories/transaction_repository.go"
click node_repositories "https://github.com/narutchai01/solpay-core-service/tree/main/internal/infra/repositories"
click node_rabbit "https://github.com/narutchai01/solpay-core-service/tree/main/internal/infra/rabbitmq"
click node_workers "https://github.com/narutchai01/solpay-core-service/blob/main/internal/infra/rabbitmq/consumer.go"
click node_solana "https://github.com/narutchai01/solpay-core-service/blob/main/internal/infra/solana/transaction_repository.go"
click node_payment "https://github.com/narutchai01/solpay-core-service/blob/main/internal/infra/payment/omise_gateway.go"
click node_slip "https://github.com/narutchai01/solpay-core-service/blob/main/internal/utils/slip.go"
click node_storage "https://github.com/narutchai01/solpay-core-service/blob/main/internal/infra/supabase/upload.go"
click node_hub "https://github.com/narutchai01/solpay-core-service/blob/main/internal/websocket/hub.go"
click node_wsroutes "https://github.com/narutchai01/solpay-core-service/blob/main/internal/routes/websocket_route.go"

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_entry,node_routes,node_txhandler,node_userhandler,node_accounthandler,node_user toneBlue
class node_services,node_userservice,node_quotes,node_solanaservice,node_balance toneAmber
class node_txservice,node_rabbit,node_workers toneMint
class node_db,node_txrepo,node_repositories,node_solana,node_payment,node_slip,node_storage toneRose
class node_hub,node_wsroutes,node_supabase toneIndigo
```

## Components

### HTTP API

- [HTTP server](https://github.com/narutchai01/solpay-core-service/blob/main/internal/server/server.go): `internal/server/server.go`
- [API routes](https://github.com/narutchai01/solpay-core-service/blob/main/internal/routes/routes.go): `internal/routes/routes.go`
- [Transaction handlers](https://github.com/narutchai01/solpay-core-service/blob/main/internal/handler/transaction_handler.go): `internal/handler/transaction_handler.go`
- [User handlers](https://github.com/narutchai01/solpay-core-service/blob/main/internal/handler/user_handler.go): `internal/handler/user_handler.go`
- [Account handlers](https://github.com/narutchai01/solpay-core-service/blob/main/internal/handler/account_handler.go): `internal/handler/account_handler.go`

### Domain Services

- [Domain services](https://github.com/narutchai01/solpay-core-service/tree/main/internal/core/services): `internal/core/services`
- [KYC & user service](https://github.com/narutchai01/solpay-core-service/blob/main/internal/core/services/user_service.go): `internal/core/services/user_service.go`
- [Quote & swap](https://github.com/narutchai01/solpay-core-service/blob/main/internal/core/services/quote_service.go): `internal/core/services/quote_service.go`
- [On-chain service](https://github.com/narutchai01/solpay-core-service/blob/main/internal/core/services/onchain_service.go): `internal/core/services/onchain_service.go`
- [Balance service](https://github.com/narutchai01/solpay-core-service/blob/main/internal/core/services/balance_service.go): `internal/core/services/balance_service.go`

### Transaction Processing

- [Transaction orchestration](https://github.com/narutchai01/solpay-core-service/blob/main/internal/core/services/transaction_service.go): `internal/core/services/transaction_service.go`
- [RabbitMQ queues](https://github.com/narutchai01/solpay-core-service/tree/main/internal/infra/rabbitmq): `internal/infra/rabbitmq`
- [Event consumers](https://github.com/narutchai01/solpay-core-service/blob/main/internal/infra/rabbitmq/consumer.go): `internal/infra/rabbitmq/consumer.go`

### Persistence & Integrations

- [PostgreSQL](https://github.com/narutchai01/solpay-core-service/blob/main/internal/db/db.go): `internal/db/db.go`
- [Transaction repository](https://github.com/narutchai01/solpay-core-service/blob/main/internal/infra/repositories/transaction_repository.go): `internal/infra/repositories/transaction_repository.go`
- [Domain repositories](https://github.com/narutchai01/solpay-core-service/tree/main/internal/infra/repositories): `internal/infra/repositories`
- [Solana transaction client](https://github.com/narutchai01/solpay-core-service/blob/main/internal/infra/solana/transaction_repository.go): `internal/infra/solana/transaction_repository.go`
- [Payment gateway](https://github.com/narutchai01/solpay-core-service/blob/main/internal/infra/payment/omise_gateway.go): `internal/infra/payment/omise_gateway.go`
- [Slip generation](https://github.com/narutchai01/solpay-core-service/blob/main/internal/utils/slip.go): `internal/utils/slip.go`
- [Supabase storage](https://github.com/narutchai01/solpay-core-service/blob/main/internal/infra/supabase/upload.go): `internal/infra/supabase/upload.go`

### Realtime

- [WebSocket hub](https://github.com/narutchai01/solpay-core-service/blob/main/internal/websocket/hub.go): `internal/websocket/hub.go`
- [WebSocket routes](https://github.com/narutchai01/solpay-core-service/blob/main/internal/routes/websocket_route.go): `internal/routes/websocket_route.go`

### Other components

- **User**
- **Supabase**

## Connections

- User → HTTP server: sends requests
- HTTP server → API routes: configures routes (evidence: `internal/server/server.go`)
- API routes → Transaction handlers: routes transactions
- API routes → User handlers: routes users
- API routes → Account handlers: routes accounts
- Transaction handlers → Transaction orchestration: invokes (evidence: `internal/handler/transaction_handler.go`)
- User handlers → KYC & user service: invokes (evidence: `internal/handler/user_handler.go`)
- Account handlers → Domain services: invokes (evidence: `internal/handler/account_handler.go`)
- HTTP server → RabbitMQ queues: sets up queues (evidence: `internal/server/server.go`)
- HTTP server → WebSocket hub: starts (evidence: `internal/server/server.go`)
- HTTP server → WebSocket routes: configures (evidence: `internal/server/server.go`)
- Transaction orchestration → Transaction repository: records transaction
- Transaction repository → PostgreSQL: reads and writes (evidence: `internal/infra/repositories/transaction_repository.go`)
- Transaction orchestration → RabbitMQ queues: publishes events
- RabbitMQ queues → Event consumers: dispatches messages
- Event consumers → Transaction orchestration: reports status
- Event consumers → Solana transaction client: dispatches on-chain work
- Event consumers → Balance service: dispatches balance work
- Event consumers → Payment gateway: dispatches payment work
- Event consumers → PostgreSQL: updates transaction
- KYC & user service → Supabase storage: uploads KYC images (evidence: `internal/core/services/user_service.go`)
- Supabase storage → Supabase: stores files
- Transaction orchestration → Slip generation: generates slip
- Transaction orchestration → Supabase storage: uploads slip
- Transaction orchestration → WebSocket hub: notifies clients
- API routes → Quote & swap: exposes quotes and swaps (evidence: `internal/routes/routes.go`)
- Quote & swap → Domain repositories: uses repositories
- On-chain service → Solana transaction client: uses client
- Balance service → Domain repositories: uses repositories
- KYC & user service → Domain repositories: uses repositories
