Technology Stack

Relevant source files

The following files were used as context for generating this wiki page:

• package.json
• README.md
• AGENTS.md
• vite.config.ts
• src/stores/tutorialStore.ts
• src/tests/store.test.ts
• src/index.css

Dreamcats is a real-time multiplayer card game built with a modern web architecture. The project leverages a reactive frontend, a real-time serverless backend, and specialized libraries for animation and audio to create an immersive gameplay experience.

The architecture is centered around Convex for real-time state synchronization and React for the user interface. State management is handled through a combination of Convex backend functions and Zustand for local client-side state.

Sources: README.md:3-12, AGENTS.md:52-57

Core Frameworks and Languages

The project is built using TypeScript as the primary programming language for both frontend and backend logic, ensuring type safety across the network boundary.

Technology	Role	Version (approx.)
React	UI Library	19.2.3
TypeScript	Programming Language	5.9.3
Vite	Build Tool & Dev Server	7.2.6
Bun	Package Manager & Runtime	N/A (Project default)

Sources: package.json:44-93, AGENTS.md:4-9

Backend Architecture: Convex

Dreamcats utilizes Convex as its primary backend-as-a-service. It provides a real-time database, serverless functions, and automatic state synchronization.

• State Flow: Mutations and queries are used to update and retrieve game state. The backend respects per-player card visibility, ensuring that players only see the cards they are authorized to see.
• Code Generation: Convex automatically generates types under convex/_generated/ based on the backend schema.
• Deployment: The project is configured for deployment on Vercel, which executes npx convex deploy to sync backend functions before building the frontend.

Sources: README.md:41-47, AGENTS.md:12-14, 53-57

Data Sync Flow

The following diagram illustrates how state flows between the React client and the Convex backend.

Frontend State Management

Local state management is handled by Zustand. The application divides state into several logical "slices" to manage different concerns.

State Slices

• Session Slice: Manages playerId, playerName, roomId, and authToken.
• Game Slice: Contains the GameState, roomStatus, and gameVersion.
• UI Slice: Tracks interface states like isMenuOpen, safeArea insets, and reducedMotion preferences.
• Net Slice: Monitors netStatus and latencyMs.

Sources: src/tests/store.test.ts:14-41, src/stores/tutorialStore.ts:57-80

Selector Pattern

The project implements an auto-generated selector pattern to optimize re-renders.

// Usage in components
const step = useTutorialStore.use.step();

Sources: src/stores/tutorialStore.ts:44-55

Styling and UI Components

The project uses a utility-first CSS approach combined with headless UI primitives.

• Tailwind CSS v4: Used for styling with a custom theme that supports light and dark modes. It utilizes @theme blocks for defining variables like --color-primary (soft purple) and --color-accent (cherry blossom pink).
• Radix UI / Shadcn/ui: Provides accessible UI primitives such as Dialogs, Sheets, and Buttons.
• Responsive Scaling: A custom useScaleToFit hook and CSS scale-container logic ensure the game board fits perfectly within the viewport regardless of aspect ratio.

Sources: README.md:20-24, 73-77, src/index.css:57-124

Animation and Audio

To achieve a "dreamy" atmosphere, the project uses specialized libraries for sensory feedback.

• GSAP (GreenSock Animation Platform): The primary engine for complex card animations and state transitions, chosen for its performance over Framer Motion in complex layout scenarios.
• Howler.js: Manages game audio, providing sound effects for card moves and UI interactions.
• Framer Motion: Used for simpler UI transitions, such as modal appearances and tutorial steps.

Sources: README.md:25-26, 73-75, package.json:51, 80-82

Infrastructure and Tooling

Development Scripts

• bun run dev: Launches both Convex backend watcher and Vite frontend in parallel.
• bun run build: Executes tsc -b for type checking followed by vite build.
• optimize-images.ts: A custom Sharp-based script used to convert card assets to WebP and optimized PNG fallbacks.

Sources: package.json:7-17, scripts/optimize-images.ts:17-45

Summary

The Dreamcats technology stack is designed for high-performance, real-time interactivity. By offloading complex networking logic to Convex and leveraging GSAP for high-frequency animations, the architecture maintains a responsive 60fps experience while ensuring data consistency across multiple players.

Sources: README.md:15-30, AGENTS.md:52-60