# shadowincache/escrowlance architecture

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

- Interactive diagram: https://gitdiagram.com/shadowincache/escrowlance
- Repository: https://github.com/shadowincache/escrowlance

## Overview

EscrowLancer coordinates freelance projects from creation and funding through freelancer assignment, milestone proof submission, approval, and payout, with disputes and refunds as an alternate resolution path. The React app presents these workflows and connects wallets; the Express API validates requests, persists off-chain records, and invokes escrow actions. MongoDB stores users, projects, milestones, transactions, and disputes, while IPFS holds proof content and the Sepolia contract guards funds and state. Routes and controllers are sampled; other README-listed capabilities are represented at their exact enclosing paths where implementation details were not provided.

Main entry points: [`frontend/src/App.jsx`](https://github.com/shadowincache/escrowlance/blob/main/frontend/src/App.jsx) (React routes), [`backend/src/app.js`](https://github.com/shadowincache/escrowlance/blob/main/backend/src/app.js) (Express API), [`backend/src/controllers/milestoneController.js`](https://github.com/shadowincache/escrowlance/blob/main/backend/src/controllers/milestoneController.js) (Milestone workflow), [`frontend/src/services/api.js`](https://github.com/shadowincache/escrowlance/blob/main/frontend/src/services/api.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User experience"]
  node_app["React routes<br/>[App.jsx]"]
  node_authui["Login and signup"]
  node_projectui["Project workspace"]
  node_milestoneui["Milestone submission"]
  node_otherui["Wallet, disputes, profile"]
  node_wallet["Wallet connection<br/>[useWallet.js]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_api["API workflows"]
  node_express["Express API<br/>[app.js]"]
  node_projectctl["Project workflow"]
  node_milestonectl["Milestone workflow"]
  node_disputectl["Dispute workflow"]
  node_authroutes["Auth and user routes"]
  node_upload["Proof uploads"]
end

subgraph group_records["Off-chain records"]
  node_models[("Mongo records")]
  node_transactions[("Transaction history<br/>[Transaction.js]")]
  node_mongodb[("MongoDB")]
end

subgraph group_chain["Escrow and integrations"]
  node_blocksvc["Chain operations"]
  node_contractclient["Contract client<br/>[contractClient.js]"]
  node_contract{{"Freelance escrow"}}
  node_ipfs["Pinata / IPFS<br/>[pinataClient.js]"]
end

node_user(("Client / freelancer"))
node_metamask(("MetaMask"))
node_sepolia(("Sepolia network"))

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_authui
node_app -->|"routes to"| node_projectui
node_app -->|"routes to"| node_milestoneui
node_app -->|"routes to"| node_otherui
node_authui -->|"requests"| node_api_client
node_projectui -->|"requests"| node_api_client
node_milestoneui -->|"requests"| node_api_client
node_otherui -->|"requests"| node_api_client
node_otherui -->|"connects wallet"| node_wallet
node_wallet -->|"reads account"| node_metamask
node_api_client -->|"HTTP requests"| node_express
node_express -->|"dispatches"| node_projectctl
node_express -->|"dispatches"| node_milestonectl
node_express -->|"dispatches"| node_disputectl
node_express -->|"dispatches"| node_authroutes
node_projectctl -->|"reads/writes"| node_models
node_milestonectl -->|"reads/writes"| node_models
node_disputectl -->|"reads/writes"| node_models
node_projectctl -->|"calls escrow actions"| node_blocksvc
node_milestonectl -->|"calls approval/release"| node_blocksvc
node_disputectl -->|"calls dispute actions"| node_blocksvc
node_blocksvc -->|"gets contract"| node_contractclient
node_contractclient -->|"invokes contract"| node_contract
node_contract -->|"executes on"| node_sepolia
node_milestoneui -->|"submits proof transaction"| node_contract
node_projectctl -->|"records refund"| node_transactions
node_milestonectl -->|"records payment activity"| node_transactions
node_disputectl -->|"records dispute activity"| node_transactions
node_models -->|"persists"| node_mongodb
node_upload -.->|"pins content"| node_ipfs
node_milestonectl -->|"verifies submission receipt"| node_contractclient
node_milestoneui -.->|"uploads proof"| node_upload

click node_app "https://github.com/shadowincache/escrowlance/blob/main/frontend/src/App.jsx"
click node_authui "https://github.com/shadowincache/escrowlance/tree/main/frontend/src/pages/auth"
click node_projectui "https://github.com/shadowincache/escrowlance/tree/main/frontend/src/pages/projects"
click node_milestoneui "https://github.com/shadowincache/escrowlance/blob/main/frontend/src/pages/milestones/SubmitMilestone.jsx"
click node_otherui "https://github.com/shadowincache/escrowlance/tree/main/frontend/src/pages"
click node_wallet "https://github.com/shadowincache/escrowlance/blob/main/frontend/src/hooks/useWallet.js"
click node_api_client "https://github.com/shadowincache/escrowlance/blob/main/frontend/src/services/api.js"
click node_express "https://github.com/shadowincache/escrowlance/blob/main/backend/src/app.js"
click node_projectctl "https://github.com/shadowincache/escrowlance/blob/main/backend/src/controllers/projectController.js"
click node_milestonectl "https://github.com/shadowincache/escrowlance/blob/main/backend/src/controllers/milestoneController.js"
click node_disputectl "https://github.com/shadowincache/escrowlance/blob/main/backend/src/controllers/disputeController.js"
click node_authroutes "https://github.com/shadowincache/escrowlance/tree/main/backend/src/routes"
click node_upload "https://github.com/shadowincache/escrowlance/tree/main/backend/src"
click node_models "https://github.com/shadowincache/escrowlance/tree/main/backend/src/models"
click node_transactions "https://github.com/shadowincache/escrowlance/blob/main/backend/src/models/Transaction.js"
click node_blocksvc "https://github.com/shadowincache/escrowlance/blob/main/backend/src/services/blockchainService.js"
click node_contractclient "https://github.com/shadowincache/escrowlance/blob/main/backend/src/blockchain/contractClient.js"
click node_contract "https://github.com/shadowincache/escrowlance/tree/main/blockchain"
click node_ipfs "https://github.com/shadowincache/escrowlance/blob/main/backend/src/ipfs/pinataClient.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_app,node_authui,node_projectui,node_milestoneui,node_otherui,node_wallet,node_api_client,node_user toneBlue
class node_express,node_projectctl,node_milestonectl,node_disputectl,node_authroutes,node_upload toneAmber
class node_models,node_transactions,node_mongodb toneMint
class node_blocksvc,node_contractclient,node_contract,node_ipfs toneRose
class node_metamask,node_sepolia toneIndigo
```

## Components

### User experience

- [React routes](https://github.com/shadowincache/escrowlance/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Login and signup](https://github.com/shadowincache/escrowlance/tree/main/frontend/src/pages/auth): `frontend/src/pages/auth`
- [Project workspace](https://github.com/shadowincache/escrowlance/tree/main/frontend/src/pages/projects): `frontend/src/pages/projects`
- [Milestone submission](https://github.com/shadowincache/escrowlance/blob/main/frontend/src/pages/milestones/SubmitMilestone.jsx): `frontend/src/pages/milestones/SubmitMilestone.jsx`
- [Wallet, disputes, profile](https://github.com/shadowincache/escrowlance/tree/main/frontend/src/pages): `frontend/src/pages`
- [Wallet connection](https://github.com/shadowincache/escrowlance/blob/main/frontend/src/hooks/useWallet.js): `frontend/src/hooks/useWallet.js`
- [API client](https://github.com/shadowincache/escrowlance/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### API workflows

- [Express API](https://github.com/shadowincache/escrowlance/blob/main/backend/src/app.js): `backend/src/app.js`
- [Project workflow](https://github.com/shadowincache/escrowlance/blob/main/backend/src/controllers/projectController.js): `backend/src/controllers/projectController.js`
- [Milestone workflow](https://github.com/shadowincache/escrowlance/blob/main/backend/src/controllers/milestoneController.js): `backend/src/controllers/milestoneController.js`
- [Dispute workflow](https://github.com/shadowincache/escrowlance/blob/main/backend/src/controllers/disputeController.js): `backend/src/controllers/disputeController.js`
- [Auth and user routes](https://github.com/shadowincache/escrowlance/tree/main/backend/src/routes): `backend/src/routes`
- [Proof uploads](https://github.com/shadowincache/escrowlance/tree/main/backend/src): `backend/src`

### Off-chain records

- [Mongo records](https://github.com/shadowincache/escrowlance/tree/main/backend/src/models): `backend/src/models`
- [Transaction history](https://github.com/shadowincache/escrowlance/blob/main/backend/src/models/Transaction.js): `backend/src/models/Transaction.js`
- **MongoDB**

### Escrow and integrations

- [Chain operations](https://github.com/shadowincache/escrowlance/blob/main/backend/src/services/blockchainService.js): `backend/src/services/blockchainService.js`
- [Contract client](https://github.com/shadowincache/escrowlance/blob/main/backend/src/blockchain/contractClient.js): `backend/src/blockchain/contractClient.js`
- [Freelance escrow](https://github.com/shadowincache/escrowlance/tree/main/blockchain): `blockchain`
- [Pinata / IPFS](https://github.com/shadowincache/escrowlance/blob/main/backend/src/ipfs/pinataClient.js): `backend/src/ipfs/pinataClient.js`

### Other components

- **Client / freelancer**
- **MetaMask**
- **Sepolia network**

## Connections

- Client / freelancer → React routes: uses
- React routes → Login and signup: routes to
- React routes → Project workspace: routes to
- React routes → Milestone submission: routes to
- React routes → Wallet, disputes, profile: routes to
- Login and signup → API client: requests
- Project workspace → API client: requests
- Milestone submission → API client: requests
- Wallet, disputes, profile → API client: requests
- Wallet, disputes, profile → Wallet connection: connects wallet
- Wallet connection → MetaMask: reads account
- API client → Express API: HTTP requests
- Express API → Project workflow: dispatches
- Express API → Milestone workflow: dispatches
- Express API → Dispute workflow: dispatches
- Express API → Auth and user routes: dispatches
- Project workflow → Mongo records: reads/writes
- Milestone workflow → Mongo records: reads/writes
- Dispute workflow → Mongo records: reads/writes
- Project workflow → Chain operations: calls escrow actions
- Milestone workflow → Chain operations: calls approval/release
- Dispute workflow → Chain operations: calls dispute actions
- Chain operations → Contract client: gets contract
- Contract client → Freelance escrow: invokes contract
- Freelance escrow → Sepolia network: executes on
- Milestone submission → Freelance escrow: submits proof transaction
- Project workflow → Transaction history: records refund
- Milestone workflow → Transaction history: records payment activity
- Dispute workflow → Transaction history: records dispute activity
- Mongo records → MongoDB: persists
- Proof uploads → Pinata / IPFS: pins content
- Milestone workflow → Contract client: verifies submission receipt
- Milestone submission → Proof uploads: uploads proof