Skip to content

CLAUDE.md

Latest commit

 

History

History
113 lines (90 loc) · 4.09 KB

CLAUDE.md

File metadata and controls

113 lines (90 loc) · 4.09 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

SolScope is an on-chain intelligence platform for Solana that combines visual analytics (bubble maps, flow diagrams), AI explanations (Claude API), and interactive Q&A. Users paste a Solana address and get instant intelligence.

Architecture

Monorepo structure:

  • frontend/ — Next.js 15 (App Router) + TypeScript
  • backend/ — Hono.js + TypeScript API server

Frontend Stack

  • Framework: Next.js 15 with App Router, TypeScript, Tailwind CSS v4
  • Animated Components: React Bits (reactbits.dev) — install via npx shadcn@latest add @react-bits/[ComponentName]
  • UI Primitives: Radix UI (headless, for forms/dialogs/dropdowns)
  • Visualization: D3.js (bubble maps, force graphs, Sankey), Recharts (standard charts)
  • State: Zustand
  • Data Fetching: TanStack Query
  • Fonts: Inter (body), JetBrains Mono (numbers/data)
  • Icons: Lucide React

Backend Stack

  • Framework: Hono.js on Node.js, TypeScript
  • AI: Claude API (claude-sonnet-4-6) for analysis explanations
  • Data Source: Helius APIs (Solana-native)
    • getTransactionsForAddress — core tx history (100 credits/req, max 1000 sigs or 100 full tx)
    • DAS API — token/NFT metadata, holder info
    • Enhanced Transactions — parsed human-readable tx data
    • Wallet API — balances, transfers, funding sources
  • Cache: Redis (Upstash)
  • Database: PostgreSQL (Neon)
  • Deployment: Vercel (frontend) + Railway (backend)

Key Design Decisions

  • Dark mode only — Dune Analytics-inspired theme
    • Background: #0d0d0e (primary), #1a1a2e (cards), #16213e (hover)
    • Borders: #2a2a3e subtle card borders
    • Accent: #4a9eff (blue), #00d4aa (green/success), #f0b429 (warning), #ff6b35 (high risk), #ff4757 (critical), #a855f7 (AI/purple)
  • Flat, minimal cards — no glassmorphism, clean 1px borders
  • Dense data layout — compact, information-rich
  • Monospace for data — JetBrains Mono for all numbers/addresses
  • Max border-radius: 8px

Routes

/                    — Landing page (hero + demo)
/explore             — Instant Explorer (paste & analyze)
/explore/[address]   — Analysis result page
/dashboard           — Dashboard builder (Phase 2)
/chat                — AI chat standalone (Phase 2)

API Endpoints

POST /api/analyze              — Run analysis on address
GET  /api/analyze/:address     — Get cached analysis
POST /api/chat                 — AI chat with analysis context
POST /api/share                — Generate share URL
GET  /api/share/:id            — Get shared analysis
GET  /api/export/:id?format=   — Export as PNG/PDF

Build & Dev Commands

# Frontend
cd frontend && npm install
npm run dev          # Dev server (localhost:3000)
npm run build        # Production build
npm run lint         # ESLint

# Backend
cd backend && npm install
npm run dev          # Dev server (localhost:8787)
npm run build        # Production build

Environment Variables

# Frontend (.env.local)
NEXT_PUBLIC_API_URL=http://localhost:8787

# Backend (.env)
HELIUS_API_KEY=
ANTHROPIC_API_KEY=
REDIS_URL=
DATABASE_URL=

Helius API Notes

  • getTransactionsForAddress requires Developer plan (100 credits/req)
  • Pagination via paginationToken format: slot:position
  • Filter by blockTime, slot, status, tokenAccounts
  • Use transactionDetails: "signatures" for performance, "full" for complete data (limited to 100)
  • Cache responses aggressively — same address rarely changes within minutes

React Bits Usage

Components are copy-paste style, installed individually. Key components used:

  • Backgrounds: Aurora, Particles, DotGrid for page backgrounds
  • Text: CountUp, BlurText, ShinyText, DecryptedText for data display
  • Cards: SpotlightCard, PixelCard, TiltedCard for holder/token cards
  • Navigation: Dock, PillNav for nav elements
  • Animations: AnimatedContent, FadeContent, StarBorder for interactions
  • Lists: AnimatedList for chat messages