# uzumakiodz/parallax architecture

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

- Interactive diagram: https://gitdiagram.com/uzumakiodz/parallax
- Repository: https://github.com/uzumakiodz/parallax

## Overview

Parallax is a decentralized AI-orchestrated microtask marketplace. A creator submits a brief for AI decomposition, reviews and funds subtasks on-chain; workers claim, bond, and submit deliverables; an AI verifier grades submissions and the contracts settle rewards or retain failed work for appeal. Verified outputs can be synthesized into a master deliverable. The graph combines the documented product workflow with sampled frontend routing and backend wiring; several UI-to-API links and contract internals are documented only at a high level, so those links use the README as evidence.

Main entry points: [`backend/src/index.ts`](https://github.com/uzumakiodz/parallax/blob/main/backend/src/index.ts) (Backend API), [`backend/src/lib/worker.ts`](https://github.com/uzumakiodz/parallax/blob/main/backend/src/lib/worker.ts) (Verification worker), [`frontend/src/App.tsx`](https://github.com/uzumakiodz/parallax/blob/main/frontend/src/App.tsx) (Application routes), [`backend/src/lib/chain.ts`](https://github.com/uzumakiodz/parallax/blob/main/backend/src/lib/chain.ts) (Chain indexing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_app["Application routes<br/>[App.tsx]"]
  node_creator_ui["Creator workspace"]
  node_review["Subtask review"]
  node_worker_ui["Worker marketplace<br/>[WorkerTasks.tsx]"]
  node_task_ui["Task workspace<br/>[TaskDetail.tsx]"]
  node_admin_ui["Admin dashboard<br/>[AdminDashboard.tsx]"]
  node_web3["Wallet and contract client<br/>[Web3Context.tsx]"]
end

subgraph group_backend["Orchestration service"]
  node_api["Backend API<br/>[index.ts]"]
  node_decompose["Brief decomposition<br/>[decompose.ts]"]
  node_task_routes["Task operations<br/>[tasks.ts]"]
  node_submission_routes["Submission access<br/>[submissions.ts]"]
  node_verify_routes["Verification trigger<br/>[verify.ts]"]
  node_worker_service["Verification worker<br/>[worker.ts]"]
  node_chain_index["Chain indexing<br/>[chain.ts]"]
  node_deployments["Deployment registry<br/>[deployments.ts]"]
end

subgraph group_chain["On-chain marketplace"]
  node_contracts{{"Task and escrow contracts"}}
end

subgraph group_storage["AI and content services"]
  node_gemini["Gemini AI<br/>[gemini.ts]"]
  node_ipfs["IPFS storage<br/>[ipfs.ts]"]
end

subgraph group_state["Persistence and indexing"]
  node_database[("PostgreSQL data<br/>[client.ts]")]
end

node_creator(("Task creator"))
node_worker(("Freelance worker"))
node_admin(("Appeal administrator"))

node_app -->|"routes to"| node_creator_ui
node_app -->|"routes to"| node_worker_ui
node_app -->|"routes to"| node_task_ui
node_app -->|"routes to"| node_admin_ui
node_app -->|"provides context"| node_web3
node_creator -.->|"creates projects"| node_creator_ui
node_creator_ui -->|"reviews subtasks"| node_review
node_review -->|"reads currency"| node_web3
node_creator_ui -.->|"requests decomposition"| node_api
node_api -->|"routes requests"| node_decompose
node_decompose -->|"generates subtasks"| node_gemini
node_decompose -->|"stores content"| node_ipfs
node_creator -.->|"approves and funds"| node_contracts
node_worker -.->|"browses work"| node_worker_ui
node_worker_ui -.->|"claims with bond"| node_contracts
node_worker -.->|"submits proof"| node_contracts
node_task_ui -.->|"loads task data"| node_api
node_task_routes -->|"resolves content"| node_ipfs
node_task_routes -->|"queries tasks"| node_database
node_api -->|"routes requests"| node_task_routes
node_api -->|"routes requests"| node_submission_routes
node_api -->|"routes requests"| node_verify_routes
node_api -->|"starts listeners"| node_chain_index
node_api -->|"starts worker"| node_worker_service
node_worker_service -->|"grades submissions"| node_gemini
node_worker_service -->|"fetches deliverables"| node_ipfs
node_worker_service -.->|"submits verification"| node_contracts
node_worker_service -->|"syncs transaction"| node_chain_index
node_verify_routes -->|"invokes verification"| node_worker_service
node_contracts -.->|"emits events"| node_chain_index
node_chain_index -->|"indexes state"| node_database
node_chain_index -->|"loads deployments"| node_deployments
node_admin -.->|"resolves appeals"| node_admin_ui
node_admin_ui -.->|"requests dispute data"| node_api
node_contracts -.->|"settles rewards"| node_worker
node_contracts -.->|"refunds on upheld appeal"| node_creator

click node_app "https://github.com/uzumakiodz/parallax/blob/main/frontend/src/App.tsx"
click node_creator_ui "https://github.com/uzumakiodz/parallax/blob/main/frontend/src/pages/CustomerDashboard.tsx"
click node_review "https://github.com/uzumakiodz/parallax/blob/main/frontend/src/components/task/ReviewSubtasksModal.tsx"
click node_worker_ui "https://github.com/uzumakiodz/parallax/blob/main/frontend/src/pages/WorkerTasks.tsx"
click node_task_ui "https://github.com/uzumakiodz/parallax/blob/main/frontend/src/pages/TaskDetail.tsx"
click node_admin_ui "https://github.com/uzumakiodz/parallax/blob/main/frontend/src/pages/AdminDashboard.tsx"
click node_web3 "https://github.com/uzumakiodz/parallax/blob/main/frontend/src/contexts/Web3Context.tsx"
click node_api "https://github.com/uzumakiodz/parallax/blob/main/backend/src/index.ts"
click node_decompose "https://github.com/uzumakiodz/parallax/blob/main/backend/src/routes/decompose.ts"
click node_task_routes "https://github.com/uzumakiodz/parallax/blob/main/backend/src/routes/tasks.ts"
click node_submission_routes "https://github.com/uzumakiodz/parallax/blob/main/backend/src/routes/submissions.ts"
click node_verify_routes "https://github.com/uzumakiodz/parallax/blob/main/backend/src/routes/verify.ts"
click node_worker_service "https://github.com/uzumakiodz/parallax/blob/main/backend/src/lib/worker.ts"
click node_chain_index "https://github.com/uzumakiodz/parallax/blob/main/backend/src/lib/chain.ts"
click node_gemini "https://github.com/uzumakiodz/parallax/blob/main/backend/src/lib/gemini.ts"
click node_ipfs "https://github.com/uzumakiodz/parallax/blob/main/backend/src/lib/ipfs.ts"
click node_deployments "https://github.com/uzumakiodz/parallax/blob/main/backend/src/lib/deployments.ts"
click node_database "https://github.com/uzumakiodz/parallax/blob/main/backend/src/db/client.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_app,node_creator_ui,node_review,node_worker_ui,node_task_ui,node_admin_ui,node_web3 toneBlue
class node_api,node_decompose,node_task_routes,node_submission_routes,node_verify_routes,node_worker_service,node_chain_index,node_deployments toneAmber
class node_contracts toneMint
class node_gemini,node_ipfs,node_creator,node_worker toneRose
class node_database,node_admin toneIndigo
```

## Components

### Web application

- [Application routes](https://github.com/uzumakiodz/parallax/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Creator workspace](https://github.com/uzumakiodz/parallax/blob/main/frontend/src/pages/CustomerDashboard.tsx): `frontend/src/pages/CustomerDashboard.tsx`
- [Subtask review](https://github.com/uzumakiodz/parallax/blob/main/frontend/src/components/task/ReviewSubtasksModal.tsx): `frontend/src/components/task/ReviewSubtasksModal.tsx`
- [Worker marketplace](https://github.com/uzumakiodz/parallax/blob/main/frontend/src/pages/WorkerTasks.tsx): `frontend/src/pages/WorkerTasks.tsx`
- [Task workspace](https://github.com/uzumakiodz/parallax/blob/main/frontend/src/pages/TaskDetail.tsx): `frontend/src/pages/TaskDetail.tsx`
- [Admin dashboard](https://github.com/uzumakiodz/parallax/blob/main/frontend/src/pages/AdminDashboard.tsx): `frontend/src/pages/AdminDashboard.tsx`
- [Wallet and contract client](https://github.com/uzumakiodz/parallax/blob/main/frontend/src/contexts/Web3Context.tsx): `frontend/src/contexts/Web3Context.tsx`

### Orchestration service

- [Backend API](https://github.com/uzumakiodz/parallax/blob/main/backend/src/index.ts): `backend/src/index.ts`
- [Brief decomposition](https://github.com/uzumakiodz/parallax/blob/main/backend/src/routes/decompose.ts): `backend/src/routes/decompose.ts`
- [Task operations](https://github.com/uzumakiodz/parallax/blob/main/backend/src/routes/tasks.ts): `backend/src/routes/tasks.ts`
- [Submission access](https://github.com/uzumakiodz/parallax/blob/main/backend/src/routes/submissions.ts): `backend/src/routes/submissions.ts`
- [Verification trigger](https://github.com/uzumakiodz/parallax/blob/main/backend/src/routes/verify.ts): `backend/src/routes/verify.ts`
- [Verification worker](https://github.com/uzumakiodz/parallax/blob/main/backend/src/lib/worker.ts): `backend/src/lib/worker.ts`
- [Chain indexing](https://github.com/uzumakiodz/parallax/blob/main/backend/src/lib/chain.ts): `backend/src/lib/chain.ts`
- [Deployment registry](https://github.com/uzumakiodz/parallax/blob/main/backend/src/lib/deployments.ts): `backend/src/lib/deployments.ts`

### On-chain marketplace

- **Task and escrow contracts**

### AI and content services

- [Gemini AI](https://github.com/uzumakiodz/parallax/blob/main/backend/src/lib/gemini.ts): `backend/src/lib/gemini.ts`
- [IPFS storage](https://github.com/uzumakiodz/parallax/blob/main/backend/src/lib/ipfs.ts): `backend/src/lib/ipfs.ts`

### Persistence and indexing

- [PostgreSQL data](https://github.com/uzumakiodz/parallax/blob/main/backend/src/db/client.ts): `backend/src/db/client.ts`

### Other components

- **Task creator**
- **Freelance worker**
- **Appeal administrator**

## Connections

- Application routes → Creator workspace: routes to (evidence: `frontend/src/App.tsx`)
- Application routes → Worker marketplace: routes to (evidence: `frontend/src/App.tsx`)
- Application routes → Task workspace: routes to (evidence: `frontend/src/App.tsx`)
- Application routes → Admin dashboard: routes to (evidence: `frontend/src/App.tsx`)
- Application routes → Wallet and contract client: provides context (evidence: `frontend/src/App.tsx`)
- Task creator → Creator workspace: creates projects
- Creator workspace → Subtask review: reviews subtasks (evidence: `frontend/src/pages/CustomerDashboard.tsx`)
- Subtask review → Wallet and contract client: reads currency (evidence: `frontend/src/components/task/ReviewSubtasksModal.tsx`)
- Creator workspace → Backend API: requests decomposition
- Backend API → Brief decomposition: routes requests (evidence: `backend/src/index.ts`)
- Brief decomposition → Gemini AI: generates subtasks (evidence: `backend/src/routes/decompose.ts`)
- Brief decomposition → IPFS storage: stores content (evidence: `backend/src/routes/decompose.ts`)
- Task creator → Task and escrow contracts: approves and funds
- Freelance worker → Worker marketplace: browses work
- Worker marketplace → Task and escrow contracts: claims with bond
- Freelance worker → Task and escrow contracts: submits proof
- Task workspace → Backend API: loads task data
- Task operations → IPFS storage: resolves content (evidence: `backend/src/routes/tasks.ts`)
- Task operations → PostgreSQL data: queries tasks (evidence: `backend/src/routes/tasks.ts`)
- Backend API → Task operations: routes requests (evidence: `backend/src/index.ts`)
- Backend API → Submission access: routes requests (evidence: `backend/src/index.ts`)
- Backend API → Verification trigger: routes requests (evidence: `backend/src/index.ts`)
- Backend API → Chain indexing: starts listeners (evidence: `backend/src/index.ts`)
- Backend API → Verification worker: starts worker (evidence: `backend/src/index.ts`)
- Verification worker → Gemini AI: grades submissions (evidence: `backend/src/lib/worker.ts`)
- Verification worker → IPFS storage: fetches deliverables (evidence: `backend/src/lib/worker.ts`)
- Verification worker → Task and escrow contracts: submits verification
- Verification worker → Chain indexing: syncs transaction (evidence: `backend/src/lib/worker.ts`)
- Verification trigger → Verification worker: invokes verification (evidence: `backend/src/routes/verify.ts`)
- Task and escrow contracts → Chain indexing: emits events
- Chain indexing → PostgreSQL data: indexes state (evidence: `backend/src/lib/chain.ts`)
- Chain indexing → Deployment registry: loads deployments (evidence: `backend/src/lib/chain.ts`)
- Appeal administrator → Admin dashboard: resolves appeals
- Admin dashboard → Backend API: requests dispute data
- Task and escrow contracts → Freelance worker: settles rewards
- Task and escrow contracts → Task creator: refunds on upheld appeal
