# mrbeliaev/task-market-backend architecture

> Architecture diagram of the GitHub repository mrbeliaev/task-market-backend, 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/mrbeliaev/task-market-backend
- Repository: https://github.com/mrbeliaev/task-market-backend

## Overview

TaskMarket Backend is an Express API and WebSocket service for off-chain task metadata, applications, comments, and task/dispute chat; Ethereum contracts retain escrow and state transitions. HTTP requests enter at the server, dispatch through route handlers and controllers to services, which validate signatures or business rules and access PostgreSQL. Admin access checks contract roles on-chain. The README documents WebSocket chat and signed mutations; service internals for chat, disputes, and chain routes were not sampled, so their detailed wiring is limited to documented behavior and visible route/controller declarations.

Main entry points: [`src/index.ts`](https://github.com/mrbeliaev/task-market-backend/blob/main/src/index.ts) (Express server), [`src/services/admin.service.ts`](https://github.com/mrbeliaev/task-market-backend/blob/main/src/services/admin.service.ts) (Admin and chains), [`src/validation`](https://github.com/mrbeliaev/task-market-backend/tree/main/src/validation) (Request schemas), [`src/controllers/task.controller.ts`](https://github.com/mrbeliaev/task-market-backend/blob/main/src/controllers/task.controller.ts) (Task controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP API"]
  node_server["Express server<br/>[index.ts]"]
  node_taskroutes["Task routes<br/>[task.routes.ts]"]
  node_taskcontroller["Task controller<br/>[task.controller.ts]"]
  node_adminroutes["Admin routes<br/>[admin.routes.ts]"]
  node_admincontroller["Admin controller"]
  node_chatroutes["Chat routes<br/>[chat.routes.ts]"]
  node_chatcontroller["Chat controller<br/>[chat.controller.ts]"]
  node_disputeroutes["Dispute routes<br/>[dispute.routes.ts]"]
  node_disputecontroller["Dispute controller"]
  node_chainroutes["Chain routes<br/>[chain.routes.ts]"]
end

subgraph group_domain["Marketplace Services"]
  node_tasks["Task operations<br/>[task.service.ts]"]
  node_adminservice["Admin and chains<br/>[admin.service.ts]"]
  node_chatservice["Task chat<br/>[chat.service.ts]"]
  node_disputeservice["Dispute chat<br/>[dispute.service.ts]"]
  node_signature["Signature recovery"]
end

subgraph group_infra["Shared Infrastructure"]
  node_validation["Request schemas"]
  node_database[("PostgreSQL<br/>[db.ts]")]
  node_upload["File upload<br/>[upload.ts]"]
end

subgraph group_realtime["Realtime and Integrations"]
  node_websocket["WebSocket hub<br/>[websocket.ts]"]
  node_telegram["Telegram alerts"]
end

node_client(("API client"))
node_admin(("Admin client"))
node_rpc{{"Ethereum RPC"}}
node_socketclient(("WebSocket client"))
node_telegramservice{{"Telegram"}}

node_client -->|"sends HTTP"| node_server
node_admin -->|"sends HTTP"| node_server
node_server -->|"mounts API"| node_taskroutes
node_server -->|"mounts API"| node_adminroutes
node_server -->|"mounts API"| node_chatroutes
node_server -->|"mounts API"| node_disputeroutes
node_server -->|"mounts API"| node_chainroutes
node_taskroutes -->|"dispatches"| node_taskcontroller
node_taskcontroller -->|"calls"| node_tasks
node_taskcontroller -->|"parses input"| node_validation
node_tasks -->|"reads and writes"| node_database
node_tasks -->|"verifies signatures"| node_signature
node_adminroutes -->|"dispatches"| node_admincontroller
node_admincontroller -->|"calls"| node_adminservice
node_admincontroller -->|"parses input"| node_validation
node_adminroutes -->|"checks admin role"| node_adminservice
node_adminservice -->|"reads and writes"| node_database
node_adminservice -->|"reads contract roles"| node_rpc
node_chainroutes -->|"loads public chains"| node_adminservice
node_chatroutes -->|"dispatches"| node_chatcontroller
node_chatroutes -->|"accepts attachment"| node_upload
node_chatcontroller -->|"calls"| node_chatservice
node_chatcontroller -->|"parses input"| node_validation
node_disputeroutes -->|"dispatches"| node_disputecontroller
node_disputeroutes -->|"accepts attachment"| node_upload
node_disputecontroller -->|"calls"| node_disputeservice
node_disputecontroller -->|"parses input"| node_validation
node_server -->|"attaches to server"| node_websocket
node_socketclient -->|"connects"| node_websocket
node_server -.->|"sends error alerts"| node_telegram
node_telegram -.->|"notifies"| node_telegramservice

click node_server "https://github.com/mrbeliaev/task-market-backend/blob/main/src/index.ts"
click node_taskroutes "https://github.com/mrbeliaev/task-market-backend/blob/main/src/routes/task.routes.ts"
click node_taskcontroller "https://github.com/mrbeliaev/task-market-backend/blob/main/src/controllers/task.controller.ts"
click node_adminroutes "https://github.com/mrbeliaev/task-market-backend/blob/main/src/routes/admin.routes.ts"
click node_admincontroller "https://github.com/mrbeliaev/task-market-backend/blob/main/src/controllers/admin.controller.ts"
click node_chatroutes "https://github.com/mrbeliaev/task-market-backend/blob/main/src/routes/chat.routes.ts"
click node_chatcontroller "https://github.com/mrbeliaev/task-market-backend/blob/main/src/controllers/chat.controller.ts"
click node_disputeroutes "https://github.com/mrbeliaev/task-market-backend/blob/main/src/routes/dispute.routes.ts"
click node_disputecontroller "https://github.com/mrbeliaev/task-market-backend/blob/main/src/controllers/dispute.controller.ts"
click node_chainroutes "https://github.com/mrbeliaev/task-market-backend/blob/main/src/routes/chain.routes.ts"
click node_tasks "https://github.com/mrbeliaev/task-market-backend/blob/main/src/services/task.service.ts"
click node_adminservice "https://github.com/mrbeliaev/task-market-backend/blob/main/src/services/admin.service.ts"
click node_chatservice "https://github.com/mrbeliaev/task-market-backend/blob/main/src/services/chat.service.ts"
click node_disputeservice "https://github.com/mrbeliaev/task-market-backend/blob/main/src/services/dispute.service.ts"
click node_signature "https://github.com/mrbeliaev/task-market-backend/blob/main/src/services/signature.service.ts"
click node_validation "https://github.com/mrbeliaev/task-market-backend/tree/main/src/validation"
click node_database "https://github.com/mrbeliaev/task-market-backend/blob/main/src/lib/db.ts"
click node_upload "https://github.com/mrbeliaev/task-market-backend/blob/main/src/lib/upload.ts"
click node_websocket "https://github.com/mrbeliaev/task-market-backend/blob/main/src/lib/websocket.ts"
click node_telegram "https://github.com/mrbeliaev/task-market-backend/blob/main/src/services/telegram.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_server,node_taskroutes,node_taskcontroller,node_adminroutes,node_admincontroller,node_chatroutes,node_chatcontroller,node_disputeroutes,node_disputecontroller,node_chainroutes,node_client,node_admin,node_socketclient toneBlue
class node_tasks,node_adminservice,node_chatservice,node_disputeservice,node_signature toneAmber
class node_validation,node_database,node_upload toneMint
class node_websocket,node_telegram toneRose
class node_rpc,node_telegramservice toneIndigo
```

## Components

### HTTP API

- [Express server](https://github.com/mrbeliaev/task-market-backend/blob/main/src/index.ts): `src/index.ts`
- [Task routes](https://github.com/mrbeliaev/task-market-backend/blob/main/src/routes/task.routes.ts): `src/routes/task.routes.ts`
- [Task controller](https://github.com/mrbeliaev/task-market-backend/blob/main/src/controllers/task.controller.ts): `src/controllers/task.controller.ts`
- [Admin routes](https://github.com/mrbeliaev/task-market-backend/blob/main/src/routes/admin.routes.ts): `src/routes/admin.routes.ts`
- [Admin controller](https://github.com/mrbeliaev/task-market-backend/blob/main/src/controllers/admin.controller.ts): `src/controllers/admin.controller.ts`
- [Chat routes](https://github.com/mrbeliaev/task-market-backend/blob/main/src/routes/chat.routes.ts): `src/routes/chat.routes.ts`
- [Chat controller](https://github.com/mrbeliaev/task-market-backend/blob/main/src/controllers/chat.controller.ts): `src/controllers/chat.controller.ts`
- [Dispute routes](https://github.com/mrbeliaev/task-market-backend/blob/main/src/routes/dispute.routes.ts): `src/routes/dispute.routes.ts`
- [Dispute controller](https://github.com/mrbeliaev/task-market-backend/blob/main/src/controllers/dispute.controller.ts): `src/controllers/dispute.controller.ts`
- [Chain routes](https://github.com/mrbeliaev/task-market-backend/blob/main/src/routes/chain.routes.ts): `src/routes/chain.routes.ts`

### Marketplace Services

- [Task operations](https://github.com/mrbeliaev/task-market-backend/blob/main/src/services/task.service.ts): `src/services/task.service.ts`
- [Admin and chains](https://github.com/mrbeliaev/task-market-backend/blob/main/src/services/admin.service.ts): `src/services/admin.service.ts`
- [Task chat](https://github.com/mrbeliaev/task-market-backend/blob/main/src/services/chat.service.ts): `src/services/chat.service.ts`
- [Dispute chat](https://github.com/mrbeliaev/task-market-backend/blob/main/src/services/dispute.service.ts): `src/services/dispute.service.ts`
- [Signature recovery](https://github.com/mrbeliaev/task-market-backend/blob/main/src/services/signature.service.ts): `src/services/signature.service.ts`

### Shared Infrastructure

- [Request schemas](https://github.com/mrbeliaev/task-market-backend/tree/main/src/validation): `src/validation`
- [PostgreSQL](https://github.com/mrbeliaev/task-market-backend/blob/main/src/lib/db.ts): `src/lib/db.ts`
- [File upload](https://github.com/mrbeliaev/task-market-backend/blob/main/src/lib/upload.ts): `src/lib/upload.ts`

### Realtime and Integrations

- [WebSocket hub](https://github.com/mrbeliaev/task-market-backend/blob/main/src/lib/websocket.ts): `src/lib/websocket.ts`
- [Telegram alerts](https://github.com/mrbeliaev/task-market-backend/blob/main/src/services/telegram.service.ts): `src/services/telegram.service.ts`

### Other components

- **API client**
- **Admin client**
- **Ethereum RPC**
- **WebSocket client**
- **Telegram**

## Connections

- API client → Express server: sends HTTP
- Admin client → Express server: sends HTTP
- Express server → Task routes: mounts API
- Express server → Admin routes: mounts API
- Express server → Chat routes: mounts API
- Express server → Dispute routes: mounts API
- Express server → Chain routes: mounts API
- Task routes → Task controller: dispatches
- Task controller → Task operations: calls
- Task controller → Request schemas: parses input
- Task operations → PostgreSQL: reads and writes
- Task operations → Signature recovery: verifies signatures
- Admin routes → Admin controller: dispatches
- Admin controller → Admin and chains: calls
- Admin controller → Request schemas: parses input
- Admin routes → Admin and chains: checks admin role
- Admin and chains → PostgreSQL: reads and writes
- Admin and chains → Ethereum RPC: reads contract roles
- Chain routes → Admin and chains: loads public chains
- Chat routes → Chat controller: dispatches
- Chat routes → File upload: accepts attachment
- Chat controller → Task chat: calls
- Chat controller → Request schemas: parses input
- Dispute routes → Dispute controller: dispatches
- Dispute routes → File upload: accepts attachment
- Dispute controller → Dispute chat: calls
- Dispute controller → Request schemas: parses input
- Express server → WebSocket hub: attaches to server
- WebSocket client → WebSocket hub: connects
- Express server → Telegram alerts: sends error alerts
- Telegram alerts → Telegram: notifies