# charclub/marketplace architecture

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

- Interactive diagram: https://gitdiagram.com/charclub/marketplace
- Repository: https://github.com/charclub/marketplace

## Overview

##### Project Type and Purpose
- CharclubMarketplace is a full-stack DApp (decentralized application) targeting the Internet Computer.
- The “backend” consists of one or more Motoko canisters (smart contracts) that implement marketplace logic, token management, and threshold cryptography.
- The “frontend” is a React/Vite application (TypeScript + TailwindCSS) that interacts with those canisters via the IC actor model.

##### File Structure Analysis
- Top-level config:
- dfx.json & canister_ids.json – define local vs. IC canister IDs and build settings
- package.json / pnpm-workspace.yaml – monorepo package management
- .github/workflows/deployment.yml & scripts/submit-deploy.sh – CI/CD pipeline
- src/backend – Motoko source for the core marketplace canister (main.mo, types.mo, plus hash/utility modules)
- src/threshold – Motoko source for a threshold-crypto canister (main.mo)
- src/frontend – React app structured into:
- public/ – static assets & DFX asset canister bundle
- src/components, hooks, contexts, pages, routes – React + TS + IC actor integration
- idl.ts, actor creation under utils/icp-ledger.ts
- README.md – describes local DFX workflow, actor generation, frontend proxying to replica.

##### Key Architectural Patterns
- Microservices via independent canisters (each Motoko module is its own deployable unit)
- Actor model: frontend uses autogenerated Candid interfaces and createActor() wrappers
- React component hierarchy with Contexts (Auth, Actor) and Hooks for data fetching
- Monorepo using PNPM workspaces for both backend and frontend code
- CI/CD: GitHub Actions triggers dfx canister deploy via script

1. Developer Workstation
- dfx CLI, pnpm, VSCode (local dev tools)
2. DFX Local Replica
- HTTP endpoints for canisters (port 4943)
3. Asset Canister
- Serves static frontend bundle
4. Marketplace Canister
- Implements NFT listing, buying, metadata storage
5. Threshold Canister
- Handles multi-party crypto operations, key shares
6. React Frontend (Browser)
- Runs on Vite dev server (port 8080) or served from asset canister
7. GitHub Actions / CI Pipeline
- deployment.yml, submit-deploy.sh

- Developer → (dfx start/deploy) → DFX Local Replica
- DFX Local Replica ↔ Asset Canister (static file hosting)
- Browser → HTTP GET → Asset Canister or Vite Dev Server
- Browser → Actor (Candid over HTTP) → Marketplace Canister
- Browser → Actor → Threshold Canister
- GitHub Actions → dfx canister deploy → IC Mainnet / Testnet

- Architectural Highlights:
- Separation of concerns: static asset hosting vs. business logic canisters
- Each canister is independent, enabling parallel development, separate upgrade cycles
- React Contexts centralize actor instances and authentication state
- Hooks abstract Candid queries/mutations (ICRC-7 token queries, pricing, balances)

