# re3-1/yotubeblockchain architecture

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

- Interactive diagram: https://gitdiagram.com/re3-1/yotubeblockchain
- Repository: https://github.com/re3-1/yotubeblockchain

## Overview

1. **Overall shape**
   - This is a monorepo for a **tokenized creator marketplace** split into four runtime boundaries: **Solidity contracts**, an **Express backend**, a **React DApp frontend**, and a **Python forecast service**.
   - The main business loop is: creator verification on the backend → channel token and marketplace activity on-chain → trade/analytics data mirrored off-chain → UI renders dashboards and charts → milestone jobs and forecasts enrich the experience.

2. **On-chain core: `contracts/`**
   - The blockchain layer is the source of truth for tokenized assets and marketplace actions.
   - Key contract responsibilities are indicated by the tests and README: **`ChannelToken`**, **`Marketplace`**, **`MilestoneChallenge`**, and likely a **badge NFT** for milestone rewards.
   - Deployment artifacts for **localhost**, **Sepolia**, and **Hardhat** show the contracts are intended to run across local dev and Polygon-oriented testnet/mainnet workflows.
   - Scripts for deploy, direct deploy, verification, and seeding imply the contracts are also used in operational setup and demo initialization.

3. **Backend API and orchestration: `backend/`**
   - The backend is an **Express API** that sits between the frontend and external services, and also between the UI and blockchain where off-chain state is needed.
   - It uses **MongoDB models** for `User`, `Trade`, and `Milestone`, so it persists user accounts, marketplace events, and milestone state outside the chain.
   - This layer is where authentication, creator/channel verification, pricing, IPFS handling, and analytics aggregation are coordinated.

4. **Authentication and identity**
   - `backend/src/services/passport.js` and `middleware/auth.js` indicate the backend manages **Google OAuth-based login** and protects private endpoints.
   - `routes/auth.js` is the entry point for login/session-related behavior.
   - The repo’s architecture suggests the backend owns the trusted identity layer, while the frontend only consumes authenticated API responses and wallet state.

5. **YouTube and platform verification**
   - `backend/src/services/youtube.js` plus `routes/channels.js` and `routes/platforms.js` show the backend verifies creator channels and fetches channel metadata from the **YouTube Data API**.
   - The `services/platforms/` directory contains a platform abstraction with a base adapter and concrete **YouTube** and **Twitch** adapters, so platform-specific logic is isolated behind a common interface.
   - This is a key extensibility boundary: creator identity and channel metadata can come from multiple platforms, but the rest of the system consumes normalized channel data.

6. **Trading, chain access, and pricing**
   - `services/chain.js` is the backend’s chain integration boundary, likely responsible for reading/writing to contracts and reconciling on-chain state.
   - `services/pricing.js` and the dedicated `__tests__/pricing.test.js` indicate pricing is not hardcoded in the UI; it is a backend concern with test coverage.
   - `routes/trades.js`, `routes/analytics.js`, and `routes/forecast.js` suggest the backend exposes market data, trade history, and computed insights to the frontend.

7. **Milestones and background jobs**
   - `routes/milestones.js` exposes milestone-related endpoints, while `jobs/milestoneResolver.js` is a background worker/process that likely evaluates milestone completion.
   - The milestone subsystem bridges off-chain activity with on-chain rewards: it can award bonus tokens or badge NFTs when creator/fan goals are met.
   - This is an important asynchronous boundary in the architecture: milestone state is not just request/response driven; it also depends on scheduled or event-triggered resolution.

8. **IPFS integration**
   - `services/ipfs.js` and `routes/ipfs.js` indicate content or metadata is uploaded/pinned through an IPFS workflow, likely via a service such as Pinata.
   - The frontend includes `IpfsUpload.jsx`, which means users can initiate uploads from the UI, but the backend is the trusted integration point for pinning and returning content hashes/URIs.
   - This is the media/metadata persistence layer for decentralized assets and badge/token metadata.

9. **Frontend DApp: `frontend/`**
   - The frontend is a **React + Vite + Tailwind + Ethers.js** application.
   - `WalletContext.jsx` and `AuthContext.jsx` separate blockchain wallet state from backend-authenticated user state, which matches the app’s dual identity model: wallet ownership plus platform login.
   - Pages such as `CreatorDashboard`, `FanDashboard`, `Marketplace`, `Milestones`, and `Landing` divide the user experience by role and task.
   - Components like `PriceChart`, `ForecastChart`, and `VolumeBadge` show the UI is heavily data-driven and consumes backend analytics/forecast endpoints rather than reading everything directly from chain.

