# the-x-35/solana-chatgpt-kit architecture

> Architecture diagram of the GitHub repository the-x-35/solana-chatgpt-kit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/the-x-35/solana-chatgpt-kit
- Repository: https://github.com/the-x-35/solana-chatgpt-kit

## Overview

##### Project type and purpose
- This is a full-stack Next.js 15 application that embeds itself as a native ChatGPT App via the OpenAI Apps SDK (MCP).
- Its primary function is to expose Solana blockchain operations (swap, transfer, balance check, stake, price lookup) directly inside ChatGPT with natural-language commands and interactive widgets using Jupiter and other Solana services.

##### File structure
Top-level folders and files:
- app/ – Next.js App Router:
– app/mcp/route.ts: MCP server endpoint that registers “tools” (API endpoints) and “resources” (UI widget HTML) with ChatGPT.
– app/api/...: Serverless functions implementing blockchain operations (swap/quote, swap/execute, transfer, stake, wallet/balance, price).
– app/swap/, app/transfer/, app/stake/, etc.: React pages for each widget.
– app/hooks/: Custom React hooks for state, display mode, OpenAI integration, sending messages.
– layout.tsx, globals.css: Global layout and styling.
– custom-page/page.tsx: Any static or override page.
- components/: Shared UI primitives (Radix UI wrappers: Button, Card, Input, Label, Badge).
- lib/: Core utilities and configuration: address resolution, Solana config, token resolver, utils, wallet-utils, x402 payment config.
- middleware.ts: Next.js middleware for routing or request handling.
- next.config.ts, tsconfig.json, postcss.config.mjs: Build and runtime configuration.