- Technology Stack Labels:
- Motoko (canisters)
- Internet Computer replica / IC network
- React + Vite + TypeScript + Tailwind
- PNPM Monorepo
- GitHub Actions

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Developer Tools"
        DW["Developer Workstation"]:::devTools
    end

    subgraph "Local Development"
        DFX["DFX Local Replica\n(port 4943)"]:::canister
    end

    subgraph "Blockchain Layer"
        AC["Asset Canister"]:::canister
        MC["Marketplace Canister"]:::canister
        TC["Threshold Canister"]:::canister
    end

    subgraph "Frontend"
        Browser["React Frontend\n(Browser / Vite)"]:::frontend
        ActorLayer["Actor Interface Layer"]:::frontend
    end

    subgraph "CI/CD Pipeline"
        CI["GitHub Actions"]:::ci
    end

    %% Connections
    DW -->|"dfx start/deploy"| DFX
    DW -->|"pnpm start"| Browser
    DFX -->|"HTTP endpoints"| AC
    Browser -->|"HTTP GET"| AC
    Browser -->|"Candid call"| MC
    Browser -->|"Candid call"| TC
    CI -->|"dfx canister deploy"| MC
    CI -->|"dfx canister deploy"| TC
    CI -->|"dfx canister deploy"| AC

    %% Click Events
    click DW "https://github.com/charclub/marketplace/blob/main/dfx.json"
    click DW "https://github.com/charclub/marketplace/blob/main/pnpm-workspace.yaml"
    click DW "https://github.com/charclub/marketplace/blob/main/package.json"
    click DW "https://github.com/charclub/marketplace/blob/main/README.md"

    click DFX "https://github.com/charclub/marketplace/blob/main/dfx.json"
    click DFX "https://github.com/charclub/marketplace/blob/main/canister_ids.json"

    click AC "https://github.com/charclub/marketplace/tree/main/src/frontend/public/"

    click MC "https://github.com/charclub/marketplace/blob/main/src/backend/main.mo"
    click MC "https://github.com/charclub/marketplace/blob/main/src/backend/types.mo"
    click MC "https://github.com/charclub/marketplace/blob/main/src/backend/utils/CRC32.mo"
    click MC "https://github.com/charclub/marketplace/blob/main/src/backend/utils/SHA224.mo"
    click MC "https://github.com/charclub/marketplace/blob/main/src/backend/utils/SHA256.mo"
    click MC "https://github.com/charclub/marketplace/blob/main/src/backend/utils/hex.mo"
    click MC "https://github.com/charclub/marketplace/blob/main/src/backend/utils/lib.mo"
    click MC "https://github.com/charclub/marketplace/blob/main/src/backend/utils/types.mo"

    click TC "https://github.com/charclub/marketplace/blob/main/src/threshold/main.mo"

    click Browser "https://github.com/charclub/marketplace/blob/main/src/frontend/index.html"
    click Browser "https://github.com/charclub/marketplace/blob/main/src/frontend/vite.config.ts"
    click Browser "https://github.com/charclub/marketplace/blob/main/src/frontend/tailwind.config.ts"
    click Browser "https://github.com/charclub/marketplace/blob/main/src/frontend/tsconfig.app.json"
    click Browser "https://github.com/charclub/marketplace/tree/main/src/frontend/public/"
    click Browser "https://github.com/charclub/marketplace/blob/main/src/frontend/src/main.tsx"
    click Browser "https://github.com/charclub/marketplace/blob/main/src/frontend/src/App.tsx"
    click Browser "https://github.com/charclub/marketplace/blob/main/src/frontend/src/contexts/Actor.tsx"
    click Browser "https://github.com/charclub/marketplace/blob/main/src/frontend/src/contexts/Auth.tsx"
    click Browser "https://github.com/charclub/marketplace/blob/main/src/frontend/src/hooks/actor.tsx"
    click Browser "https://github.com/charclub/marketplace/blob/main/src/frontend/src/hooks/auth.tsx"
    click Browser "https://github.com/charclub/marketplace/blob/main/src/frontend/src/libs/icp-ledger.ts"

    click ActorLayer "https://github.com/charclub/marketplace/blob/main/src/frontend/src/types/idl.ts"
    click ActorLayer "https://github.com/charclub/marketplace/blob/main/src/frontend/src/utils/idl.ts"
    click ActorLayer "https://github.com/charclub/marketplace/blob/main/src/frontend/src/libs/icp-ledger.ts"

    click CI "https://github.com/charclub/marketplace/blob/main/.github/workflows/deployment.yml"
    click CI "https://github.com/charclub/marketplace/blob/main/.github/scripts/submit-deploy.sh"

    %% Styles
    classDef devTools fill:#D0E8FF,stroke:#000;
    classDef canister fill:#D4F4DD,stroke:#000;
    classDef frontend fill:#FFDAB9,stroke:#000;
    classDef ci fill:#E0E0E0,stroke:#000;
```
