# evolify/pumpfun architecture

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

- Interactive diagram: https://gitdiagram.com/evolify/pumpfun
- Repository: https://github.com/evolify/pumpfun

## Overview

##### Project Type and Purpose
- This is a Next.js 13 full-stack PWA (Progressive Web App) focused on listing, sorting, filtering, and swapping “pump.fun” tokens.
- It uses the new App Router (`app/`), a small backend API route for pumping data, client-side state management, and a Service Worker for offline support.

##### File Structure
Top-level directories and roles:
- app/
– `app/page.tsx`, `app/layout.tsx`: Root layout and page shells
– `app/modules/`: Reusable UI modules (list/detail, header, reload button, loading spinner)
– `app/api/pump/route.ts`: Internal API endpoint to fetch pump token data
– `app/store.ts`: Client-side state management (e.g., Zustand or Context)
– `app/sw.ts`, `public/sw.js`: Service Worker registration and script
– `app/~offline/`: Offline fallback page
- common/
– `common/api/`, `common/hooks/`: API helper functions and React hooks (e.g., `usePump`)
– `common/ui/`: Component library (buttons, loading, popovers, theme toggle)
– `common/utils/`: General utilities (env, format, request, store, tracking)
– `common/styles/`: Base CSS (theme, UnoCSS)
- public/: Static assets (manifest.json, fallback SW.js)
- Configuration files: `next.config.mjs`, `tsconfig.json`, `package.json`, etc.

##### README for Additional Insights
- Core features: token listing, market cap sorting/filtering, social links, one-click swaps via Bonkbot, Pepeboost, GMGN Sniper Bot.
- PWA support and theming (light/dark).
- No internal database; data is fetched from an external “pump.fun” source or via the internal `app/api/pump/route.ts` which may proxy or transform it.

##### Main Components and Their Interactions
a. Client (Browser)
– Loads Next.js pages, runs React components, registers Service Worker
– Renders UI modules, invokes hooks (`usePump`)
b. Next.js App Router
– Server-side rendering (SSR)/static generation of pages in `app/`
– Client-side transitions between routes
c. Internal API Layer
– `app/api/pump/route.ts`: Fetches/normalizes pump token data for the client
d. State Management
– `app/store.ts` + `common/utils/store.ts`: Holds global UI state, filter/sort settings
e. Service Worker & Offline
– `app/sw.ts` & `public/sw.js`: Caches assets & API responses, serves `~offline/page.tsx` when offline
f. Common Modules & UI Library
– Shared components, hooks, and utilities consumed by pages and modules
g. External Services
– pump.fun data source (token metadata, social links)
– Swap endpoints: Bonkbot, Pepeboost, GMGN Sniper Bot (one-click swap operations)

##### Architectural Patterns and Design Principles
– Component-based UI (modular, reusable React components)
– Separation of concerns (presentation in `app/modules`, data fetching in `app/api`, business logic in `common`)
– PWA best practices (Service Worker, offline fallback)
– Theme toggling via CSS variables and a theme context/provider