10. **Frontend-to-backend and frontend-to-chain data flow**
   - The frontend’s `api.js` is the API boundary for backend calls.
   - The ABI bundle in `frontend/src/abi/` indicates direct contract interaction via **Ethers.js** for wallet-connected actions, while operational data like authentication, charts, milestones, and IPFS uploads comes from the backend.
   - In practice, the UI is a hybrid client: it talks to the blockchain for transaction execution and to the backend for authoritative off-chain business logic and enriched data.

11. **Forecast service: `forecast/`**
   - The `forecast/` folder is a separate **FastAPI microservice** in Python.
   - The README says it provides AI price forecasting using **Holt-Winters + linear regression**, which makes it a specialized analytics service rather than part of the main Node backend.
   - This service likely receives historical pricing/volume inputs and returns predictions consumed by frontend charts or backend analytics endpoints.

12. **Analytics and reporting**
   - `backend/src/routes/analytics.js` and frontend components like `PriceChart`, `ForecastChart`, and `VolumeBadge` show that historical market data is surfaced as first-class product functionality.
   - The `Trade` model suggests the backend stores trade records for aggregation, charting, and possibly reconciliation against on-chain events.
   - This analytics layer is the read-optimized side of the system, separate from the write-heavy chain interactions.

13. **Testing and CI**
   - There are three major test surfaces: **Hardhat contract tests** in `contracts/test`, **Jest backend tests** in `backend/__tests__`, and a **frontend build** step in CI.
   - `.github/workflows/ci.yml` plus the README mention contract checks, backend tests, frontend build, and **Slither** analysis, so the repo treats security and deployment readiness as part of the pipeline.
   - This supports a multi-boundary architecture where correctness is validated independently at the contract, API, and UI layers.

14. **Deployment/runtime boundaries**
   - Each runtime has its own packaging: backend and forecast both have Dockerfiles, frontend is Vercel-oriented, and contracts use Hardhat deployment scripts.
   - The repo is therefore designed for separate deployment of the chain, API, UI, and AI service, which is important for diagramming because each has different scaling and trust characteristics.
   - External services materially shaping the architecture are **Polygon**, **Google OAuth**, **YouTube Data API**, **MongoDB**, **IPFS/Pinata**, and the forecast service’s Python ML stack.

