# outlier1217/quilvion-multichain-testnet architecture

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

- Interactive diagram: https://gitdiagram.com/outlier1217/quilvion-multichain-testnet
- Repository: https://github.com/outlier1217/quilvion-multichain-testnet

## Overview

Quilvion is a wallet-based commerce protocol: buyers and merchants use chain-specific Next.js apps to discover products, transact through escrow, manage orders and disputes, and build reputation. The FastAPI backends provide risk scoring, marketplace assistance, and admin/merchant workflows, backed by PostgreSQL and Groq; chain programs/contracts enforce on-chain commerce and settlement. The tree documents EVM and Sui frontends and a Solana program/client, while the README describes additional chain deployments. Route, transaction, and most contract excerpts were not sampled, so uncertain runtime wiring is omitted.

Main entry points: [`quilvion-backend/main.py`](https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-backend/main.py) (FastAPI service), [`quilvion-backend/app/llm/claude_client.py`](https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-backend/app/llm/claude_client.py) (Groq LLM client), [`quilvion-evm-frontend/src/app/page.tsx`](https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-evm-frontend/src/app/page.tsx) (EVM storefront), [`quilvion-sui-frontend/src/app/page.tsx`](https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-sui-frontend/src/app/page.tsx) (Sui storefront)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Commerce clients"]
  node_evm_ui["EVM storefront<br/>[page.tsx]"]
  node_sui_ui["Sui storefront<br/>[page.tsx]"]
  node_evm_tx["EVM transactions<br/>[transactions.ts]"]
  node_sui_tx["Sui transactions<br/>[transactions.ts]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_backend["AI backend"]
  node_fastapi["FastAPI service<br/>[main.py]"]
  node_risk["Fraud scoring<br/>[risk.py]"]
  node_llm_routes["AI assistance<br/>[llm.py]"]
  node_merchant_routes["Merchant workflows<br/>[merchant.py]"]
  node_dispute_routes["Dispute handling<br/>[dispute.py]"]
  node_buyer_routes["Buyer assistance<br/>[buyer.py]"]
  node_admin_routes["Admin operations<br/>[admin.py]"]
  node_orders_routes["Order API<br/>[orders.py]"]
  node_ml_model["ML model<br/>[model.py]"]
  node_groq["Groq LLM client<br/>[claude_client.py]"]
end

subgraph group_chain["Chain execution"]
  node_evm_contracts["EVM contracts"]
  node_sui_contracts["Sui contracts"]
  node_solana_program["Solana commerce<br/>[lib.rs]"]
  node_solana_client["Solana client<br/>[client.ts]"]
end

subgraph group_state["Protocol state"]
  node_db[("Commerce database<br/>[database.py]")]
end

node_buyers(("Buyers"))
node_merchants(("Merchants"))
node_groq_service{{"Groq service"}}
node_evm_chain{{"EVM network"}}
node_sui_chain{{"Sui network"}}
node_solana_chain{{"Solana network"}}

node_buyers -->|"use storefront"| node_evm_ui
node_buyers -->|"use storefront"| node_sui_ui
node_merchants -->|"manage commerce"| node_evm_ui
node_merchants -->|"manage commerce"| node_sui_ui
node_evm_ui -->|"request API"| node_api_client
node_sui_ui -->|"request API"| node_api_client
node_evm_ui -->|"initiate transactions"| node_evm_tx
node_sui_ui -->|"initiate transactions"| node_sui_tx
node_api_client -->|"HTTP requests"| node_fastapi
node_fastapi -->|"dispatches"| node_risk
node_fastapi -->|"dispatches"| node_llm_routes
node_fastapi -->|"dispatches"| node_merchant_routes
node_fastapi -->|"dispatches"| node_dispute_routes
node_fastapi -->|"dispatches"| node_buyer_routes
node_fastapi -->|"dispatches"| node_admin_routes
node_fastapi -->|"dispatches"| node_orders_routes
node_risk -->|"scores risk"| node_ml_model
node_llm_routes -->|"requests generation"| node_groq
node_merchant_routes -->|"requests generation"| node_groq
node_dispute_routes -->|"requests generation"| node_groq
node_buyer_routes -->|"requests generation"| node_groq
node_groq -->|"calls API"| node_groq_service
node_fastapi -->|"initializes tables"| node_db
node_evm_tx -->|"submits transactions"| node_evm_chain
node_sui_tx -->|"submits transactions"| node_sui_chain
node_solana_client -->|"uses program"| node_solana_program
node_solana_program -->|"executes on"| node_solana_chain

click node_evm_ui "https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-evm-frontend/src/app/page.tsx"
click node_sui_ui "https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-sui-frontend/src/app/page.tsx"
click node_evm_tx "https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-evm-frontend/src/lib/evm/transactions.ts"
click node_sui_tx "https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-sui-frontend/src/lib/sui/transactions.ts"
click node_api_client "https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-evm-frontend/src/lib/api.ts"
click node_fastapi "https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-backend/main.py"
click node_risk "https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-backend/app/routes/risk.py"
click node_llm_routes "https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-backend/app/routes/llm.py"
click node_merchant_routes "https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-backend/app/routes/merchant.py"
click node_dispute_routes "https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-backend/app/routes/dispute.py"
click node_buyer_routes "https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-backend/app/routes/buyer.py"
click node_admin_routes "https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-backend/app/routes/admin.py"
click node_orders_routes "https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-backend/app/routes/orders.py"
click node_ml_model "https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-backend/app/ml/model.py"
click node_groq "https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-backend/app/llm/claude_client.py"
click node_db "https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-backend/app/database.py"
click node_evm_contracts "https://github.com/outlier1217/quilvion-multichain-testnet/tree/main/quilvion_evm"
click node_sui_contracts "https://github.com/outlier1217/quilvion-multichain-testnet/tree/main/quilvion-sui-frontend/src/lib/sui"
click node_solana_program "https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion_solana/programs/commerce-core/src/lib.rs"
click node_solana_client "https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion_solana/client/client.ts"

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_evm_ui,node_sui_ui,node_evm_tx,node_sui_tx,node_api_client,node_sui_chain toneBlue
class node_fastapi,node_risk,node_llm_routes,node_merchant_routes,node_dispute_routes,node_buyer_routes,node_admin_routes,node_orders_routes,node_ml_model,node_groq toneAmber
class node_evm_contracts,node_sui_contracts,node_solana_program,node_solana_client toneMint
class node_db toneRose
class node_buyers,node_merchants,node_groq_service,node_evm_chain,node_solana_chain toneIndigo
```

## Components

### Commerce clients

- [EVM storefront](https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-evm-frontend/src/app/page.tsx): `quilvion-evm-frontend/src/app/page.tsx`
- [Sui storefront](https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-sui-frontend/src/app/page.tsx): `quilvion-sui-frontend/src/app/page.tsx`
- [EVM transactions](https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-evm-frontend/src/lib/evm/transactions.ts): `quilvion-evm-frontend/src/lib/evm/transactions.ts`
- [Sui transactions](https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-sui-frontend/src/lib/sui/transactions.ts): `quilvion-sui-frontend/src/lib/sui/transactions.ts`
- [API client](https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-evm-frontend/src/lib/api.ts): `quilvion-evm-frontend/src/lib/api.ts`

### AI backend

- [FastAPI service](https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-backend/main.py): `quilvion-backend/main.py`
- [Fraud scoring](https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-backend/app/routes/risk.py): `quilvion-backend/app/routes/risk.py`
- [AI assistance](https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-backend/app/routes/llm.py): `quilvion-backend/app/routes/llm.py`
- [Merchant workflows](https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-backend/app/routes/merchant.py): `quilvion-backend/app/routes/merchant.py`
- [Dispute handling](https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-backend/app/routes/dispute.py): `quilvion-backend/app/routes/dispute.py`
- [Buyer assistance](https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-backend/app/routes/buyer.py): `quilvion-backend/app/routes/buyer.py`
- [Admin operations](https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-backend/app/routes/admin.py): `quilvion-backend/app/routes/admin.py`
- [Order API](https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-backend/app/routes/orders.py): `quilvion-backend/app/routes/orders.py`
- [ML model](https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-backend/app/ml/model.py): `quilvion-backend/app/ml/model.py`
- [Groq LLM client](https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-backend/app/llm/claude_client.py): `quilvion-backend/app/llm/claude_client.py`

### Chain execution

- [EVM contracts](https://github.com/outlier1217/quilvion-multichain-testnet/tree/main/quilvion_evm): `quilvion_evm`
- [Sui contracts](https://github.com/outlier1217/quilvion-multichain-testnet/tree/main/quilvion-sui-frontend/src/lib/sui): `quilvion-sui-frontend/src/lib/sui`
- [Solana commerce](https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion_solana/programs/commerce-core/src/lib.rs): `quilvion_solana/programs/commerce-core/src/lib.rs`
- [Solana client](https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion_solana/client/client.ts): `quilvion_solana/client/client.ts`

### Protocol state

- [Commerce database](https://github.com/outlier1217/quilvion-multichain-testnet/blob/main/quilvion-backend/app/database.py): `quilvion-backend/app/database.py`

### Other components

- **Buyers**
- **Merchants**
- **Groq service**
- **EVM network**
- **Sui network**
- **Solana network**

## Connections

- Buyers → EVM storefront: use storefront
- Buyers → Sui storefront: use storefront
- Merchants → EVM storefront: manage commerce
- Merchants → Sui storefront: manage commerce
- EVM storefront → API client: request API
- Sui storefront → API client: request API
- EVM storefront → EVM transactions: initiate transactions
- Sui storefront → Sui transactions: initiate transactions
- API client → FastAPI service: HTTP requests
- FastAPI service → Fraud scoring: dispatches
- FastAPI service → AI assistance: dispatches
- FastAPI service → Merchant workflows: dispatches
- FastAPI service → Dispute handling: dispatches
- FastAPI service → Buyer assistance: dispatches
- FastAPI service → Admin operations: dispatches
- FastAPI service → Order API: dispatches
- Fraud scoring → ML model: scores risk
- AI assistance → Groq LLM client: requests generation
- Merchant workflows → Groq LLM client: requests generation
- Dispute handling → Groq LLM client: requests generation
- Buyer assistance → Groq LLM client: requests generation
- Groq LLM client → Groq service: calls API
- FastAPI service → Commerce database: initializes tables
- EVM transactions → EVM network: submits transactions
- Sui transactions → Sui network: submits transactions
- Solana client → Solana commerce: uses program
- Solana commerce → Solana network: executes on