# conorwd/pump.fun-and-dexscreener-twitter-bot architecture

> Architecture diagram of the GitHub repository conorwd/pump.fun-and-dexscreener-twitter-bot, 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/conorwd/pump.fun-and-dexscreener-twitter-bot
- Repository: https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot

## Overview

##### Project Type and Purpose
- This is a full-stack, React/Next.js application with server-side API routes.
- Purpose: monitor Twitter for Pump.fun token links and automatically execute Solana trades based on configurable criteria, while providing a modern web UI for monitoring and control.

##### File Structure
- Top-level files: Next.js config (`next.config.js`, `tsconfig.json`), build scripts, `README.md`, `.env`.
- src/app: Next.js App Router directory, holding pages, layout, providers, metadata.
- src/app/api/pump-proxy: serverless API route for proxying Pump.fun trades.
- src/components: React UI components for settings, order status, feeds, etc.
- src/contexts: React Contexts for global state (wallet, trading, blacklist, buylist).
- src/services & clients: wrappers around external services (Helius RPC, Twitter WS, DexScreener, PumpFun).
- Constants, types, CSS, Tailwind config.

##### README for Insights
- Describes real-time Twitter monitoring via WebSocket backend.
- Automatic token purchases through Helius RPC.
- UI for configuration (follower filter, slippage, blacklist/buylist).
- Uses a WebSocket URL (`NEXT_PUBLIC_TWITTER_WS_URL`) to receive events.

##### Main Components in the System
a. Browser / Client
- Next.js React app
- React Contexts & UI Components
b. Next.js Server
- API Route: `/api/pump-proxy/route.ts` (trade proxy)
- Server-side rendering for initial page loads
c. External Services
- Twitter WebSocket feed (real-time tweets)
- Helius RPC endpoint (Solana transaction gateway)
- Pump.fun API (token purchase endpoints)
- DexScreener API (price data)

##### Relationships and Data Flow
1. User opens browser → Next.js serves React pages (SSR/CSR).
2. React Contexts fetch initial config & status (optional GET to API routes).
3. Client establishes WebSocket to `NEXT_PUBLIC_TWITTER_WS_URL`.
4. Incoming tweets containing Pump.fun links are streamed to client.
5. Client logic (via `twitterService`) filters by follower count, buylist/blacklist.
6. Upon match, client calls `/api/pump-proxy` → Next.js server route.
7. Server route (`pumpFunClient` + `heliusService`) constructs and signs purchase TX via Helius RPC.
8. Confirmation/status flows back to client, UI updates order status component.
9. DexScreener calls provide price charts/data in UI.

##### Architectural Patterns & Design Principles
- Component-based UI (React) with Context for global state.
- Lightweight API layer in Next.js for secure secret handling (RPC calls).
- Service abstraction: each external system has a client/service wrapper.
- Separation of concerns: UI, state management, API proxy, external integration.
- Real-time event handling via WebSocket.