Main entry points: [`backend/src/index.js`](https://github.com/re3-1/yotubeblockchain/blob/main/backend/src/index.js) (Express API), [`frontend/src/App.jsx`](https://github.com/re3-1/yotubeblockchain/blob/main/frontend/src/App.jsx) (React App), [`contracts/contracts`](https://github.com/re3-1/yotubeblockchain/tree/main/contracts/contracts) (Contracts), [`.github/workflows/ci.yml`](https://github.com/re3-1/yotubeblockchain/blob/main/.github/workflows/ci.yml) (CI Pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_onchain["On-chain"]
  node_contracts_core["Contracts<br/>solidity suite"]
  node_contracts_deploy["Deploy Scripts<br/>deployment"]
  node_contracts_tests["Contract Tests<br/>hardhat tests"]
end

subgraph group_backend["Backend API"]
  node_backend_api["Express API<br/>node service<br/>[index.js]"]
  node_backend_auth["Auth Layer<br/>oauth session<br/>[passport.js]"]
  node_backend_platforms["Platform Adapters<br/>platform integration"]
  node_backend_chain["Chain Service<br/>web3 bridge<br/>[chain.js]"]
  node_backend_domain["Models & Routes<br/>domain API"]
  node_backend_jobs["Milestone Job<br/>worker"]
  node_backend_ipfs["IPFS Service<br/>content pinning<br/>[ipfs.js]"]
end

subgraph group_frontend["Frontend DApp"]
  node_frontend_app["React App<br/>dapp client<br/>[App.jsx]"]
  node_frontend_contexts["Contexts<br/>state layer"]
  node_frontend_pages["Dashboards<br/>ui pages"]
  node_frontend_charts["Charts & Uploads<br/>ui components"]
  node_frontend_api["API + ABI<br/>client integration<br/>[api.js]"]
end

subgraph group_forecast["Forecast Service"]
  node_forecast_api["Forecast API<br/>fastapi service<br/>[app.py]"]
end

subgraph group_ops["CI / Ops"]
  node_ci_pipeline["CI Pipeline<br/>automation<br/>[ci.yml]"]
end

node_backend_api -->|"uses"| node_backend_auth
node_backend_api -->|"normalizes"| node_backend_platforms
node_backend_api -->|"syncs"| node_backend_chain
node_backend_api -->|"serves"| node_backend_domain
node_backend_api -.->|"triggers"| node_backend_jobs
node_backend_domain -->|"uploads"| node_backend_ipfs
node_backend_domain -->|"queries"| node_forecast_api
node_backend_domain -.->|"reflects"| node_contracts_core
node_backend_jobs -.->|"awards"| node_contracts_core
node_frontend_app -->|"holds"| node_frontend_contexts
node_frontend_app -->|"renders"| node_frontend_pages
node_frontend_app -->|"composes"| node_frontend_charts
node_frontend_app -->|"fetches"| node_frontend_api
node_frontend_api -->|"calls"| node_backend_api
node_frontend_api -->|"transacts"| node_contracts_core
node_contracts_deploy -->|"deploys"| node_contracts_core
node_contracts_tests -->|"verifies"| node_contracts_core
node_ci_pipeline -->|"checks"| node_contracts_tests
node_ci_pipeline -->|"tests"| node_backend_api
node_ci_pipeline -->|"builds"| node_frontend_app
node_ci_pipeline -.->|"packages"| node_forecast_api

click node_contracts_core "https://github.com/re3-1/yotubeblockchain/tree/main/contracts/contracts"
click node_contracts_deploy "https://github.com/re3-1/yotubeblockchain/tree/main/contracts/scripts"
click node_contracts_tests "https://github.com/re3-1/yotubeblockchain/tree/main/contracts/test"
click node_backend_api "https://github.com/re3-1/yotubeblockchain/blob/main/backend/src/index.js"
click node_backend_auth "https://github.com/re3-1/yotubeblockchain/blob/main/backend/src/services/passport.js"
click node_backend_platforms "https://github.com/re3-1/yotubeblockchain/tree/main/backend/src/services/platforms"
click node_backend_chain "https://github.com/re3-1/yotubeblockchain/blob/main/backend/src/services/chain.js"
click node_backend_domain "https://github.com/re3-1/yotubeblockchain/tree/main/backend/src/routes"
click node_backend_jobs "https://github.com/re3-1/yotubeblockchain/blob/main/backend/src/jobs/milestoneResolver.js"
click node_backend_ipfs "https://github.com/re3-1/yotubeblockchain/blob/main/backend/src/services/ipfs.js"
click node_frontend_app "https://github.com/re3-1/yotubeblockchain/blob/main/frontend/src/App.jsx"
click node_frontend_contexts "https://github.com/re3-1/yotubeblockchain/tree/main/frontend/src/context"
click node_frontend_pages "https://github.com/re3-1/yotubeblockchain/tree/main/frontend/src/pages"
click node_frontend_charts "https://github.com/re3-1/yotubeblockchain/tree/main/frontend/src/components"
click node_frontend_api "https://github.com/re3-1/yotubeblockchain/blob/main/frontend/src/api.js"
click node_forecast_api "https://github.com/re3-1/yotubeblockchain/blob/main/forecast/app.py"
click node_ci_pipeline "https://github.com/re3-1/yotubeblockchain/blob/main/.github/workflows/ci.yml"

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_contracts_core,node_contracts_deploy,node_contracts_tests toneBlue
class node_backend_api,node_backend_auth,node_backend_platforms,node_backend_chain,node_backend_domain,node_backend_jobs,node_backend_ipfs toneAmber
class node_frontend_app,node_frontend_contexts,node_frontend_pages,node_frontend_charts,node_frontend_api toneMint
class node_forecast_api toneRose
class node_ci_pipeline toneIndigo
```

## Components

### On-chain

Solidity contracts, deployment, and Hardhat workflow

- [Contracts](https://github.com/re3-1/yotubeblockchain/tree/main/contracts/contracts): solidity suite · Token, marketplace, milestone, and reward contracts · `contracts/contracts`
- [Deploy Scripts](https://github.com/re3-1/yotubeblockchain/tree/main/contracts/scripts): deployment · Hardhat deployment, verification, and seeding scripts · `contracts/scripts`
- [Contract Tests](https://github.com/re3-1/yotubeblockchain/tree/main/contracts/test): hardhat tests · On-chain behavior tests for core contracts · `contracts/test`

### Backend API

Express API, persistence, integrations, and jobs

- [Express API](https://github.com/re3-1/yotubeblockchain/blob/main/backend/src/index.js): node service · HTTP entrypoint for auth, data, and orchestration · `backend/src/index.js`
- [Auth Layer](https://github.com/re3-1/yotubeblockchain/blob/main/backend/src/services/passport.js): oauth session · Google OAuth, middleware, and session protection · `backend/src/services/passport.js`
- [Platform Adapters](https://github.com/re3-1/yotubeblockchain/tree/main/backend/src/services/platforms): platform integration · Normalized creator-platform adapters for YouTube and Twitch · `backend/src/services/platforms`
- [Chain Service](https://github.com/re3-1/yotubeblockchain/blob/main/backend/src/services/chain.js): web3 bridge · Reads and writes blockchain state from the backend · `backend/src/services/chain.js`
- [Models & Routes](https://github.com/re3-1/yotubeblockchain/tree/main/backend/src/routes): domain API · Users, trades, milestones, analytics, and platform endpoints · `backend/src/routes`
- [Milestone Job](https://github.com/re3-1/yotubeblockchain/blob/main/backend/src/jobs/milestoneResolver.js): worker · Background milestone resolution and reward triggering · `backend/src/jobs/milestoneResolver.js`
- [IPFS Service](https://github.com/re3-1/yotubeblockchain/blob/main/backend/src/services/ipfs.js): content pinning · Uploads and pins metadata or media for decentralized assets · `backend/src/services/ipfs.js`

### Frontend DApp

React client, state, pages, and charts

- [React App](https://github.com/re3-1/yotubeblockchain/blob/main/frontend/src/App.jsx): dapp client · Vite-based client that combines wallet and authenticated state · `frontend/src/App.jsx`
- [Contexts](https://github.com/re3-1/yotubeblockchain/tree/main/frontend/src/context): state layer · Wallet and backend-auth state management · `frontend/src/context`
- [Dashboards](https://github.com/re3-1/yotubeblockchain/tree/main/frontend/src/pages): ui pages · Role-based pages for creators, fans, marketplace, and milestones · `frontend/src/pages`
- [Charts & Uploads](https://github.com/re3-1/yotubeblockchain/tree/main/frontend/src/components): ui components · Price, forecast, volume, and IPFS upload components · `frontend/src/components`
- [API + ABI](https://github.com/re3-1/yotubeblockchain/blob/main/frontend/src/api.js): client integration · Backend API client plus direct contract ABI bindings · `frontend/src/api.js`

### Forecast Service

Python analytics microservice

- [Forecast API](https://github.com/re3-1/yotubeblockchain/blob/main/forecast/app.py): fastapi service · Python price forecasting microservice · `forecast/app.py`

### CI / Ops

Repository-wide testing and release automation

- [CI Pipeline](https://github.com/re3-1/yotubeblockchain/blob/main/.github/workflows/ci.yml): automation · Build, test, and security checks across the repo · `.github/workflows/ci.yml`

## Connections

- Express API → Auth Layer: uses · API protects routes and establishes user identity
- Express API → Platform Adapters: normalizes · API delegates creator platform lookups to adapters
- Express API → Chain Service: syncs · API reconciles off-chain requests with on-chain state
- Express API → Models & Routes: serves · Routes expose auth, trades, analytics, milestones, and IPFS
- Express API → Milestone Job: triggers · Milestone processing is also handled asynchronously
- Models & Routes → IPFS Service: uploads · IPFS endpoints back media and metadata workflows
- Models & Routes → Forecast API: queries · Forecast and analytics endpoints consume prediction service output
- Models & Routes → Contracts: reflects · Backend models mirror on-chain trading and milestone activity
- Milestone Job → Contracts: awards · Resolved milestones can trigger on-chain rewards
- React App → Contexts: holds · Client state separates wallet and authenticated identity
- React App → Dashboards: renders · Pages drive creator, fan, marketplace, and milestone flows
- React App → Charts & Uploads: composes · Dashboards embed charts and upload widgets
- React App → API + ABI: fetches · UI calls backend APIs and contract bindings
- API + ABI → Express API: calls · Client API layer talks to the Express backend
- API + ABI → Contracts: transacts · Wallet-connected actions use contract ABIs
- Deploy Scripts → Contracts: deploys · Scripts publish core contracts to target networks
- Contract Tests → Contracts: verifies · Hardhat tests validate contract behavior
- CI Pipeline → Contract Tests: checks · CI runs contract validation
- CI Pipeline → Express API: tests · CI runs backend test suite
- CI Pipeline → React App: builds · CI verifies frontend build output
- CI Pipeline → Forecast API: packages · CI includes the forecast service runtime
