# saheeldev/taptostream architecture

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

- Interactive diagram: https://gitdiagram.com/saheeldev/taptostream
- Repository: https://github.com/saheeldev/taptostream

## Overview

TapToStream is a video-on-demand application in which viewers browse a catalog, connect an Algorand wallet, pay per video, and receive a signed stream URL. The frontend requests video metadata and opens a watch flow; its payment hook responds to the server’s 402 challenge by signing an ASA transfer and retrying. The server verifies payment, calls the Algorand contract to distribute creator/platform shares, then authorizes stream delivery. The main entry points and payment path are supported by sampled source; some UI and stream implementation details are inferred only from the file tree.

Main entry points: [`server/index.js`](https://github.com/saheeldev/taptostream/blob/main/server/index.js) (HTTP API), [`projects/taptostream-frontend/src/hooks/useX402.ts`](https://github.com/saheeldev/taptostream/blob/main/projects/taptostream-frontend/src/hooks/useX402.ts) (x402 client), [`server/x402.js`](https://github.com/saheeldev/taptostream/blob/main/server/x402.js) (Payment verification), [`projects/taptostream-frontend/src/Home.tsx`](https://github.com/saheeldev/taptostream/blob/main/projects/taptostream-frontend/src/Home.tsx) (Video home)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Viewer app"]
  node_app["App shell<br/>[App.tsx]"]
  node_home["Video home<br/>[Home.tsx]"]
  node_video_card["Video card<br/>[VideoCard.tsx]"]
  node_watch_modal["Watch modal<br/>[WatchModal.tsx]"]
  node_wallet_ui["Wallet controls<br/>[ConnectWallet.tsx]"]
  node_wallet_provider["Wallet provider<br/>[App.tsx]"]
  node_stream_view["Video playback<br/>[WatchModal.tsx]"]
end

subgraph group_server["API and streaming"]
  node_api["HTTP API<br/>[index.js]"]
  node_video_catalog["Video catalog<br/>[videos.json]"]
  node_stream_service["Stream URLs<br/>[stream.js]"]
end

subgraph group_payments["Payment flow"]
  node_payment_hook["x402 client<br/>[useX402.ts]"]
  node_payment_middleware["Payment verification<br/>[x402.js]"]
  node_facilitator["x402 facilitator"]
end

subgraph group_chain["Algorand contract"]
  node_algorand_node["Algorand node"]
  node_tap_contract["TapToStream<br/>[contract.py]"]
  node_contract_artifacts["Contract artifacts"]
end

node_viewer(("Viewer"))

node_viewer -->|"opens app"| node_app
node_app -->|"configures wallet"| node_wallet_provider
node_app -->|"renders"| node_home
node_viewer -->|"connects wallet"| node_wallet_ui
node_home -->|"requests catalog"| node_api
node_api -->|"reads catalog"| node_video_catalog
node_api -->|"returns catalog"| node_home
node_home -->|"shows videos"| node_video_card
node_video_card -->|"opens watch"| node_watch_modal
node_watch_modal -->|"requests access"| node_payment_hook
node_payment_hook -->|"signs transfer"| node_wallet_provider
node_payment_hook -->|"requests watch"| node_api
node_api -->|"dispatches payment"| node_payment_middleware
node_payment_middleware -->|"broadcasts transfer"| node_algorand_node
node_payment_middleware -.->|"verifies payment"| node_facilitator
node_payment_middleware -->|"calls payment method"| node_tap_contract
node_tap_contract -->|"submits transfers"| node_algorand_node
node_tap_contract -.->|"described by"| node_contract_artifacts
node_api -->|"gets signed URL"| node_stream_service
node_stream_service -->|"returns stream URL"| node_api
node_api -->|"returns stream URL"| node_payment_hook
node_payment_hook -->|"returns playback data"| node_watch_modal
node_watch_modal -->|"loads stream"| node_stream_view
node_viewer -->|"watches video"| node_stream_view

click node_app "https://github.com/saheeldev/taptostream/blob/main/projects/taptostream-frontend/src/App.tsx"
click node_home "https://github.com/saheeldev/taptostream/blob/main/projects/taptostream-frontend/src/Home.tsx"
click node_video_card "https://github.com/saheeldev/taptostream/blob/main/projects/taptostream-frontend/src/components/VideoCard.tsx"
click node_watch_modal "https://github.com/saheeldev/taptostream/blob/main/projects/taptostream-frontend/src/components/WatchModal.tsx"
click node_wallet_ui "https://github.com/saheeldev/taptostream/blob/main/projects/taptostream-frontend/src/components/ConnectWallet.tsx"
click node_wallet_provider "https://github.com/saheeldev/taptostream/blob/main/projects/taptostream-frontend/src/App.tsx"
click node_payment_hook "https://github.com/saheeldev/taptostream/blob/main/projects/taptostream-frontend/src/hooks/useX402.ts"
click node_api "https://github.com/saheeldev/taptostream/blob/main/server/index.js"
click node_video_catalog "https://github.com/saheeldev/taptostream/blob/main/server/videos.json"
click node_stream_service "https://github.com/saheeldev/taptostream/blob/main/server/stream.js"
click node_payment_middleware "https://github.com/saheeldev/taptostream/blob/main/server/x402.js"
click node_tap_contract "https://github.com/saheeldev/taptostream/blob/main/projects/taptostream-contracts/smart_contracts/tap_to_stream/contract.py"
click node_contract_artifacts "https://github.com/saheeldev/taptostream/blob/main/projects/taptostream-contracts/smart_contracts/artifacts/tap_to_stream/TapToStream.arc56.json"
click node_stream_view "https://github.com/saheeldev/taptostream/blob/main/projects/taptostream-frontend/src/components/WatchModal.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_app,node_home,node_video_card,node_watch_modal,node_wallet_ui,node_wallet_provider,node_stream_view,node_viewer toneBlue
class node_api,node_video_catalog,node_stream_service toneAmber
class node_payment_hook,node_payment_middleware,node_facilitator toneMint
class node_algorand_node,node_tap_contract,node_contract_artifacts toneRose
```

## Components

### Viewer app

- [App shell](https://github.com/saheeldev/taptostream/blob/main/projects/taptostream-frontend/src/App.tsx): `projects/taptostream-frontend/src/App.tsx`
- [Video home](https://github.com/saheeldev/taptostream/blob/main/projects/taptostream-frontend/src/Home.tsx): `projects/taptostream-frontend/src/Home.tsx`
- [Video card](https://github.com/saheeldev/taptostream/blob/main/projects/taptostream-frontend/src/components/VideoCard.tsx): `projects/taptostream-frontend/src/components/VideoCard.tsx`
- [Watch modal](https://github.com/saheeldev/taptostream/blob/main/projects/taptostream-frontend/src/components/WatchModal.tsx): `projects/taptostream-frontend/src/components/WatchModal.tsx`
- [Wallet controls](https://github.com/saheeldev/taptostream/blob/main/projects/taptostream-frontend/src/components/ConnectWallet.tsx): `projects/taptostream-frontend/src/components/ConnectWallet.tsx`
- [Wallet provider](https://github.com/saheeldev/taptostream/blob/main/projects/taptostream-frontend/src/App.tsx): `projects/taptostream-frontend/src/App.tsx`
- [Video playback](https://github.com/saheeldev/taptostream/blob/main/projects/taptostream-frontend/src/components/WatchModal.tsx): `projects/taptostream-frontend/src/components/WatchModal.tsx`

### API and streaming

- [HTTP API](https://github.com/saheeldev/taptostream/blob/main/server/index.js): `server/index.js`
- [Video catalog](https://github.com/saheeldev/taptostream/blob/main/server/videos.json): `server/videos.json`
- [Stream URLs](https://github.com/saheeldev/taptostream/blob/main/server/stream.js): `server/stream.js`

### Payment flow

- [x402 client](https://github.com/saheeldev/taptostream/blob/main/projects/taptostream-frontend/src/hooks/useX402.ts): `projects/taptostream-frontend/src/hooks/useX402.ts`
- [Payment verification](https://github.com/saheeldev/taptostream/blob/main/server/x402.js): `server/x402.js`
- **x402 facilitator**

### Algorand contract

- **Algorand node**
- [TapToStream](https://github.com/saheeldev/taptostream/blob/main/projects/taptostream-contracts/smart_contracts/tap_to_stream/contract.py): `projects/taptostream-contracts/smart_contracts/tap_to_stream/contract.py`
- [Contract artifacts](https://github.com/saheeldev/taptostream/blob/main/projects/taptostream-contracts/smart_contracts/artifacts/tap_to_stream/TapToStream.arc56.json): `projects/taptostream-contracts/smart_contracts/artifacts/tap_to_stream/TapToStream.arc56.json`

### Other components

- **Viewer**

## Connections

- Viewer → App shell: opens app
- App shell → Wallet provider: configures wallet
- App shell → Video home: renders
- Viewer → Wallet controls: connects wallet
- Video home → HTTP API: requests catalog
- HTTP API → Video catalog: reads catalog
- HTTP API → Video home: returns catalog
- Video home → Video card: shows videos
- Video card → Watch modal: opens watch
- Watch modal → x402 client: requests access
- x402 client → Wallet provider: signs transfer
- x402 client → HTTP API: requests watch
- HTTP API → Payment verification: dispatches payment
- Payment verification → Algorand node: broadcasts transfer
- Payment verification → x402 facilitator: verifies payment
- Payment verification → TapToStream: calls payment method
- TapToStream → Algorand node: submits transfers
- TapToStream → Contract artifacts: described by
- HTTP API → Stream URLs: gets signed URL
- Stream URLs → HTTP API: returns stream URL
- HTTP API → x402 client: returns stream URL
- x402 client → Watch modal: returns playback data
- Watch modal → Video playback: loads stream
- Viewer → Video playback: watches video