# prajwal471/workvault architecture

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

## Overview

WorkVault is a Stellar-based freelance escrow product. Clients connect a wallet, create and configure a vault, then fund it; freelancers submit deliverables, and the parties approve release or pursue dispute and refund actions. The Soroban contract enforces vault and milestone state while storing records on-ledger. The frontend also provides role-specific dashboards, wallet/network handling, transaction status, and activity updates. README capabilities inform the map where source excerpts were unavailable; links for those areas are limited to documented ownership and existing paths.

Main entry points: [`frontend/lib/contracts.ts`](https://github.com/prajwal471/workvault/blob/main/frontend/lib/contracts.ts) (Contract calls), [`frontend/app/dashboard/client/page.tsx`](https://github.com/prajwal471/workvault/blob/main/frontend/app/dashboard/client/page.tsx) (Client dashboard), [`frontend/app/dashboard/layout.tsx`](https://github.com/prajwal471/workvault/blob/main/frontend/app/dashboard/layout.tsx) (Dashboard shell), [`frontend/context/WalletContext.tsx`](https://github.com/prajwal471/workvault/blob/main/frontend/context/WalletContext.tsx) (Wallet state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Access and roles"]
  node_landing["Landing and connect<br/>[page.tsx]"]
  node_walletstate["Wallet state<br/>[WalletContext.tsx]"]
  node_role["Role state<br/>[RoleContext.tsx]"]
  node_dashboard["Dashboard shell<br/>[layout.tsx]"]
end

subgraph group_workflow["Escrow workflow"]
  node_clientdash["Client dashboard<br/>[page.tsx]"]
  node_freelancerdash["Freelancer dashboard<br/>[page.tsx]"]
  node_create["Create vault"]
  node_milestones["Milestone setup"]
  node_deposit["Fund escrow"]
  node_deliverable["Submit deliverable"]
  node_actions["Vault actions<br/>[VaultActions.tsx]"]
  node_dispute["Raise dispute"]
  node_vaultlist["Vault listing<br/>[VaultList.tsx]"]
end

subgraph group_chain["Soroban contract"]
  node_contractsapi["Contract calls<br/>[contracts.ts]"]
  node_contract["Vault contract<br/>[lib.rs]"]
  node_contracttypes["Vault and milestone types<br/>[types.rs]"]
  node_storage[("Contract storage<br/>[storage.rs]")]
end

subgraph group_activity["Network and activity"]
  node_stellar["Stellar integration<br/>[stellar.ts]"]
  node_wallets["Wallet adapters<br/>[freighter.ts]"]
  node_rpc["Stellar RPC and Horizon"]
  node_token["Soroban token"]
  node_vaultaggregation["Vault aggregation<br/>[myVaults.ts]"]
  node_events["Event polling<br/>[events.ts]"]
  node_feed["Activity feed<br/>[ActivityFeed.tsx]"]
end

node_client(("Client"))
node_freelancer(("Freelancer"))

node_client -->|"opens"| node_landing
node_freelancer -->|"opens"| node_landing
node_landing -->|"connects wallet"| node_walletstate
node_landing -->|"selects role"| node_role
node_walletstate -->|"connects and signs"| node_wallets
node_walletstate -->|"fetches balance"| node_stellar
node_client -->|"uses"| node_clientdash
node_freelancer -->|"uses"| node_freelancerdash
node_clientdash -->|"renders within"| node_dashboard
node_freelancerdash -->|"renders within"| node_dashboard
node_dashboard -->|"reads wallet"| node_walletstate
node_dashboard -->|"reads role"| node_role
node_clientdash -->|"offers creation"| node_create
node_clientdash -->|"offers setup"| node_milestones
node_clientdash -->|"offers funding"| node_deposit
node_clientdash -->|"shows vaults"| node_vaultlist
node_freelancerdash -->|"offers submission"| node_deliverable
node_freelancerdash -->|"shows vaults"| node_vaultlist
node_vaultlist -->|"loads vaults"| node_vaultaggregation
node_create -->|"calls"| node_contractsapi
node_milestones -->|"calls"| node_contractsapi
node_deposit -->|"looks up and funds"| node_contractsapi
node_deliverable -->|"submits proof"| node_contractsapi
node_vaultlist -->|"offers actions"| node_actions
node_actions -->|"calls"| node_contractsapi
node_dispute -->|"raises dispute"| node_contractsapi
node_contractsapi -->|"requests signing"| node_walletstate
node_contractsapi -->|"submits contract calls"| node_rpc
node_stellar -->|"queries account and transactions"| node_rpc
node_contract -->|"reads and writes"| node_storage
node_contract -->|"uses records"| node_contracttypes
node_contract -->|"transfers escrow tokens"| node_token
node_vaultaggregation -->|"reads vault data"| node_contractsapi
node_feed -->|"polls events"| node_events
node_events -->|"fetches events"| node_rpc
node_dashboard -->|"displays activity"| node_feed

click node_landing "https://github.com/prajwal471/workvault/blob/main/frontend/app/page.tsx"
click node_walletstate "https://github.com/prajwal471/workvault/blob/main/frontend/context/WalletContext.tsx"
click node_role "https://github.com/prajwal471/workvault/blob/main/frontend/context/RoleContext.tsx"
click node_dashboard "https://github.com/prajwal471/workvault/blob/main/frontend/app/dashboard/layout.tsx"
click node_clientdash "https://github.com/prajwal471/workvault/blob/main/frontend/app/dashboard/client/page.tsx"
click node_freelancerdash "https://github.com/prajwal471/workvault/blob/main/frontend/app/dashboard/freelancer/page.tsx"
click node_create "https://github.com/prajwal471/workvault/blob/main/frontend/components/CreateVaultForm.tsx"
click node_milestones "https://github.com/prajwal471/workvault/blob/main/frontend/components/SetMilestonesForm.tsx"
click node_deposit "https://github.com/prajwal471/workvault/blob/main/frontend/components/DepositFundsForm.tsx"
click node_deliverable "https://github.com/prajwal471/workvault/blob/main/frontend/components/SubmitDeliverableForm.tsx"
click node_actions "https://github.com/prajwal471/workvault/blob/main/frontend/components/VaultActions.tsx"
click node_dispute "https://github.com/prajwal471/workvault/blob/main/frontend/components/RaiseDisputeForm.tsx"
click node_vaultlist "https://github.com/prajwal471/workvault/blob/main/frontend/components/VaultList.tsx"
click node_contractsapi "https://github.com/prajwal471/workvault/blob/main/frontend/lib/contracts.ts"
click node_contract "https://github.com/prajwal471/workvault/blob/main/contracts/vault/src/lib.rs"
click node_contracttypes "https://github.com/prajwal471/workvault/blob/main/contracts/vault/src/types.rs"
click node_storage "https://github.com/prajwal471/workvault/blob/main/contracts/vault/src/storage.rs"
click node_stellar "https://github.com/prajwal471/workvault/blob/main/frontend/lib/stellar.ts"
click node_wallets "https://github.com/prajwal471/workvault/blob/main/frontend/lib/freighter.ts"
click node_vaultaggregation "https://github.com/prajwal471/workvault/blob/main/frontend/lib/myVaults.ts"
click node_events "https://github.com/prajwal471/workvault/blob/main/frontend/lib/events.ts"
click node_feed "https://github.com/prajwal471/workvault/blob/main/frontend/components/ActivityFeed.tsx"

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_landing,node_walletstate,node_role,node_dashboard,node_client toneBlue
class node_clientdash,node_freelancerdash,node_create,node_milestones,node_deposit,node_deliverable,node_actions,node_dispute,node_vaultlist toneAmber
class node_contractsapi,node_contract,node_contracttypes,node_storage toneMint
class node_stellar,node_wallets,node_rpc,node_token,node_vaultaggregation,node_events,node_feed toneRose
class node_freelancer toneIndigo
```

## Components

### Access and roles

- [Landing and connect](https://github.com/prajwal471/workvault/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Wallet state](https://github.com/prajwal471/workvault/blob/main/frontend/context/WalletContext.tsx): `frontend/context/WalletContext.tsx`
- [Role state](https://github.com/prajwal471/workvault/blob/main/frontend/context/RoleContext.tsx): `frontend/context/RoleContext.tsx`
- [Dashboard shell](https://github.com/prajwal471/workvault/blob/main/frontend/app/dashboard/layout.tsx): `frontend/app/dashboard/layout.tsx`

### Escrow workflow

- [Client dashboard](https://github.com/prajwal471/workvault/blob/main/frontend/app/dashboard/client/page.tsx): `frontend/app/dashboard/client/page.tsx`
- [Freelancer dashboard](https://github.com/prajwal471/workvault/blob/main/frontend/app/dashboard/freelancer/page.tsx): `frontend/app/dashboard/freelancer/page.tsx`
- [Create vault](https://github.com/prajwal471/workvault/blob/main/frontend/components/CreateVaultForm.tsx): `frontend/components/CreateVaultForm.tsx`
- [Milestone setup](https://github.com/prajwal471/workvault/blob/main/frontend/components/SetMilestonesForm.tsx): `frontend/components/SetMilestonesForm.tsx`
- [Fund escrow](https://github.com/prajwal471/workvault/blob/main/frontend/components/DepositFundsForm.tsx): `frontend/components/DepositFundsForm.tsx`
- [Submit deliverable](https://github.com/prajwal471/workvault/blob/main/frontend/components/SubmitDeliverableForm.tsx): `frontend/components/SubmitDeliverableForm.tsx`
- [Vault actions](https://github.com/prajwal471/workvault/blob/main/frontend/components/VaultActions.tsx): `frontend/components/VaultActions.tsx`
- [Raise dispute](https://github.com/prajwal471/workvault/blob/main/frontend/components/RaiseDisputeForm.tsx): `frontend/components/RaiseDisputeForm.tsx`
- [Vault listing](https://github.com/prajwal471/workvault/blob/main/frontend/components/VaultList.tsx): `frontend/components/VaultList.tsx`

### Soroban contract

- [Contract calls](https://github.com/prajwal471/workvault/blob/main/frontend/lib/contracts.ts): `frontend/lib/contracts.ts`
- [Vault contract](https://github.com/prajwal471/workvault/blob/main/contracts/vault/src/lib.rs): `contracts/vault/src/lib.rs`
- [Vault and milestone types](https://github.com/prajwal471/workvault/blob/main/contracts/vault/src/types.rs): `contracts/vault/src/types.rs`
- [Contract storage](https://github.com/prajwal471/workvault/blob/main/contracts/vault/src/storage.rs): `contracts/vault/src/storage.rs`

### Network and activity

- [Stellar integration](https://github.com/prajwal471/workvault/blob/main/frontend/lib/stellar.ts): `frontend/lib/stellar.ts`
- [Wallet adapters](https://github.com/prajwal471/workvault/blob/main/frontend/lib/freighter.ts): `frontend/lib/freighter.ts`
- **Stellar RPC and Horizon**
- **Soroban token**
- [Vault aggregation](https://github.com/prajwal471/workvault/blob/main/frontend/lib/myVaults.ts): `frontend/lib/myVaults.ts`
- [Event polling](https://github.com/prajwal471/workvault/blob/main/frontend/lib/events.ts): `frontend/lib/events.ts`
- [Activity feed](https://github.com/prajwal471/workvault/blob/main/frontend/components/ActivityFeed.tsx): `frontend/components/ActivityFeed.tsx`

### Other components

- **Client**
- **Freelancer**

## Connections

- Client → Landing and connect: opens
- Freelancer → Landing and connect: opens
- Landing and connect → Wallet state: connects wallet
- Landing and connect → Role state: selects role
- Wallet state → Wallet adapters: connects and signs
- Wallet state → Stellar integration: fetches balance
- Client → Client dashboard: uses
- Freelancer → Freelancer dashboard: uses
- Client dashboard → Dashboard shell: renders within
- Freelancer dashboard → Dashboard shell: renders within
- Dashboard shell → Wallet state: reads wallet
- Dashboard shell → Role state: reads role
- Client dashboard → Create vault: offers creation
- Client dashboard → Milestone setup: offers setup
- Client dashboard → Fund escrow: offers funding
- Client dashboard → Vault listing: shows vaults
- Freelancer dashboard → Submit deliverable: offers submission
- Freelancer dashboard → Vault listing: shows vaults
- Vault listing → Vault aggregation: loads vaults
- Create vault → Contract calls: calls
- Milestone setup → Contract calls: calls
- Fund escrow → Contract calls: looks up and funds
- Submit deliverable → Contract calls: submits proof
- Vault listing → Vault actions: offers actions
- Vault actions → Contract calls: calls
- Raise dispute → Contract calls: raises dispute
- Contract calls → Wallet state: requests signing
- Contract calls → Stellar RPC and Horizon: submits contract calls
- Stellar integration → Stellar RPC and Horizon: queries account and transactions
- Vault contract → Contract storage: reads and writes
- Vault contract → Vault and milestone types: uses records
- Vault contract → Soroban token: transfers escrow tokens
- Vault aggregation → Contract calls: reads vault data
- Activity feed → Event polling: polls events
- Event polling → Stellar RPC and Horizon: fetches events
- Dashboard shell → Activity feed: displays activity