# jumperexchange/jumper-exchange architecture

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

- Interactive diagram: https://gitdiagram.com/jumperexchange/jumper-exchange
- Repository: https://github.com/jumperexchange/jumper-exchange

## Overview

##### Project type & purpose
- Jumper.Exchange is a full-stack, React/Next.js 13 App-Router application that serves as the web frontend for the Jumper.Exchange service.
- It delivers UI pages, handles client-side interactions (wallet connections, routing, widget flows) and implements backend logic via Next.js API routes.
- It integrates with external blockchain networks, headless CMS (Strapi), Merkl API, analytics (PostHog), error tracking (Sentry), and is containerized & deployed via GitHub Actions to GCP.

##### High-level file structure insights
- Top-level config & infra:
– Dockerfile, .dockerignore, .github/workflows (build, multi-tag push, deploy to staging/production), .github/actions/init-gcp
– next.config.mjs, gen-api.sh, instrumentation.ts / instrumentation-client.ts, sentry.edge.config.ts, sentry.server.config.ts
- “src/app”: Next.js App-Router pages + layouts, plus “src/app/api” for serverless routes (env-config, profile, widget-* endpoints)
- “src/components” & “src/app/ui”: React component library & page-specific UI
- “src/providers” & “src/hooks” & “src/stores”: application-wide contexts, side-effect logic, global state management
- “src/utils” & “src/lib” & “src/config”: fetch wrappers, URL‐builders, third-party integrations (StrapiApi, MerklApi, RPC shuffling)
- “public”: static assets & manifest
- Tests & storybook: component stories (.storybook), end-to-end & unit tests (Playwright, Vitest)

