# hoanlv214/js-recall architecture

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

- Interactive diagram: https://gitdiagram.com/hoanlv214/js-recall
- Repository: https://github.com/hoanlv214/js-recall

## Overview

##### Project type and purpose
- This is a JavaScript/TypeScript monorepo (Turborepo + pnpm workspaces) named “js-recall.”
- It hosts two Next.js web applications under apps/—“portal” (main user dashboard) and “faucet” (test‐token dispenser)—plus a suite of shared packages under packages/ that implement:
– Core SDK (@recallnet/sdk) for interacting with the Recall network
– Extended SDK features (@recallnet/sdkx)
– A React UI component library (@recallnet/ui)
– Smart‐contract interfaces, chain configs, utilities (contracts, chains, address‐utils, bigint‐utils, fvm, network‐constants), tooling (agent-toolkit), and configuration packages (eslint-config, typescript-config, fonts).

##### File structure
- Top-level orchestrator:
– pnpm-workspace.yaml + turbo.json define the workspace and build pipelines.
– GitHub workflows (.github/workflows) handle CI (lint/test/build) and releases.
- Apps:
– apps/portal (Next.js 13+ with server/client components, Tailwind, custom hooks, API routes via next middleware, uses wagmi for wallet connections)
– apps/faucet (Next.js, simple token request UI)
- Shared packages:
– SDK layer (packages/sdk, packages/sdkx)
– UI layer (packages/ui)
– Domain & utilities (contracts, chains, fvm, network-constants, address-utils, bigint-utils)
– Tooling & config (eslint-config, typescript-config, fonts, agent-toolkit)

##### README for additional insights
- Confirms monorepo structure, development commands, per-package usage.
- Emphasizes use of Cursor for AI‐assisted development, but that does not impact runtime architecture.

##### Main components
- Monorepo workspace (Turborepo + pnpm) – build/orchestration layer
- CI/CD pipeline (GitHub Actions: code-quality, release)
- Applications (containers or rectangles):
– Portal (Next.js web app)
– Faucet (Next.js web app)
- Shared package modules (grouped under “packages”):
– SDK (@recallnet/sdk) – blockchain client layer
– SDKX (@recallnet/sdkx) – extended features
– UI (@recallnet/ui) – React components + theming
– Contracts, chains, address-utils, bigint-utils, fvm, network-constants – domain/data libraries
– Agent-toolkit – CLI/automation
- External services / networks:
– Recall network (blockchain nodes / IPFS)
– Wallet providers (e.g., MetaMask, WalletConnect)
– (Optional) Deployment platform (e.g., Vercel / Netlify)

##### Relationships and interactions
- Developer Workstation → pushes code → GitHub → triggers CI/CD → builds & publishes packages and apps.
- Portal & Faucet import shared packages at build time (pnpm workspace symlinks)
- At runtime:
– Browser users → interact with portal/faucet UI (React)
– Next.js server components / API routes → call @recallnet/sdk (and sdkx)
– SDK → RPC calls to blockchain nodes / IPFS gateways → ledger & storage
– Wallet connectors → user signatures → smart-contract interactions
- Agent-toolkit & other CLI tools are used by developers (not part of the runtime path).

##### Architectural patterns & design principles
- Monorepo modularity: clear separation of concerns between applications and libraries
- Next.js duality: server‐side rendering & client‐side interactivity
- Layered architecture:
– Presentation layer (packages/ui + Next.js pages/components)
– Application layer (apps/… custom logic, hooks, API routes)
– Domain layer (SDK + domain utilities + contracts)
– Infrastructure / external layer (blockchain, storage, CI/CD)
- Reusability: all business logic in packages, UI in a shared library, avoiding duplication.

##### Key details to capture
- Monorepo structure (two apps + many packages) and build orchestration
- Next.js apps consuming shared UI & domain libraries
- SDK as the single gateway to Recall network interactions
- External dependencies: blockchain nodes, IPFS, wallet connectors
- CI/CD workflows automating tests, builds, versioning, and publish

## Diagram (Mermaid)