##### Key insights from the README
- Architecture section calls out five main pieces:
1. MCP Server (app/mcp)
2. API Routes (app/api)
3. Wallet modes (server-key vs. browser extension + x402 payment protocol)
4. UI Widgets (app/swap, app/transfer, etc.)
5. Address Resolution (lib/address-resolver.ts)
- Tech stack: Next.js, React, TypeScript, Tailwind, Solana Web3.js, Jupiter API, OpenAI Apps SDK, Zod for validation.
- External services: Jupiter aggregator, Bonfida SNS, AllDomains, PayAI/x402 facilitator, Solana JSON RPC.

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "ChatGPT App Layer"
    CG["ChatGPT Client"]:::chatgpt
    MCP["MCP Server /mcp"]:::chatgpt
  end

  subgraph "Next.js Server Layer"
    subgraph "API Routes"
      Q["/api/swap/quote"]:::api
      E["/api/swap/execute"]:::api
      T["/api/transfer"]:::api
      S["/api/stake"]:::api
      WB["/api/wallet/balance"]:::api
      P["/api/price"]:::api
    end
    MW["Middleware"]:::config
    CFG["Config Files"]:::config
  end

  subgraph "UI Widget Layer"
    SW["Swap Widget"]:::frontend
    TR["Transfer Widget"]:::frontend
    ST["Stake Widget"]:::frontend
    CP["Custom Page"]:::frontend
    Hooks["Hooks"]:::util
  end

  subgraph "Library Layer"
    AR["address-resolver.ts"]:::util
    SC["solana-config.ts"]:::util
    TRU["token-resolver.ts"]:::util
    U["utils.ts"]:::util
    WU["wallet-utils.ts"]:::util
    X4["x402-config.ts"]:::util
  end

  subgraph "External Services"
    SOL["Solana RPC"]:::external
    JUP["Jupiter API"]:::external
    DNS["Bonfida SNS / AllDomains"]:::external
    PAY["x402 Payment Facilitator"]:::external
    EXTW["External Wallets"]:::external
    PUBLIC["Static Assets"]:::external
  end

  CG -->|"register tools/resources"| MCP
  CG -->|"natural-language command"| SW
  CG -->|"natural-language command"| TR
  CG -->|"natural-language command"| ST

  SW -->|"GET quote"| Q
  SW -->|"POST execute"| E
  SW -->|"GET price"| P
  SW -->|"GET balance"| WB
  TR -->|"POST transfer"| T
  ST -->|"POST stake"| S

  Hooks --> SW
  Hooks --> TR
  Hooks --> ST

  Q --> AR
  E --> AR
  T --> AR
  S --> AR
  WB --> AR
  P --> AR

  Q --> SC
  E --> SC
  T --> SC
  S --> SC
  WB --> SC
  P --> SC

  E --> WU
  T --> WU
  S --> WU

  E --> X4
  T --> X4
  S --> X4

  Q -->|"quote"| JUP
  E -->|"execute swap"| JUP
  T -->|"sendTransaction"| SOL
  S -->|"sendTransaction"| SOL
  WB -->|"getBalance"| SOL
  P -->|"getPrice"| SOL

  AR --> DNS
  WU --> PAY

  SW --> EXTW
  TR --> EXTW
  ST --> EXTW

  MCP --> Q
  MCP --> E
  MCP --> T
  MCP --> S
  MCP --> WB
  MCP --> P

  click MCP "https://github.com/the-x-35/solana-chatgpt-kit/blob/main/app/mcp/route.ts"
  click Q "https://github.com/the-x-35/solana-chatgpt-kit/blob/main/app/api/swap/quote/route.ts"
  click E "https://github.com/the-x-35/solana-chatgpt-kit/blob/main/app/api/swap/execute/route.ts"
  click T "https://github.com/the-x-35/solana-chatgpt-kit/blob/main/app/api/transfer/route.ts"
  click S "https://github.com/the-x-35/solana-chatgpt-kit/blob/main/app/api/stake/route.ts"
  click WB "https://github.com/the-x-35/solana-chatgpt-kit/blob/main/app/api/wallet/balance/route.ts"
  click P "https://github.com/the-x-35/solana-chatgpt-kit/blob/main/app/api/price/route.ts"
  click SW "https://github.com/the-x-35/solana-chatgpt-kit/blob/main/app/swap/page.tsx"
  click TR "https://github.com/the-x-35/solana-chatgpt-kit/blob/main/app/transfer/page.tsx"
  click ST "https://github.com/the-x-35/solana-chatgpt-kit/blob/main/app/stake/page.tsx"
  click CP "https://github.com/the-x-35/solana-chatgpt-kit/blob/main/app/custom-page/page.tsx"
  click Hooks "https://github.com/the-x-35/solana-chatgpt-kit/blob/main/app/hooks/index.ts"
  click AR "https://github.com/the-x-35/solana-chatgpt-kit/blob/main/lib/address-resolver.ts"
  click SC "https://github.com/the-x-35/solana-chatgpt-kit/blob/main/lib/solana-config.ts"
  click TRU "https://github.com/the-x-35/solana-chatgpt-kit/blob/main/lib/token-resolver.ts"
  click U "https://github.com/the-x-35/solana-chatgpt-kit/blob/main/lib/utils.ts"
  click WU "https://github.com/the-x-35/solana-chatgpt-kit/blob/main/lib/wallet-utils.ts"
  click X4 "https://github.com/the-x-35/solana-chatgpt-kit/blob/main/lib/x402-config.ts"
  click MW "https://github.com/the-x-35/solana-chatgpt-kit/blob/main/middleware.ts"
  click CFG "https://github.com/the-x-35/solana-chatgpt-kit/blob/main/next.config.ts"
  click CFG "https://github.com/the-x-35/solana-chatgpt-kit/blob/main/tsconfig.json"
  click CFG "https://github.com/the-x-35/solana-chatgpt-kit/blob/main/postcss.config.mjs"
  click PUBLIC "https://github.com/the-x-35/solana-chatgpt-kit/tree/main/public/"

  classDef chatgpt fill:#D9D2E9,stroke:#7D5BA6
  classDef frontend fill:#DBEAFE,stroke:#3B82F6
  classDef api fill:#D1FAE5,stroke:#10B981
  classDef util fill:#FEF3C7,stroke:#F59E0B
  classDef external fill:#FEE2E2,stroke:#EF4444
  classDef config fill:#E5E7EB,stroke:#6B7280
```