##### Extracted deployment & runtime details from README
- Uses pnpm, Vite dev server scripts for different backends (develop, local, staging, production)
- CI/CD pipeline builds Docker image, pushes multi tags, deploys to GCP via GitHub Actions
- Husky, lint-staged, Prettier & ESLint enforce code quality

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Side"
        direction TB
        Client["Client Browser"]:::frontend
        CDN["CDN / Static Asset Host"]:::frontend
        ReactApp["React App"]:::frontend
    end
    Client -->|downloads JS/CSS| CDN
    CDN --> ReactApp

    %% Next.js Server Layer
    subgraph "Next.js Server" 
        direction TB
        Server["Next.js App Server"]:::backend
        subgraph "Pages & Layouts"
            direction TB
            Pages["Pages & Layouts"]:::frontend
        end
        subgraph "API Layer"
            direction TB
            WidgetAPI["Widget API Routes"]:::api
            ProfileAPI["Profile API"]:::api
            EnvConfigAPI["Env-Config API"]:::api
        end
        subgraph "UI Components"
            direction TB
            SharedUI["React Component Library"]:::frontend
            PageUI["Page-specific UI"]:::frontend
        end
        subgraph "Domain Layer"
            direction TB
            Providers["Context Providers"]:::backend
            Hooks["Custom Hooks"]:::backend
            Stores["Global State Stores"]:::backend
        end
        subgraph "Data Layer"
            direction TB
            StrapiUtil["Strapi Integration"]:::external
            MerklUtil["Merkl Integration"]:::external
            RpcUtil["RPC Wrappers"]:::external
        end
    end

    ReactApp -->|SSR/SSG or API calls| Server
    Server -->|renders Pages & Layouts| Pages
    Pages --> SharedUI
    Pages --> PageUI
    Server --> WidgetAPI
    Server --> ProfileAPI
    Server --> EnvConfigAPI

    %% External Services
    subgraph "External Services"
        direction TB
        Strapi["Strapi CMS"]:::external
        Merkl["Merkl API"]:::external
        BackendAPI["Jumper.Backend API"]:::external
        RPCNodes["Blockchain RPC Nodes"]:::external
        PostHog["PostHog Analytics"]:::external
        Sentry["Sentry (Edge & Server)"]:::external
    end

    RpcUtil --> RPCNodes
    Server -->|fetch data| Strapi
    Server -->|fetch data| Merkl
    Server -->|fetch data| BackendAPI
    ReactApp -->|fetch/utils| BackendAPI
    ReactApp -->|transactions| RPCNodes
    ReactApp -->|events| PostHog
    Server -->|events| PostHog
    ReactApp -->|errors| Sentry
    Server -->|errors| Sentry

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline" 
        direction TB
        GHActions["GitHub Actions"]:::pipeline
        DockerReg["Container Registry"]:::pipeline
        GCP["GCP Deploy"]:::pipeline
    end
    GHActions -->|build Docker image| DockerReg
    DockerReg -->|deploy| GCP
    GHActions -->|trigger on push| Server

    %% Click Events
    click Server "https://github.com/jumperexchange/jumper-exchange/tree/develop/src/app/"
    click WidgetAPI "https://github.com/jumperexchange/jumper-exchange/tree/develop/src/app/api/"
    click SharedUI "https://github.com/jumperexchange/jumper-exchange/tree/develop/src/components/"
    click PageUI "https://github.com/jumperexchange/jumper-exchange/tree/develop/src/app/ui/"
    click Providers "https://github.com/jumperexchange/jumper-exchange/tree/develop/src/providers/"
    click Hooks "https://github.com/jumperexchange/jumper-exchange/tree/develop/src/hooks/"
    click Stores "https://github.com/jumperexchange/jumper-exchange/tree/develop/src/stores/"
    click StrapiUtil "https://github.com/jumperexchange/jumper-exchange/tree/develop/src/utils/strapi/"
    click MerklUtil "https://github.com/jumperexchange/jumper-exchange/tree/develop/src/utils/merkl/"
    click RpcUtil "https://github.com/jumperexchange/jumper-exchange/tree/develop/src/utils/rpc/"
    click CallReq "https://github.com/jumperexchange/jumper-exchange/blob/develop/src/utils/callRequest.ts"
    click BuildUrl "https://github.com/jumperexchange/jumper-exchange/blob/develop/src/utils/buildUrl.ts"
    click AppLib "https://github.com/jumperexchange/jumper-exchange/tree/develop/src/app/lib/"
    click NextConfig "https://github.com/jumperexchange/jumper-exchange/blob/develop/next.config.mjs"
    click GenApi "https://github.com/jumperexchange/jumper-exchange/blob/develop/gen-api.sh"
    click InstrServer "https://github.com/jumperexchange/jumper-exchange/blob/develop/instrumentation.ts"
    click InstrClient "https://github.com/jumperexchange/jumper-exchange/blob/develop/instrumentation-client.ts"
    click SentryEdge "https://github.com/jumperexchange/jumper-exchange/blob/develop/sentry.edge.config.ts"
    click SentryServer "https://github.com/jumperexchange/jumper-exchange/blob/develop/sentry.server.config.ts"
    click EnvConfigFile "https://github.com/jumperexchange/jumper-exchange/tree/develop/src/config/"
    click ApiEnv "https://github.com/jumperexchange/jumper-exchange/blob/develop/src/app/api/env-config.js"
    click Public "https://github.com/jumperexchange/jumper-exchange/tree/develop/public/"
    click Dockerfile "https://github.com/jumperexchange/jumper-exchange/tree/develop/Dockerfile"
    click DockerIg "https://github.com/jumperexchange/jumper-exchange/blob/develop/.dockerignore"
    click GHWF "https://github.com/jumperexchange/jumper-exchange/tree/develop/.github/workflows/"
    click InitGcp "https://github.com/jumperexchange/jumper-exchange/tree/develop/.github/actions/init-gcp/"
    click Story "https://github.com/jumperexchange/jumper-exchange/tree/develop/.storybook/"
    click Tests "https://github.com/jumperexchange/jumper-exchange/tree/develop/tests/"
    click PlayW "https://github.com/jumperexchange/jumper-exchange/blob/develop/playwright.config.ts"
    click Vitest "https://github.com/jumperexchange/jumper-exchange/blob/develop/vitest.config.ts"

    %% Styles
    classDef frontend fill:#BEE3F8,stroke:#3182CE,color:#1A365D;
    classDef backend fill:#90CDF4,stroke:#2B6CB0,color:#1A365D;
    classDef api fill:#63B3ED,stroke:#2C5282,color:#1A365D;
    classDef external fill:#E2E8F0,stroke:#4A5568,color:#1A365D,stroke-dasharray: 5 5;
    classDef pipeline fill:#C6F6D5,stroke:#2F855A,color:#1A365D,stroke-dasharray: 2 2
```
