# jye-a-dev/trustpassz architecture

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

- Interactive diagram: https://gitdiagram.com/jye-a-dev/trustpassz
- Repository: https://github.com/jye-a-dev/trustpassz

## Overview

TrustPassz is a Web3 digital-escrow platform with user web and mobile clients, an admin portal, a NestJS API, an AI arbitration service, and on-chain escrow contracts. Its documented lifecycle runs from deal creation and deposit through inspection, settlement, or dispute and refund; disputes may be analyzed by AI and resolved by an on-chain relayer. Sampled source confirms selected API, authentication, and AI-engine calls; several subsystem links below rely on the README’s explicit architecture and lifecycle descriptions.

Main entry points: [`apps/server/src/main.ts`](https://github.com/jye-a-dev/trustpassz/blob/main/apps/server/src/main.ts) (REST API), [`apps/server/src/modules/payments/payments.service.ts`](https://github.com/jye-a-dev/trustpassz/blob/main/apps/server/src/modules/payments/payments.service.ts) (Deposits and payments), [`apps/server/src/modules/disputes`](https://github.com/jye-a-dev/trustpassz/tree/main/apps/server/src/modules/disputes) (Dispute handling), [`apps/ai_pipeline/engines/arbitrator_engine.py`](https://github.com/jye-a-dev/trustpassz/blob/main/apps/ai_pipeline/engines/arbitrator_engine.py) (Verdict engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client applications"]
  node_userweb["User web portal"]
  node_mobile["Mobile client<br/>[App.tsx]"]
  node_admin["Admin portal"]
end

subgraph group_api["Platform API"]
  node_server["REST API<br/>[main.ts]"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_deals["Deal lifecycle<br/>[deals.service.ts]"]
  node_payments["Deposits and payments"]
  node_disputes["Dispute handling"]
  node_bargains["Deal bargaining"]
  node_orders["Orders"]
  node_analytics["Analytics"]
  node_payment_service["PayOS and VietQR<br/>[vietqr.service.ts]"]
end

subgraph group_ai["AI arbitration"]
  node_arbitration["Arbitration API<br/>[arbitration.py]"]
  node_arbengine["Verdict engine"]
  node_suggestions["Deal suggestions"]
  node_engine["Constrained inference<br/>[outlines_engine.py]"]
end

subgraph group_chain["Escrow settlement"]
  node_relayer["Chain relayer"]
  node_contract["Digital escrow contract<br/>[lib.rs]"]
end

subgraph group_state["Platform state and evidence"]
  node_database[("PostgreSQL data<br/>[prisma.service.ts]")]
  node_evidence[("Evidence storage")]
end

node_user(("Buyer or seller"))

node_user -->|"uses"| node_userweb
node_user -->|"uses"| node_mobile
node_userweb -->|"calls API"| node_server
node_mobile -.->|"calls API"| node_server
node_admin -->|"calls API"| node_server
node_server -.->|"routes authentication"| node_auth
node_auth -->|"upserts users"| node_database
node_server -->|"routes deal requests"| node_deals
node_deals -.->|"persists deals"| node_database
node_server -->|"routes payment requests"| node_payments
node_payments -->|"creates VietQR checkout"| node_payment_service
node_payments -.->|"records deposits"| node_database
node_server -.->|"routes disputes"| node_disputes
node_disputes -.->|"stores evidence"| node_evidence
node_server -->|"routes bargaining"| node_bargains
node_server -.->|"routes orders"| node_orders
node_server -.->|"serves analytics"| node_analytics
node_disputes -->|"submits dispute"| node_arbitration
node_arbitration -->|"dispatches verdict"| node_arbengine
node_arbengine -->|"runs inference"| node_engine
node_engine -->|"supports suggestions"| node_suggestions
node_arbengine -->|"fetches image URLs"| node_evidence
node_server -->|"dispatches resolution"| node_relayer
node_relayer -->|"calls resolveDispute"| node_contract
node_contract -.->|"settles or refunds"| node_user

click node_userweb "https://github.com/jye-a-dev/trustpassz/tree/main/apps/cl_user/src/app"
click node_mobile "https://github.com/jye-a-dev/trustpassz/blob/main/apps/mb_user/src/App.tsx"
click node_admin "https://github.com/jye-a-dev/trustpassz/tree/main/apps/cl_admin/src/app/(dashboard)"
click node_server "https://github.com/jye-a-dev/trustpassz/blob/main/apps/server/src/main.ts"
click node_auth "https://github.com/jye-a-dev/trustpassz/blob/main/apps/server/src/modules/auth/auth.service.ts"
click node_deals "https://github.com/jye-a-dev/trustpassz/blob/main/apps/server/src/modules/deals/deals.service.ts"
click node_payments "https://github.com/jye-a-dev/trustpassz/blob/main/apps/server/src/modules/payments/payments.service.ts"
click node_disputes "https://github.com/jye-a-dev/trustpassz/tree/main/apps/server/src/modules/disputes"
click node_bargains "https://github.com/jye-a-dev/trustpassz/tree/main/apps/server/src/modules/bargains"
click node_orders "https://github.com/jye-a-dev/trustpassz/tree/main/apps/server/src/modules/orders"
click node_analytics "https://github.com/jye-a-dev/trustpassz/tree/main/apps/server/src/modules/analytics"
click node_arbitration "https://github.com/jye-a-dev/trustpassz/blob/main/apps/ai_pipeline/routers/arbitration.py"
click node_arbengine "https://github.com/jye-a-dev/trustpassz/blob/main/apps/ai_pipeline/engines/arbitrator_engine.py"
click node_suggestions "https://github.com/jye-a-dev/trustpassz/blob/main/apps/ai_pipeline/services/suggestion_service.py"
click node_engine "https://github.com/jye-a-dev/trustpassz/blob/main/apps/ai_pipeline/core/outlines_engine.py"
click node_relayer "https://github.com/jye-a-dev/trustpassz/blob/main/apps/server/src/oracle-relayer/oracle-relayer.service.ts"
click node_contract "https://github.com/jye-a-dev/trustpassz/blob/main/packages/contracts-solana/programs/trustpassz-escrow/src/lib.rs"
click node_database "https://github.com/jye-a-dev/trustpassz/blob/main/apps/server/src/database/prisma.service.ts"
click node_evidence "https://github.com/jye-a-dev/trustpassz/blob/main/apps/server/src/integrations/supabase/supabase.service.ts"
click node_payment_service "https://github.com/jye-a-dev/trustpassz/blob/main/apps/server/src/modules/payments/services/vietqr.service.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_userweb,node_mobile,node_admin toneBlue
class node_server,node_auth,node_deals,node_payments,node_disputes,node_bargains,node_orders,node_analytics,node_payment_service toneAmber
class node_arbitration,node_arbengine,node_suggestions,node_engine toneMint
class node_relayer,node_contract toneRose
class node_database,node_evidence,node_user toneIndigo
```

## Components

### Client applications

- [User web portal](https://github.com/jye-a-dev/trustpassz/tree/main/apps/cl_user/src/app): `apps/cl_user/src/app`
- [Mobile client](https://github.com/jye-a-dev/trustpassz/blob/main/apps/mb_user/src/App.tsx): `apps/mb_user/src/App.tsx`
- [Admin portal](https://github.com/jye-a-dev/trustpassz/tree/main/apps/cl_admin/src/app/(dashboard)): `apps/cl_admin/src/app/(dashboard)`

### Platform API

- [REST API](https://github.com/jye-a-dev/trustpassz/blob/main/apps/server/src/main.ts): `apps/server/src/main.ts`
- [Authentication](https://github.com/jye-a-dev/trustpassz/blob/main/apps/server/src/modules/auth/auth.service.ts): `apps/server/src/modules/auth/auth.service.ts`
- [Deal lifecycle](https://github.com/jye-a-dev/trustpassz/blob/main/apps/server/src/modules/deals/deals.service.ts): `apps/server/src/modules/deals/deals.service.ts`
- [Deposits and payments](https://github.com/jye-a-dev/trustpassz/blob/main/apps/server/src/modules/payments/payments.service.ts): `apps/server/src/modules/payments/payments.service.ts`
- [Dispute handling](https://github.com/jye-a-dev/trustpassz/tree/main/apps/server/src/modules/disputes): `apps/server/src/modules/disputes`
- [Deal bargaining](https://github.com/jye-a-dev/trustpassz/tree/main/apps/server/src/modules/bargains): `apps/server/src/modules/bargains`
- [Orders](https://github.com/jye-a-dev/trustpassz/tree/main/apps/server/src/modules/orders): `apps/server/src/modules/orders`
- [Analytics](https://github.com/jye-a-dev/trustpassz/tree/main/apps/server/src/modules/analytics): `apps/server/src/modules/analytics`
- [PayOS and VietQR](https://github.com/jye-a-dev/trustpassz/blob/main/apps/server/src/modules/payments/services/vietqr.service.ts): `apps/server/src/modules/payments/services/vietqr.service.ts`

### AI arbitration

- [Arbitration API](https://github.com/jye-a-dev/trustpassz/blob/main/apps/ai_pipeline/routers/arbitration.py): `apps/ai_pipeline/routers/arbitration.py`
- [Verdict engine](https://github.com/jye-a-dev/trustpassz/blob/main/apps/ai_pipeline/engines/arbitrator_engine.py): `apps/ai_pipeline/engines/arbitrator_engine.py`
- [Deal suggestions](https://github.com/jye-a-dev/trustpassz/blob/main/apps/ai_pipeline/services/suggestion_service.py): `apps/ai_pipeline/services/suggestion_service.py`
- [Constrained inference](https://github.com/jye-a-dev/trustpassz/blob/main/apps/ai_pipeline/core/outlines_engine.py): `apps/ai_pipeline/core/outlines_engine.py`

### Escrow settlement

- [Chain relayer](https://github.com/jye-a-dev/trustpassz/blob/main/apps/server/src/oracle-relayer/oracle-relayer.service.ts): `apps/server/src/oracle-relayer/oracle-relayer.service.ts`
- [Digital escrow contract](https://github.com/jye-a-dev/trustpassz/blob/main/packages/contracts-solana/programs/trustpassz-escrow/src/lib.rs): `packages/contracts-solana/programs/trustpassz-escrow/src/lib.rs`

### Platform state and evidence

- [PostgreSQL data](https://github.com/jye-a-dev/trustpassz/blob/main/apps/server/src/database/prisma.service.ts): `apps/server/src/database/prisma.service.ts`
- [Evidence storage](https://github.com/jye-a-dev/trustpassz/blob/main/apps/server/src/integrations/supabase/supabase.service.ts): `apps/server/src/integrations/supabase/supabase.service.ts`

### Other components

- **Buyer or seller**

## Connections

- Buyer or seller → User web portal: uses
- Buyer or seller → Mobile client: uses
- User web portal → REST API: calls API
- Mobile client → REST API: calls API
- Admin portal → REST API: calls API
- REST API → Authentication: routes authentication
- Authentication → PostgreSQL data: upserts users (evidence: `apps/server/src/modules/auth/auth.service.ts`)
- REST API → Deal lifecycle: routes deal requests
- Deal lifecycle → PostgreSQL data: persists deals
- REST API → Deposits and payments: routes payment requests
- Deposits and payments → PayOS and VietQR: creates VietQR checkout (evidence: `apps/server/src/modules/payments/payments.controller.ts`)
- Deposits and payments → PostgreSQL data: records deposits
- REST API → Dispute handling: routes disputes
- Dispute handling → Evidence storage: stores evidence
- REST API → Deal bargaining: routes bargaining (evidence: `apps/server/src/modules/bargains/bargains.controller.ts`)
- REST API → Orders: routes orders
- REST API → Analytics: serves analytics
- Dispute handling → Arbitration API: submits dispute
- Arbitration API → Verdict engine: dispatches verdict (evidence: `apps/ai_pipeline/routers/arbitration.py`)
- Verdict engine → Constrained inference: runs inference (evidence: `apps/ai_pipeline/engines/arbitrator_engine.py`)
- Constrained inference → Deal suggestions: supports suggestions
- Verdict engine → Evidence storage: fetches image URLs (evidence: `apps/ai_pipeline/engines/arbitrator_engine.py`)
- REST API → Chain relayer: dispatches resolution
- Chain relayer → Digital escrow contract: calls resolveDispute
- Digital escrow contract → Buyer or seller: settles or refunds