##### Elements
- Labels for each major component and sub-component.
- Env-var boundary: separate what uses `NEXT_PUBLIC_` vs. server-only secrets.
- State stores (Contexts) that mediate between UI and services.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Client Zone
  subgraph "Client (Browser)"
    direction TB
    UI["React UI Components"]:::frontend
    Contexts["React Contexts"]:::frontend
    Clients["Service Clients"]:::frontend
  end

  %% Client Sub-components
  UI -->|"uses"| Components["Components"]:::frontend
  Components -->|"renders"| Blacklist["Blacklist Manager"]:::frontend
  Components -->|"renders"| Footer["Footer"]:::frontend
  Components -->|"renders"| Header["Header"]:::frontend
  Components -->|"renders"| OrderStatus["Order Status"]:::frontend
  Components -->|"renders"| Purchased["Purchased Tokens"]:::frontend
  Components -->|"renders"| Settings["Trading Settings"]:::frontend
  Components -->|"renders"| Feed["Twitter Feed"]:::frontend

  Contexts --> WalletCtx["Wallet Context"]:::frontend
  Contexts --> TradingCtx["Trading Context"]:::frontend
  Contexts --> BlacklistCtx["Blacklist Context"]:::frontend
  Contexts --> BuylistCtx["Buylist Context"]:::frontend

  Clients --> PumpFunClientC["Pump.fun Client"]:::frontend
  Clients --> DexClientC["DexScreener Client"]:::frontend
  Clients --> TwitterSvcC["Twitter WebSocket Service"]:::frontend

  %% Server Zone
  subgraph "Server (Next.js)"
    direction TB
    SSR["Next.js SSR"]:::server
    API["API Route: /api/pump-proxy"]:::server
    HeliusSvc["Helius RPC Service"]:::server
    PumpFunSvc["Pump.fun Service Wrapper"]:::server
  end

  SSR -->|"serves pages"| UI
  SSR -.->|"injects providers"| Contexts

  API -->|"calls"| HeliusSvc
  API -->|"calls"| PumpFunSvc

  %% External Zone
  subgraph "External Services"
    direction TB
    TwitterWS["Twitter WebSocket Feed"]:::external
    HeliusRPC["Helius RPC Endpoint"]:::external
    PumpFunAPI["Pump.fun API"]:::external
    DexAPI["DexScreener API"]:::external
  end

  %% Data Flows
  UI -->|"WS Connect"| TwitterWS
  TwitterWS -->|"tweets"| UI
  UI -->|"GET price data"| DexAPI
  UI -->|"POST trade request"| API
  API -->|"RPC sendTx"| HeliusRPC
  API -->|"REST buy"| PumpFunAPI
  HeliusSvc -->|"JSON RPC"| HeliusRPC
  PumpFunSvc -->|"REST"| PumpFunAPI
  DexClientC -->|"REST"| DexAPI
  TwitterSvcC -->|"WS"| TwitterWS

  API -->|"response status"| UI
  HeliusRPC -->|"tx confirmation"| HeliusSvc
  PumpFunAPI -->|"order confirmation"| PumpFunSvc

  %% Click Events for component mapping
  click API "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/src/app/api/pump-proxy/route.ts"
  click Blacklist "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/src/components/BlacklistManager.tsx"
  click Footer "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/src/components/Footer.tsx"
  click Header "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/src/components/Header.tsx"
  click OrderStatus "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/src/components/OrderStatus.tsx"
  click Purchased "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/src/components/PurchasedTokens.tsx"
  click Settings "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/src/components/TradingSettings.tsx"
  click Feed "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/src/components/TwitterFeed.tsx"
  click WalletCtx "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/src/contexts/WalletContext.tsx"
  click TradingCtx "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/src/contexts/TradingContext.tsx"
  click BlacklistCtx "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/src/contexts/BlacklistContext.tsx"
  click BuylistCtx "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/src/contexts/BuylistContext.tsx"
  click HeliusSvc "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/src/services/heliusService.ts"
  click TwitterSvcC "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/src/services/twitterService.ts"
  click PumpFunClientC "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/src/pumpFunClient.ts"
  click DexClientC "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/src/dexscreenerClient.ts"
  click RootLayout "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/src/app/layout.tsx"
  click Providers "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/src/app/providers.tsx"
  click Metadata "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/src/app/metadata.ts"
  click Page "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/src/app/page.tsx"
  click Template "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/src/app/template.tsx"
  click Constants "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/src/constants.ts"
  click Types "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/src/types.ts"
  click TypesIndex "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/src/types/index.ts"
  click GlobalsCSS "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/src/styles/globals.css"
  click Tailwind "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/tailwind.config.js"
  click NextConfig "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/next.config.js"
  click TSConfig "https://github.com/conorwd/pump.fun-and-dexscreener-twitter-bot/blob/main/tsconfig.json"

  %% Styles
  classDef frontend fill:#D0E4FD,stroke:#1E70BF,color:#0B3D91
  classDef server fill:#D6F5D6,stroke:#2E8B57,color:#165F00
  classDef external fill:#F0F0F0,stroke:#999999,color:#666666
```
