Skip to content

CLAUDE.md

Latest commit

 

History

History
63 lines (45 loc) · 3.15 KB

CLAUDE.md

File metadata and controls

63 lines (45 loc) · 3.15 KB

CLAUDE.md

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

Commands

make install   # Install npm dependencies
make dev       # Start Vite dev server with HMR
make build     # TypeScript check + production build to dist/
make lint      # ESLint
make test      # Vitest (run once)
make fmt       # Prettier format
npm run test:watch  # Vitest in watch mode

Run a single test file: npx vitest run src/hooks/useAnimationController.test.ts

Architecture

Interactive visualization tool for database internals. Each topic (indexing, encoding, replication, partitioning, transactions, consensus) has multiple visualizations rendered on HTML5 Canvas with step-through animation.

Visualization Pattern (Engine + Renderer)

Every visualization lives in src/visualizations/<topic>/<algorithm>/ with two files:

  • engine.ts - Pure logic. Defines Config, State, Frame types and exports a generateFrames(config) function that produces an array of frame snapshots. Each frame contains the full simulation state plus metadata (annotation text, highlights, operation type). No React or Canvas code here.

  • <Name>Visualization.tsx - React component. Wires the engine to the UI:

    1. Holds config state, passes it to generateFrames() via useMemo
    2. Uses useAnimationController() for playback (play/pause/step/speed/scrub)
    3. Uses useCanvas() for Canvas ref and DPR-aware setup
    4. Renders frames via a renderFrame(ctx, frame) function using canvas-utils helpers
    5. Wraps everything in <VisualizationContainer> which provides animation controls, config panel, and keyboard shortcuts

Adding a New Visualization

  1. Create src/visualizations/<topic>/<name>/engine.ts with types and generateFrames()
  2. Create src/visualizations/<topic>/<name>/<Name>Visualization.tsx following the pattern above
  3. Add a tab entry in the corresponding src/routes/<topic>.tsx file

Routing and Layout

  • TanStack Router with file-based routing (src/routes/). Route tree is auto-generated in src/routeTree.gen.ts (do not edit).
  • __root.tsx provides the shell: sidebar + content area
  • Each route uses <TopicPage> which renders tabs, one per visualization
  • Sidebar navigation is in AppSidebar.tsx

Shared Infrastructure

  • src/lib/canvas-utils.ts - Drawing primitives (nodes, rects, arrows, labels, animated messages) and shared COLORS palette
  • src/hooks/useAnimationController.ts - Frame-based playback controller (play/pause/step/speed/reset/goToFrame)
  • src/hooks/useCanvas.ts - Canvas ref with DPR-aware sizing
  • src/hooks/useKeyboardShortcuts.ts - Keyboard controls bound to the animation controller
  • src/components/VisualizationContainer.tsx - Standard wrapper composing animation controls + optional config panel
  • src/components/ConfigPanel.tsx - Renders slider/select config fields from a declarative schema

Tech Stack

  • TypeScript, React 19, Vite 7, Tailwind CSS v4, shadcn/ui (new-york style), TanStack Router
  • Path alias: @/ maps to src/
  • shadcn components in src/components/ui/, configured via components.json
  • Tests: Vitest with jsdom, setup in src/test/setup.ts