# ntbfain/dice architecture

> Architecture diagram of the GitHub repository ntbfain/dice, 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/ntbfain/dice
- Repository: https://github.com/ntbfain/dice

## Overview

DICE is a freelance-art commission and live-auction marketplace. Clients browse artist portfolios or auctions, commission work or bid, then track order stages, chat, review drafts, pay milestones, and receive completed files; artists and administrators manage those workflows. The frontend serves localized pages and communicates with FastAPI over REST and WebSockets. The README documents watermarking, protected master-file delivery, and milestone payments; sampled source confirms auction-to-order creation, notifications, authentication, and WebSocket updates. Several feature routers were not sampled, so their internal call relationships are not asserted.

Main entry points: [`backend/main.py`](https://github.com/ntbfain/dice/blob/main/backend/main.py) (FastAPI Application), [`frontend/src/app/[locale]`](https://github.com/ntbfain/dice/tree/main/frontend/src/app/%5Blocale%5D) (Marketplace and Dashboards), [`backend/services/auction_service.py`](https://github.com/ntbfain/dice/blob/main/backend/services/auction_service.py) (Auction Lifecycle), [`backend/core/db.py`](https://github.com/ntbfain/dice/blob/main/backend/core/db.py) (Relational Database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web Client"]
  node_web_pages["Marketplace and Dashboards"]
  node_web_api["API Client<br/>[api.ts]"]
  node_web_market_api["Marketplace API Client<br/>[marketplaceApi.ts]"]
  node_websocket_client["Realtime Client"]
  node_localization["Locale Routing<br/>[routing.ts]"]
end

subgraph group_api["API Workflows"]
  node_app_entry["FastAPI Application<br/>[main.py]"]
  node_auth_routes["Authentication and Users<br/>[auth.py]"]
  node_auction_routes["Auction Endpoints<br/>[auctions.py]"]
  node_order_routes["Orders and Queue<br/>[orders.py]"]
  node_artist_routes["Artist and Portfolio<br/>[artists.py]"]
  node_admin_routes["Analytics and Admin<br/>[analytics.py]"]
end

subgraph group_domain["Marketplace Services"]
  node_auction_service["Auction Lifecycle<br/>[auction_service.py]"]
  node_order_service["Payment State<br/>[order_service.py]"]
  node_notification_service["Notifications"]
  node_watermark["Image Protection<br/>[watermark.py]"]
end

subgraph group_state["Persistence and Realtime"]
  node_database[("Relational Database<br/>[db.py]")]
  node_ws_manager["WebSocket Manager<br/>[websocket.py]"]
  node_protected_files[("Protected File Storage")]
end

node_client_actor(("Client or Artist"))

node_client_actor -->|"uses"| node_web_pages
node_web_pages -->|"routes by locale"| node_localization
node_web_pages -->|"requests REST"| node_web_api
node_web_pages -->|"requests marketplace"| node_web_market_api
node_web_pages -->|"subscribes realtime"| node_websocket_client
node_web_api -->|"sends REST"| node_app_entry
node_web_market_api -->|"sends REST"| node_app_entry
node_websocket_client -->|"opens socket"| node_app_entry
node_app_entry -->|"dispatches routes"| node_auth_routes
node_app_entry -->|"dispatches routes"| node_auction_routes
node_app_entry -->|"dispatches routes"| node_order_routes
node_app_entry -->|"dispatches routes"| node_artist_routes
node_app_entry -->|"dispatches routes"| node_admin_routes
node_app_entry -->|"initializes database"| node_database
node_app_entry -->|"connects sockets"| node_ws_manager
node_auction_service -->|"reads and writes"| node_database
node_auction_service -.->|"checks payment state"| node_order_service
node_auction_service -->|"creates notifications"| node_notification_service
node_auction_service -->|"broadcasts events"| node_ws_manager
node_notification_service -->|"stores notifications"| node_database
node_notification_service -->|"sends messages"| node_ws_manager
node_order_service -->|"reads invoices"| node_database
node_websocket_client -->|"receives events"| node_ws_manager
node_order_routes -.->|"handles delivery"| node_protected_files
node_order_routes -.->|"protects previews"| node_watermark
node_auction_routes -.->|"uses lifecycle"| node_auction_service

click node_web_pages "https://github.com/ntbfain/dice/tree/main/frontend/src/app/%5Blocale%5D"
click node_web_api "https://github.com/ntbfain/dice/blob/main/frontend/src/lib/api.ts"
click node_web_market_api "https://github.com/ntbfain/dice/blob/main/frontend/src/lib/marketplaceApi.ts"
click node_websocket_client "https://github.com/ntbfain/dice/blob/main/frontend/src/components/WebSocketContext.tsx"
click node_localization "https://github.com/ntbfain/dice/blob/main/frontend/src/i18n/routing.ts"
click node_app_entry "https://github.com/ntbfain/dice/blob/main/backend/main.py"
click node_auth_routes "https://github.com/ntbfain/dice/blob/main/backend/api/routers/auth.py"
click node_auction_routes "https://github.com/ntbfain/dice/blob/main/backend/api/routers/auctions.py"
click node_order_routes "https://github.com/ntbfain/dice/blob/main/backend/api/routers/orders.py"
click node_artist_routes "https://github.com/ntbfain/dice/blob/main/backend/api/routers/artists.py"
click node_admin_routes "https://github.com/ntbfain/dice/blob/main/backend/api/routers/analytics.py"
click node_auction_service "https://github.com/ntbfain/dice/blob/main/backend/services/auction_service.py"
click node_order_service "https://github.com/ntbfain/dice/blob/main/backend/services/order_service.py"
click node_notification_service "https://github.com/ntbfain/dice/blob/main/backend/services/notification_service.py"
click node_watermark "https://github.com/ntbfain/dice/blob/main/backend/core/watermark.py"
click node_database "https://github.com/ntbfain/dice/blob/main/backend/core/db.py"
click node_ws_manager "https://github.com/ntbfain/dice/blob/main/backend/core/websocket.py"

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_web_pages,node_web_api,node_web_market_api,node_websocket_client,node_localization,node_client_actor toneBlue
class node_app_entry,node_auth_routes,node_auction_routes,node_order_routes,node_artist_routes,node_admin_routes toneAmber
class node_auction_service,node_order_service,node_notification_service,node_watermark toneMint
class node_database,node_ws_manager,node_protected_files toneRose
```

## Components

### Web Client

- [Marketplace and Dashboards](https://github.com/ntbfain/dice/tree/main/frontend/src/app/%5Blocale%5D): `frontend/src/app/[locale]`
- [API Client](https://github.com/ntbfain/dice/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Marketplace API Client](https://github.com/ntbfain/dice/blob/main/frontend/src/lib/marketplaceApi.ts): `frontend/src/lib/marketplaceApi.ts`
- [Realtime Client](https://github.com/ntbfain/dice/blob/main/frontend/src/components/WebSocketContext.tsx): `frontend/src/components/WebSocketContext.tsx`
- [Locale Routing](https://github.com/ntbfain/dice/blob/main/frontend/src/i18n/routing.ts): `frontend/src/i18n/routing.ts`

### API Workflows

- [FastAPI Application](https://github.com/ntbfain/dice/blob/main/backend/main.py): `backend/main.py`
- [Authentication and Users](https://github.com/ntbfain/dice/blob/main/backend/api/routers/auth.py): `backend/api/routers/auth.py`
- [Auction Endpoints](https://github.com/ntbfain/dice/blob/main/backend/api/routers/auctions.py): `backend/api/routers/auctions.py`
- [Orders and Queue](https://github.com/ntbfain/dice/blob/main/backend/api/routers/orders.py): `backend/api/routers/orders.py`
- [Artist and Portfolio](https://github.com/ntbfain/dice/blob/main/backend/api/routers/artists.py): `backend/api/routers/artists.py`
- [Analytics and Admin](https://github.com/ntbfain/dice/blob/main/backend/api/routers/analytics.py): `backend/api/routers/analytics.py`

### Marketplace Services

- [Auction Lifecycle](https://github.com/ntbfain/dice/blob/main/backend/services/auction_service.py): `backend/services/auction_service.py`
- [Payment State](https://github.com/ntbfain/dice/blob/main/backend/services/order_service.py): `backend/services/order_service.py`
- [Notifications](https://github.com/ntbfain/dice/blob/main/backend/services/notification_service.py): `backend/services/notification_service.py`
- [Image Protection](https://github.com/ntbfain/dice/blob/main/backend/core/watermark.py): `backend/core/watermark.py`

### Persistence and Realtime

- [Relational Database](https://github.com/ntbfain/dice/blob/main/backend/core/db.py): `backend/core/db.py`
- [WebSocket Manager](https://github.com/ntbfain/dice/blob/main/backend/core/websocket.py): `backend/core/websocket.py`
- **Protected File Storage**

### Other components

- **Client or Artist**

## Connections

- Client or Artist → Marketplace and Dashboards: uses
- Marketplace and Dashboards → Locale Routing: routes by locale
- Marketplace and Dashboards → API Client: requests REST
- Marketplace and Dashboards → Marketplace API Client: requests marketplace
- Marketplace and Dashboards → Realtime Client: subscribes realtime
- API Client → FastAPI Application: sends REST
- Marketplace API Client → FastAPI Application: sends REST
- Realtime Client → FastAPI Application: opens socket
- FastAPI Application → Authentication and Users: dispatches routes
- FastAPI Application → Auction Endpoints: dispatches routes
- FastAPI Application → Orders and Queue: dispatches routes
- FastAPI Application → Artist and Portfolio: dispatches routes
- FastAPI Application → Analytics and Admin: dispatches routes
- FastAPI Application → Relational Database: initializes database
- FastAPI Application → WebSocket Manager: connects sockets
- Auction Lifecycle → Relational Database: reads and writes
- Auction Lifecycle → Payment State: checks payment state
- Auction Lifecycle → Notifications: creates notifications
- Auction Lifecycle → WebSocket Manager: broadcasts events
- Notifications → Relational Database: stores notifications
- Notifications → WebSocket Manager: sends messages
- Payment State → Relational Database: reads invoices
- Realtime Client → WebSocket Manager: receives events
- Orders and Queue → Protected File Storage: handles delivery
- Orders and Queue → Image Protection: protects previews
- Auction Endpoints → Auction Lifecycle: uses lifecycle