##### Final Touches
– Ensure every component is labeled with its folder/file path for traceability.
– Optionally, annotate with key technologies (Next.js, React, TypeScript, SCSS, UnoCSS, PWA).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Browser Client
    subgraph "Browser (Client)"
        B["Browser"]:::frontend
    end

    %% Service Worker & Offline
    subgraph "Service Worker & Offline"
        SWReg["Service Worker Registration (app/sw.ts)"]:::offline
        SWWorker["SW Script (public/sw.js)"]:::offline
        OfflinePage["Offline Page (app/~offline/page.tsx)"]:::offline
    end

    %% Next.js App Router
    subgraph "Next.js App Router"
        Page["Page (app/page.tsx)"]:::frontend
        Layout["Layout (app/layout.tsx)"]:::frontend
        subgraph "UI Modules (app/modules)"
            BtnReload["btn-reload.tsx"]:::frontend
            Header["header.tsx"]:::frontend
            Links["links.tsx"]:::frontend
            LoadingM["loading.tsx"]:::frontend
            ListIndex["list/index.tsx"]:::frontend
            ListItem["list/item.tsx"]:::frontend
            ListDetail["list/detail.tsx"]:::frontend
        end
    end

    %% Common UI Library
    subgraph "Common UI Library"
        CU_Loading["common/ui/loading.tsx"]:::frontend
        CU_Confirm["common/ui/popover/confirm.tsx"]:::frontend
        CU_Drawer["common/ui/popover/drawer.tsx"]:::frontend
        CU_Notify["common/ui/popover/notify.tsx"]:::frontend
        CU_ThemeIndex["common/ui/theme/index.tsx"]:::frontend
        CU_Typings["common/ui/theme/typings.ts"]:::frontend
        CU_ThemeToggle["common/ui/theme_toggle/index.tsx"]:::frontend
        CU_Style["common/ui/theme_toggle/style.css"]:::frontend
    end

    %% Common Hooks & API Helpers
    subgraph "Common API Helpers & Hooks"
        APIHelpers["common/api/index.ts"]:::frontend
        PumpHook["common/hooks/pump.ts"]:::frontend
    end

    %% State Management & Utilities
    subgraph "State Management & Utilities"
        StateMgmt["State Store (app/store.ts)"]:::state
        StoreUtilCU["Store Util (common/utils/store.ts)"]:::state
        EnvUtil["env.ts"]:::state
        FormatUtil["format.ts"]:::state
        RequestUtil["request.ts"]:::state
        ThemeUtil["theme.ts"]:::state
        TrackUtil["track.ts"]:::state
    end

    %% Internal API Layer
    subgraph "Internal API Layer"
        PumpRoute["/api/pump (app/api/pump/route.ts)"]:::api
    end

    %% External Services & Data
    DataSource["pump.fun Data Source"]:::external
    Bonk["Bonkbot"]:::external
    Pepe["Pepeboost"]:::external
    Sniper["GMGN Sniper Bot"]:::external

    %% Legend
    subgraph "Legend"
        direction LR
        F["UI Layer"]:::frontend
        A["API Layer"]:::api
        S["State/Utils"]:::state
        O["Offline/SW"]:::offline
        E["External"]:::external
    end

    %% Connections
    B -->|"load /"| Page
    B -->|"register()"| SWReg
    SWReg <--> SWWorker
    SWWorker -->|"serve cache"| Page
    SWWorker -->|"offline fallback"| OfflinePage

    Page -->|"renders"| Layout
    Layout -->|"includes"| BtnReload
    Layout -->|"includes"| Header
    Layout -->|"includes"| Links
    Layout -->|"includes"| LoadingM
    Layout -->|"includes"| ListIndex

    BtnReload --> PumpHook
    Header --> PumpHook
    Links --> PumpHook
    LoadingM --> APIHelpers
    ListIndex --> PumpHook
    ListItem --> PumpHook
    ListDetail --> PumpHook

    PumpHook --> APIHelpers
    APIHelpers --> RequestUtil

    Layout --> StateMgmt
    StateMgmt --> StoreUtilCU

    BtnReload -->|"GET /api/pump"| PumpRoute
    Header -->|"GET /api/pump"| PumpRoute
    ListIndex -->|"GET /api/pump"| PumpRoute
    ListItem -->|"GET /api/pump"| PumpRoute
    ListDetail -->|"GET /api/pump"| PumpRoute

    PumpRoute -->|"fetch tokens"| DataSource

    Layout -->|"POST swap"| Bonk
    Layout -->|"POST swap"| Pepe
    Layout -->|"POST swap"| Sniper

    %% Click Events
    click Page "https://github.com/evolify/pumpfun/blob/main/app/page.tsx"
    click Layout "https://github.com/evolify/pumpfun/blob/main/app/layout.tsx"
    click BtnReload "https://github.com/evolify/pumpfun/blob/main/app/modules/btn-reload.tsx"
    click Header "https://github.com/evolify/pumpfun/blob/main/app/modules/header.tsx"
    click Links "https://github.com/evolify/pumpfun/blob/main/app/modules/links.tsx"
    click LoadingM "https://github.com/evolify/pumpfun/blob/main/app/modules/loading.tsx"
    click ListIndex "https://github.com/evolify/pumpfun/blob/main/app/modules/list/index.tsx"
    click ListItem "https://github.com/evolify/pumpfun/blob/main/app/modules/list/item.tsx"
    click ListDetail "https://github.com/evolify/pumpfun/blob/main/app/modules/list/detail.tsx"
    click PumpRoute "https://github.com/evolify/pumpfun/blob/main/app/api/pump/route.ts"
    click StateMgmt "https://github.com/evolify/pumpfun/blob/main/app/store.ts"
    click StoreUtilCU "https://github.com/evolify/pumpfun/blob/main/common/utils/store.ts"
    click SWReg "https://github.com/evolify/pumpfun/blob/main/app/sw.ts"
    click SWWorker "https://github.com/evolify/pumpfun/blob/main/public/sw.js"
    click OfflinePage "https://github.com/evolify/pumpfun/blob/main/app/~offline/page.tsx"
    click APIHelpers "https://github.com/evolify/pumpfun/blob/main/common/api/index.ts"
    click PumpHook "https://github.com/evolify/pumpfun/blob/main/common/hooks/pump.ts"
    click CU_Loading "https://github.com/evolify/pumpfun/blob/main/common/ui/loading.tsx"
    click CU_Confirm "https://github.com/evolify/pumpfun/blob/main/common/ui/popover/confirm.tsx"
    click CU_Drawer "https://github.com/evolify/pumpfun/blob/main/common/ui/popover/drawer.tsx"
    click CU_Notify "https://github.com/evolify/pumpfun/blob/main/common/ui/popover/notify.tsx"
    click CU_ThemeIndex "https://github.com/evolify/pumpfun/blob/main/common/ui/theme/index.tsx"
    click CU_Typings "https://github.com/evolify/pumpfun/blob/main/common/ui/theme/typings.ts"
    click CU_ThemeToggle "https://github.com/evolify/pumpfun/blob/main/common/ui/theme_toggle/index.tsx"
    click CU_Style "https://github.com/evolify/pumpfun/blob/main/common/ui/theme_toggle/style.css"
    click EnvUtil "https://github.com/evolify/pumpfun/blob/main/common/utils/env.ts"
    click FormatUtil "https://github.com/evolify/pumpfun/blob/main/common/utils/format.ts"
    click RequestUtil "https://github.com/evolify/pumpfun/blob/main/common/utils/request.ts"
    click ThemeUtil "https://github.com/evolify/pumpfun/blob/main/common/utils/theme.ts"
    click TrackUtil "https://github.com/evolify/pumpfun/blob/main/common/utils/track.ts"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#3399ff,color:#000
    classDef api fill:#d4edda,stroke:#28a745,color:#000
    classDef state fill:#fff3cd,stroke:#ffca28,color:#000
    classDef offline fill:#e2e3e5,stroke:#6c757d,color:#000
    classDef external fill:#f3e5f5,stroke:#9c27b0,color:#000
```
