# marikk852/freelance-app architecture

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

- Interactive diagram: https://gitdiagram.com/marikk852/freelance-app
- Repository: https://github.com/marikk852/freelance-app

## Overview

SafeDeal is a Telegram Mini App for client–freelancer deals, with funds held in TON or other supported-chain escrow contracts. The main workflow runs from deal creation and freelancer acceptance through contract deployment, payment monitoring, protected delivery, client approval or dispute, and release/refund/split; profiles, notifications, subscriptions, and crystals support that flow. The graph includes documented capabilities whose route implementations were not sampled. Dashed edges mark likely integration points not directly evidenced; source excerpts are partial.

Main entry points: [`backend/services/escrowService.js`](https://github.com/marikk852/freelance-app/blob/main/backend/services/escrowService.js) (Escrow coordinator), [`database/db.js`](https://github.com/marikk852/freelance-app/blob/main/database/db.js) (PostgreSQL access), [`backend/server.js`](https://github.com/marikk852/freelance-app/blob/main/backend/server.js) (HTTP API server), [`miniapp/src/App.tsx`](https://github.com/marikk852/freelance-app/blob/main/miniapp/src/App.tsx) (Telegram Mini App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Deal experience"]
  node_miniapp["Telegram Mini App<br/>[App.tsx]"]
  node_deal_pages["Deal workflow screens"]
  node_api_client["API client<br/>[api.ts]"]
  node_bot["Telegram bot<br/>[bot.js]"]
  node_bot_deals["Bot deal handlers<br/>[deals.js]"]
end

subgraph group_api["Backend services"]
  node_server["HTTP API server<br/>[server.js]"]
  node_deal_routes["Deal and delivery routes"]
  node_auth["Telegram auth<br/>[auth.js]"]
  node_file_protection["Protected delivery files<br/>[fileProtection.js]"]
  node_other_routes["Community and account routes"]
  node_users["User profiles<br/>[users.js]"]
end

subgraph group_chain["Escrow and chains"]
  node_escrow["Escrow coordinator<br/>[escrowService.js]"]
  node_evm_escrow["EVM escrow adapter"]
  node_ton["TON client service<br/>[tonService.js]"]
  node_ton_contracts["TON contract wrappers<br/>[EscrowContract.ts]"]
  node_monitor["Escrow monitoring<br/>[monitorService.js]"]
end

subgraph group_state["Persistence"]
  node_db[("PostgreSQL access<br/>[db.js]")]
  node_models["Deal and user models"]
end

subgraph group_engagement["Engagement"]
  node_notifications["Notifications"]
  node_subscriptions["Subscriptions and tiers<br/>[tierService.js]"]
  node_crystals["Crystal rewards<br/>[crystalService.js]"]
end

node_client_actor(("Client and freelancer"))
node_external_chain{{"TON and EVM networks"}}
node_telegram{{"Telegram platform"}}

node_client_actor -->|"uses"| node_miniapp
node_miniapp -->|"routes to"| node_deal_pages
node_miniapp -.->|"requests data"| node_api_client
node_api_client -.->|"calls API"| node_server
node_server -->|"applies"| node_auth
node_server -->|"mounts routes"| node_deal_routes
node_deal_routes -->|"delegates escrow"| node_escrow
node_deal_routes -->|"uses delivery protection"| node_file_protection
node_escrow -->|"uses TON operations"| node_ton
node_escrow -->|"dispatches EVM"| node_evm_escrow
node_evm_escrow -.->|"submits transactions"| node_external_chain
node_ton -.->|"queries and sends"| node_external_chain
node_ton_contracts -.->|"defines TON contracts"| node_external_chain
node_monitor -->|"checks escrow"| node_escrow
node_monitor -->|"checks chain state"| node_ton
node_escrow -->|"reads and writes"| node_db
node_evm_escrow -->|"reads and writes"| node_db
node_models -->|"uses database"| node_db
node_bot -->|"registers handlers"| node_bot_deals
node_bot_deals -->|"deploys contracts"| node_escrow
node_bot_deals -->|"reads deal data"| node_db
node_escrow -->|"notifies parties"| node_notifications
node_notifications -->|"stores notifications"| node_db
node_notifications -.->|"sends messages"| node_telegram
node_subscriptions -->|"reads tier plans"| node_db
node_crystals -->|"gets tier bonus"| node_subscriptions
node_crystals -->|"updates ledger and balance"| node_db
node_server -.->|"mounts routes"| node_other_routes
node_server -->|"mounts users API"| node_users
node_client_actor -->|"uses"| node_bot

click node_miniapp "https://github.com/marikk852/freelance-app/blob/main/miniapp/src/App.tsx"
click node_deal_pages "https://github.com/marikk852/freelance-app/tree/main/miniapp/src/pages"
click node_api_client "https://github.com/marikk852/freelance-app/blob/main/miniapp/src/utils/api.ts"
click node_server "https://github.com/marikk852/freelance-app/blob/main/backend/server.js"
click node_deal_routes "https://github.com/marikk852/freelance-app/tree/main/backend/routes"
click node_auth "https://github.com/marikk852/freelance-app/blob/main/backend/middleware/auth.js"
click node_escrow "https://github.com/marikk852/freelance-app/blob/main/backend/services/escrowService.js"
click node_evm_escrow "https://github.com/marikk852/freelance-app/blob/main/backend/services/evmEscrowService.js"
click node_ton "https://github.com/marikk852/freelance-app/blob/main/backend/services/tonService.js"
click node_ton_contracts "https://github.com/marikk852/freelance-app/blob/main/contracts/wrappers/EscrowContract.ts"
click node_file_protection "https://github.com/marikk852/freelance-app/blob/main/backend/services/fileProtection.js"
click node_monitor "https://github.com/marikk852/freelance-app/blob/main/backend/services/monitorService.js"
click node_db "https://github.com/marikk852/freelance-app/blob/main/database/db.js"
click node_models "https://github.com/marikk852/freelance-app/tree/main/database/models"
click node_bot "https://github.com/marikk852/freelance-app/blob/main/bot/bot.js"
click node_bot_deals "https://github.com/marikk852/freelance-app/blob/main/bot/handlers/deals.js"
click node_notifications "https://github.com/marikk852/freelance-app/blob/main/backend/services/notificationService.js"
click node_subscriptions "https://github.com/marikk852/freelance-app/blob/main/backend/services/tierService.js"
click node_crystals "https://github.com/marikk852/freelance-app/blob/main/backend/services/crystalService.js"
click node_other_routes "https://github.com/marikk852/freelance-app/tree/main/backend/routes"
click node_users "https://github.com/marikk852/freelance-app/blob/main/backend/routes/users.js"

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_miniapp,node_deal_pages,node_api_client,node_bot,node_bot_deals,node_client_actor toneBlue
class node_server,node_deal_routes,node_auth,node_file_protection,node_other_routes,node_users toneAmber
class node_escrow,node_evm_escrow,node_ton,node_ton_contracts,node_monitor toneMint
class node_db,node_models toneRose
class node_notifications,node_subscriptions,node_crystals,node_external_chain,node_telegram toneIndigo
```

## Components

### Deal experience

- [Telegram Mini App](https://github.com/marikk852/freelance-app/blob/main/miniapp/src/App.tsx): `miniapp/src/App.tsx`
- [Deal workflow screens](https://github.com/marikk852/freelance-app/tree/main/miniapp/src/pages): `miniapp/src/pages`
- [API client](https://github.com/marikk852/freelance-app/blob/main/miniapp/src/utils/api.ts): `miniapp/src/utils/api.ts`
- [Telegram bot](https://github.com/marikk852/freelance-app/blob/main/bot/bot.js): `bot/bot.js`
- [Bot deal handlers](https://github.com/marikk852/freelance-app/blob/main/bot/handlers/deals.js): `bot/handlers/deals.js`

### Backend services

- [HTTP API server](https://github.com/marikk852/freelance-app/blob/main/backend/server.js): `backend/server.js`
- [Deal and delivery routes](https://github.com/marikk852/freelance-app/tree/main/backend/routes): `backend/routes`
- [Telegram auth](https://github.com/marikk852/freelance-app/blob/main/backend/middleware/auth.js): `backend/middleware/auth.js`
- [Protected delivery files](https://github.com/marikk852/freelance-app/blob/main/backend/services/fileProtection.js): `backend/services/fileProtection.js`
- [Community and account routes](https://github.com/marikk852/freelance-app/tree/main/backend/routes): `backend/routes`
- [User profiles](https://github.com/marikk852/freelance-app/blob/main/backend/routes/users.js): `backend/routes/users.js`

### Escrow and chains

- [Escrow coordinator](https://github.com/marikk852/freelance-app/blob/main/backend/services/escrowService.js): `backend/services/escrowService.js`
- [EVM escrow adapter](https://github.com/marikk852/freelance-app/blob/main/backend/services/evmEscrowService.js): `backend/services/evmEscrowService.js`
- [TON client service](https://github.com/marikk852/freelance-app/blob/main/backend/services/tonService.js): `backend/services/tonService.js`
- [TON contract wrappers](https://github.com/marikk852/freelance-app/blob/main/contracts/wrappers/EscrowContract.ts): `contracts/wrappers/EscrowContract.ts`
- [Escrow monitoring](https://github.com/marikk852/freelance-app/blob/main/backend/services/monitorService.js): `backend/services/monitorService.js`

### Persistence

- [PostgreSQL access](https://github.com/marikk852/freelance-app/blob/main/database/db.js): `database/db.js`
- [Deal and user models](https://github.com/marikk852/freelance-app/tree/main/database/models): `database/models`

### Engagement

- [Notifications](https://github.com/marikk852/freelance-app/blob/main/backend/services/notificationService.js): `backend/services/notificationService.js`
- [Subscriptions and tiers](https://github.com/marikk852/freelance-app/blob/main/backend/services/tierService.js): `backend/services/tierService.js`
- [Crystal rewards](https://github.com/marikk852/freelance-app/blob/main/backend/services/crystalService.js): `backend/services/crystalService.js`

### Other components

- **Client and freelancer**
- **TON and EVM networks**
- **Telegram platform**

## Connections

- Client and freelancer → Telegram Mini App: uses
- Telegram Mini App → Deal workflow screens: routes to (evidence: `miniapp/src/App.tsx`)
- Telegram Mini App → API client: requests data
- API client → HTTP API server: calls API
- HTTP API server → Telegram auth: applies (evidence: `backend/server.js`)
- HTTP API server → Deal and delivery routes: mounts routes (evidence: `backend/server.js`)
- Deal and delivery routes → Escrow coordinator: delegates escrow (evidence: `backend/routes/contracts.js`)
- Deal and delivery routes → Protected delivery files: uses delivery protection (evidence: `backend/routes/deliveries.js`)
- Escrow coordinator → TON client service: uses TON operations (evidence: `backend/services/escrowService.js`)
- Escrow coordinator → EVM escrow adapter: dispatches EVM (evidence: `backend/services/escrowService.js`)
- EVM escrow adapter → TON and EVM networks: submits transactions
- TON client service → TON and EVM networks: queries and sends
- TON contract wrappers → TON and EVM networks: defines TON contracts
- Escrow monitoring → Escrow coordinator: checks escrow (evidence: `backend/services/monitorService.js`)
- Escrow monitoring → TON client service: checks chain state (evidence: `backend/services/monitorService.js`)
- Escrow coordinator → PostgreSQL access: reads and writes (evidence: `backend/services/escrowService.js`)
- EVM escrow adapter → PostgreSQL access: reads and writes (evidence: `backend/services/evmEscrowService.js`)
- Deal and user models → PostgreSQL access: uses database (evidence: `database/models/User.js`)
- Telegram bot → Bot deal handlers: registers handlers (evidence: `bot/bot.js`)
- Bot deal handlers → Escrow coordinator: deploys contracts (evidence: `bot/handlers/deals.js`)
- Bot deal handlers → PostgreSQL access: reads deal data (evidence: `bot/handlers/deals.js`)
- Escrow coordinator → Notifications: notifies parties (evidence: `backend/services/escrowService.js`)
- Notifications → PostgreSQL access: stores notifications (evidence: `backend/services/notificationService.js`)
- Notifications → Telegram platform: sends messages
- Subscriptions and tiers → PostgreSQL access: reads tier plans (evidence: `backend/services/tierService.js`)
- Crystal rewards → Subscriptions and tiers: gets tier bonus (evidence: `backend/services/crystalService.js`)
- Crystal rewards → PostgreSQL access: updates ledger and balance (evidence: `backend/services/crystalService.js`)
- HTTP API server → Community and account routes: mounts routes (evidence: `backend/server.js`)
- HTTP API server → User profiles: mounts users API (evidence: `backend/server.js`)
- Client and freelancer → Telegram bot: uses
