RugMunchMedia/rmi-frontend
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
rmi-frontend/AGENTS.md

9.1 KiB
Raw Permalink Blame History

AGENTS.md — RMI Frontend

Read this before working on the frontend codebase.

Every AI agent working on rugmunch.io reads this first.

Last updated: 2026-06-25

═══════════════════════════════════════════════════════════════════ WHAT THIS IS ═══════════════════════════════════════════════════════════════════

The RMI frontend at rugmunch.io — a Bloomberg-terminal-style crypto intelligence dashboard built with React 19 + Vite + TypeScript.

This is NOT Next.js. Static SPA, built with vite build, served via nginx + Cloudflare.

═══════════════════════════════════════════════════════════════════ WHERE THINGS LIVE ═══════════════════════════════════════════════════════════════════

Source: /root/frontend/rmi-frontend/ (netcup — build environment) Local copy: ~/rmi/rmi-frontend/ (cinnabox — edit environment) Build: npm run build → dist/ Deploy: cp -r dist/* /var/www/rmi/ (sudo on netcup) Dev server: npm run dev → localhost:5173

═══ CRITICAL — two separate copies ═══ Build goes to dist/ → Deploy DIFFERS from /var/www/rmi/ Running npm run build does NOT update the live site. You MUST run cp -r dist/* /var/www/rmi/ after every build. Forgetting this = site serves stale JS = broken UI = user yells.

═══════════════════════════════════════════════════════════════════ THE STACK ═══════════════════════════════════════════════════════════════════

React 19 + TypeScript 5.7 # Framework Vite 5 # Build tool Tailwind 4 # Styling TanStack Query 5 # Server state Zustand # Client state React Router v7 # Routing Recharts 3 + TV Lightweight 5 # Charts DataBus Client # Data layer (SWR + dedup)

═══════════════════════════════════════════════════════════════════ RULES (non-negotiable) ═══════════════════════════════════════════════════════════════════

  1. ALL DATA THROUGH DATABUS. Never raw fetch() in pages/components. Use useDataBus() hook or DataBusClient. ESLint enforces this.

  2. REACT QUERY STALETIME MUST ALIGN WITH BACKEND TTL. Price data: 30s. Metadata: 5min. Labels: 1hr. Alerts: 10s. Wrong staleTime = either stale data or excess polling.

  3. PRE-RENDER SHELLS. Every data component shows a skeleton screen while loading. Never show spinners or blank space.

  4. VERIFY BEFORE CLAIMING FIXED. Build → deploy → browser navigate → console check → data renders. Never say "it works" without proof. Use cache-busting (?v=N) to bypass Cloudflare cache.

  5. NO LUCIDE-REACT ICONS WITHOUT VERIFYING EXPORT. Whale, ShieldAlert, Siren are NOT in the ESM build. Crashes at runtime with ReferenceError. Test with node -e "require('lucide-react').X".

  6. CODE SPLITTING MANDATORY. All 42+ pages use React.lazy() + dynamic import(). Layout components (SidebarLayout, etc.) are static imports. Index chunk must stay under ~150KB.

  7. NO FLASHING/PULSING ANIMATIONS. Static indicators only. animate-pulse, animate-ping, animate-glow-pulse are banned. User explicitly rejected all strobing UI.

  8. SOCIAL-FI ON ALL CONTENT. Every post, news article, bulletin item gets SocialActionBar (reactions, comments, share).

  9. NO ADMIN ROUTES ON CONSUMER SITE. Admin.rugmunch.io is a separate codebase at /srv/admin-darkroom/. Admin pages in consumer App.tsx are bugs.

  10. DATABUS CHAIN NAMES MUST BE VERIFIED. Wrong name = silent empty page. Run curl localhost:8000/api/v1/databus/chains and check before adding new useDataBus('chain') calls.

═══════════════════════════════════════════════════════════════════ PAGES ═══════════════════════════════════════════════════════════════════

42+ pages, all lazy-loaded. Key ones:

/ (HomePage) /market-intel (15 tabs) /news /scanner /wallet/[address] /rugmaps /rugcharts /hunter (gamification) /premium /chat (AI streaming) /discover /feed /community /campaigns /walletsafe /api-docs /tool-market /investigator/[u]

Routes in App.tsx. Nav in SidebarLayout. to: paths MUST match route path= exactly. No orphans.

═══════════════════════════════════════════════════════════════════ DEPLOY ═══════════════════════════════════════════════════════════════════

Build + deploy (from netcup)

cd /root/frontend/rmi-frontend npm run build cp -r dist/* /var/www/rmi/

Clean stale chunks after deploy

NEW_INDEX=$(curl -s https://rugmunch.io/ | grep -o 'src="/assets/index-[^"]"' | sed 's|src="/assets/||;s|"||') cd /var/www/rmi/assets && ls index-.js | grep -v "$NEW_INDEX" | xargs rm -f

From cinnabox (sync → VPS builds)

bash ~/rmi/scripts/deploy.sh frontend

═ VERIFICATION SEQUENCE (MANDATORY) ═

  1. npm run build — succeeds with zero errors
  2. cp dist/* /var/www/rmi/
  3. browser_navigate with ?v=N
  4. browser_console — check for ReferenceError/TypeError
  5. Verify real data renders (not just Loading...)
  6. Never say "fixed" without steps 3-5

═══════════════════════════════════════════════════════════════════ PERSISTENT UI (never remove) ═══════════════════════════════════════════════════════════════════

PriceTickerBar — fixed top-0, h-[32px], 10 coins scrolling CommandPalette — Cmd+K overlay, fuzzy nav search SystemStatusBar — fixed bottom-0, h-[24px], health/latency/threats

Layout: pt-[32px] pb-[24px] clears the bars. Sidebar top-[32px].

═══════════════════════════════════════════════════════════════════ DATA BUS CHAIN REFERENCE (verified working) ═══════════════════════════════════════════════════════════════════

token_price, token_metadata, trending, alerts, scanner, news, news_intel, full_news, fear_greed, whale_alerts, token_trades, liquidity_risk, token_launches, market_overview, market_brief, wallet_labels, wallet_tokens, ct_rundown, defillama_chains, defillama_tvl, prediction_markets, cross_chain, holder_data, mcp_bridge, rag_search, arkham_portfolio, arkham_intel, arkham_transfers, social_metrics, cluster_map, token_search, bb_post, ai_task

BROKEN names (will silently fail): ❌ market_movers → use trending ❌ intelligence_feed → use news_intel ❌ risk_scan → use scanner ❌ wallet_profile → use arkham_portfolio ❌ sentiment → use fear_greed ❌ whale_data → use whale_alerts ❌ dex_data → use token_trades ❌ liquidity_depth → use liquidity_risk

═══════════════════════════════════════════════════════════════════ GO BUILD ═══════════════════════════════════════════════════════════════════

You know:

  • This is a React SPA on rugmunch.io
  • All data goes through DataBus
  • Verify before claiming fixed
  • No pulsing animations, no raw fetch, no dead code
  • Build → deploy → verify → commit