```mermaid
flowchart TD
    Developer(["Developer Workstation"]):::external
    GitHub(["GitHub Repository"]):::ci
    CI(["CI/CD Pipeline\n(GitHub Actions)"]):::ci
    Workspace(["Monorepo Workspace\n(Turborepo + pnpm)"]):::orchestrator

    subgraph "Applications"
        Portal(["Portal Web App\n(Next.js)"]):::app
        Faucet(["Faucet Web App\n(Next.js)"]):::app
    end

    subgraph "Packages"
        SDK(["@recallnet/sdk"]):::package
        SDKX(["@recallnet/sdkx"]):::package
        UI(["@recallnet/ui"]):::package
        Contracts(["Contracts Interfaces"]):::package
        Chains(["Chain Configurations"]):::package
        AddressUtils(["Address Utilities"]):::package
        BigIntUtils(["BigInt Utilities"]):::package
        FVM(["FVM Utilities"]):::package
        NetConstants(["Network Constants"]):::package
        Agent(["Agent Toolkit"]):::package
        ESLintCfg(["ESLint Config"]):::package
        TSConfig(["TypeScript Config"]):::package
        Fonts(["Fonts Package"]):::package
    end

    subgraph "External Services"
        Browser(["Browser Users"]):::external
        Wallet(["Wallet Providers"]):::external
        BC(["Recall Network\n(Blockchain Nodes)"]):::external
        IPFS(["IPFS Gateways"]):::external
        Deployment(["Vercel/Netlify\n(Deployment)"]):::external
    end

    Developer -->|"push code"| GitHub
    GitHub -->|"triggers"| CI
    CI -->|"build pipeline"| Workspace

    Workspace --> Portal
    Workspace --> Faucet
    Workspace --> SDK
    Workspace --> SDKX
    Workspace --> UI
    Workspace --> Contracts
    Workspace --> Chains
    Workspace --> AddressUtils
    Workspace --> BigIntUtils
    Workspace --> FVM
    Workspace --> NetConstants
    Workspace --> Agent
    Workspace --> ESLintCfg
    Workspace --> TSConfig
    Workspace --> Fonts

    CI -->|"deploy apps"| Deployment
    Deployment --> Portal
    Deployment --> Faucet

    Browser --> Portal
    Browser --> Faucet

    Portal --> UI
    Portal --> SDK
    Portal --> SDKX
    Portal --> Contracts
    Portal --> Chains
    Portal --> AddressUtils
    Portal --> BigIntUtils
    Portal --> FVM
    Portal --> NetConstants

    Faucet --> UI
    Faucet --> SDK

    SDK --> BC
    SDK --> IPFS

    Wallet --> Portal
    Wallet --> Faucet

    click Workspace "https://github.com/hoanlv214/js-recall/blob/main/pnpm-workspace.yaml"
    click Workspace "https://github.com/hoanlv214/js-recall/blob/main/turbo.json"
    click CI "https://github.com/hoanlv214/js-recall/blob/main/.github/workflows/code-quality.yml"
    click CI "https://github.com/hoanlv214/js-recall/blob/main/.github/workflows/release.yml"
    click Portal "https://github.com/hoanlv214/js-recall/tree/main/apps/portal/"
    click Faucet "https://github.com/hoanlv214/js-recall/tree/main/apps/faucet/"
    click SDK "https://github.com/hoanlv214/js-recall/tree/main/packages/sdk/"
    click SDKX "https://github.com/hoanlv214/js-recall/tree/main/packages/sdkx/"
    click UI "https://github.com/hoanlv214/js-recall/tree/main/packages/ui/"
    click Contracts "https://github.com/hoanlv214/js-recall/tree/main/packages/contracts/"
    click Chains "https://github.com/hoanlv214/js-recall/tree/main/packages/chains/"
    click AddressUtils "https://github.com/hoanlv214/js-recall/tree/main/packages/address-utils/"
    click BigIntUtils "https://github.com/hoanlv214/js-recall/tree/main/packages/bigint-utils/"
    click FVM "https://github.com/hoanlv214/js-recall/tree/main/packages/fvm/"
    click NetConstants "https://github.com/hoanlv214/js-recall/tree/main/packages/network-constants/"
    click Agent "https://github.com/hoanlv214/js-recall/tree/main/packages/agent-toolkit/"
    click ESLintCfg "https://github.com/hoanlv214/js-recall/tree/main/packages/eslint-config/"
    click TSConfig "https://github.com/hoanlv214/js-recall/tree/main/packages/typescript-config/"
    click Fonts "https://github.com/hoanlv214/js-recall/tree/main/packages/fonts/"

    classDef orchestrator fill:#fdf,stroke:#933,stroke-width:2px
    classDef ci fill:#eef,stroke:#336,stroke-width:2px
    classDef app fill:#dfd,stroke:#262,stroke-width:2px
    classDef package fill:#ffd,stroke:#aa6,stroke-width:1px
    classDef external fill:#fee,stroke:#911,stroke-width:2px
```
