Skip to content

CLAUDE.md

Latest commit

 

History

History
120 lines (94 loc) · 6.43 KB

CLAUDE.md

File metadata and controls

120 lines (94 loc) · 6.43 KB

Sarafu Network Visualizer

A Next.js application that visualizes blockchain transaction data from the Sarafu Network using interactive 2D and 3D force-directed graphs.

AI Team Configuration (autogenerated by team-configurator, 2025-12-05)

Important: YOU MUST USE subagents when available for the task.

Detected Tech Stack

  • Frontend Framework: Next.js 13.4 (Pages Router) with React 18.2
  • UI Styling: Tailwind CSS 3.3 (JIT mode) with HeadlessUI and Framer Motion
  • Visualization:
    • 3D Force Graph 1.71
    • React Force Graph 2D/3D (1.25/1.23)
    • Three.js 0.153 with three-forcegraph
  • Database: PostgreSQL with Kysely 0.25 (type-safe SQL query builder)
    • Multiple databases: Graph DB and Federated DB
    • Type generation via kysely-codegen
  • Caching: Upstash Redis 1.35
  • Blockchain: viem 2.41, web3 4.0, multicoin-address-validator
  • Data Fetching: SWR 2.2
  • Language: TypeScript 5.4 (strict mode disabled)
  • Testing: Jest 29.5
  • Build Tools: ESBuild 0.18, PostCSS, Autoprefixer
  • Deployment: Vercel (@vercel/node 2.7)

Specialist Agents for This Project

Use these specialists based on the task at hand:

Task Agent Notes
Next.js SSR/SSG/API Routes @react-nextjs-expert Primary specialist for Next.js features, pages, API routes, data fetching patterns, and optimization. Always check latest Next.js docs before implementing.
UI Components & Tailwind Styling @tailwind-frontend-expert Utility-first styling, responsive design, container queries. Use for all component styling work.
Frontend Components (General) @frontend-developer Alternative for React components when Next.js-specific features not needed. Use for client-side logic and state management.
API Design & Contracts @api-architect Design REST endpoints, define request/response schemas, pagination strategies, error handling patterns.
Backend/Database Logic @backend-developer PostgreSQL queries with Kysely, database migrations, data processing, caching strategies with Redis.
Code Reviews & Quality @code-reviewer MUST USE before merging features or PRs. Provides security, maintainability, and performance reviews.
Performance Optimization @performance-optimizer MUST USE for graph rendering performance, data processing optimization, bundle size reduction, caching strategies.
Documentation @documentation-specialist Update README, API docs, architecture guides. Use after major features or when onboarding.
Codebase Analysis @code-archaeologist Deep exploration of unfamiliar code, legacy analysis, architecture documentation, risk assessment.

Project-Specific Guidance

Graph Visualization Work

  • Primary concerns: Performance with large datasets, rendering optimization, user interactivity
  • Key files:
    • /Users/chui/Dev/grassroots/vis/components/network-graph/ - Graph components
    • /Users/chui/Dev/grassroots/vis/utils/render_graph.ts - Graph data generation logic
  • Recommended agents: @performance-optimizer for rendering performance, @react-nextjs-expert for component architecture, @frontend-developer for Three.js/D3 integration

Database & Data Processing

  • Stack: PostgreSQL with Kysely ORM, multiple database connections (graphDB, federatedDB)
  • Key files:
    • /Users/chui/Dev/grassroots/vis/db/db.ts - Database connections
    • /Users/chui/Dev/grassroots/vis/db/graph-db.d.ts - Auto-generated types (regenerate with npm run generate:graph)
    • /Users/chui/Dev/grassroots/vis/db/federated-db.d.ts - Auto-generated types
  • Recommended agents: @backend-developer for query optimization and data layer work, @api-architect for API contract design

API Routes

  • Pattern: Next.js API routes in /Users/chui/Dev/grassroots/vis/pages/api/
  • Current routes:
    • /api/data - Main graph data endpoint with caching
  • Recommended agents: @react-nextjs-expert for Next.js-specific API features, @api-architect for endpoint design, @backend-developer for data processing

Styling & Components

  • Style system: Tailwind CSS with JIT mode, HeadlessUI for accessible components
  • Animation: Framer Motion for transitions
  • Key files: /Users/chui/Dev/grassroots/vis/tailwind.config.js
  • Recommended agents: @tailwind-frontend-expert for all styling work, @frontend-developer for component logic

Performance Considerations

  • Large dataset visualization (blockchain transactions)
  • Redis caching with 24-hour TTL
  • Graph data processing optimization (using Maps for O(1) lookups)
  • Dynamic imports for heavy visualization libraries
  • Recommended agent: @performance-optimizer for any performance work

Blockchain Integration

  • Multiple blockchain libraries (viem, web3.js)
  • Address validation with multicoin-address-validator
  • Token transfer tracking and voucher system
  • Recommended agents: @backend-developer for blockchain data processing, @code-reviewer for security review of blockchain interactions

Workflow Recommendations

  1. New Features: Start with @react-nextjs-expert or @api-architect depending on frontend vs backend
  2. Performance Issues: Always consult @performance-optimizer for graph rendering or data processing bottlenecks
  3. Before Merging: ALWAYS run @code-reviewer for security and quality checks
  4. Complex Queries: Use @backend-developer for Kysely query optimization
  5. UI/UX Work: Use @tailwind-frontend-expert for styling, @frontend-developer for component logic
  6. Documentation: After major changes, use @documentation-specialist to update docs

Example Commands

# Next.js feature development
"@react-nextjs-expert Build a new API route for filtering graph data by date range"

# Performance optimization
"@performance-optimizer Analyze and optimize the graph rendering performance in network-graph-3d.tsx"

# Styling work
"@tailwind-frontend-expert Create a responsive header component with dark mode support"

# Code review before PR
"@code-reviewer Review the changes in pages/api/data.ts and utils/cache.ts for security and performance"

# Database optimization
"@backend-developer Optimize the transaction query in pages/api/data.ts to reduce load time"

# Architecture analysis
"@code-archaeologist Analyze the graph data processing pipeline and document the architecture"

Last Updated: 2025-12-05
Configured By: team-configurator agent