Skip to content

sarpoy-ui

The frontend is a Nuxt 3 single-page application (SPA) that gives creators and solvers a polished interface backed by wallet auth and realtime chat. This guide explains the UX goals, tech stack, routing plan, and integration details so the implementation stays aligned with the backend contract.

Stack

  • Nuxt 3 (SPA mode) with Vite bundler.
  • Vue 3 Composition API for components and composables.
  • Tailwind CSS with DaisyUI / Radix primitives for consistent theming.
  • Pinia for lightweight global state (session, wallet metadata, feature flags).
  • TanStack Query (Vue Query) for data fetching, caching, and optimistic updates.
  • Solana wallet adapters (@solana/wallet-adapter-vue, Phantom, Backpack, Solflare).
  • Markdown-it or similar to render bot descriptions safely.

UX Pillars

  1. Frictionless wallet onboarding: Show network status, balances, and error states inline.
  2. Chat-first experience: Keep chat composer always visible with message cost indicator + countdown to cost bump.
  3. Creator transparency: Show pot, fee breakdown, ledger of incoming/outgoing SOL.
  4. Trust cues: Surface transaction signatures, confirmation status, and security hints.

Routes & Views

Route Purpose Key Components
/ Landing page, hero, featured bots HeroSection, FeaturedBots, HowItWorks
/bots Directory with filters/search BotFilters, BotCard, InfiniteGrid
/bots/:id Bot detail + chat BotHeader, PotWidget, ChatWindow, ClueHistory
/creator Creator studio (list + launch) CreatorBotsTable, BotWizard
/leaderboard Creator & solver rankings LeaderboardTabs, EntryRow
/profile User activity, linked wallets ProfileStats, TxHistory, SettingsForm

Use Nuxt layouts for default (public) and dashboard (creator-only).

Data Access Pattern

  • Wrap all HTTP calls in composables under ~/composables/api/* to centralize base URLs, auth headers, and error handling.
  • Use Vue Query for caching; keys follow ['bots', params], ['chat', sessionId], etc.
  • WebSocket composable (useChatStream) listens to /ws/chats/{session} for new messages and settlement updates.
  • Wallet state lives in Pinia store (useSessionStore) with actions to request nonce, sign, and fetch session profile.

Styling & Design Tokens

  • Tailwind config defines semantic colors (brand, accent, danger), typography scale, and spacing tokens.
  • Dark mode is on by default with accessible contrast ratios.
  • Components rely on Radix UI primitives / Headless UI to accelerate modals, dropdowns, and toggles.

Integration with Solana

  • Provide a WalletGuard component that blocks gated routes when wallet disconnected or wrong cluster.
  • Display transaction signatures with links to Solscan/Helius Explorer.
  • Support priority fees toggle for power users.
  • Cache frequently used program IDs + PDAs from docs/sarpoy-api.md to avoid repeated RPC calls.

Testing & Tooling

  • Unit tests: Vitest + Vue Testing Library for components and composables.
  • E2E tests: Playwright hitting a mock API or local FastAPI instance.
  • Accessibility: Run @axe-core/playwright in CI; ensure keyboard navigation across chat.
  • Storybook: Optional but recommended for iterating on chat UI and wallet flows.

Implementation Sequence

  1. Scaffold Nuxt project (npx nuxi@latest init sarpoy-ui) and configure Tailwind + ESLint + Prettier.
  2. Implement wallet bar, session store, and API client composable.
  3. Build Bot Directory + detail flow using mock data.
  4. Integrate live API endpoints once sarpoy-api MVP is available.
  5. Polish dashboards, leaderboards, and animations; add analytics + error tracking (Sentry/PostHog).