Skip to content

docs: comprehensive architecture & tech stack documentation#8

Merged
jackson-jpeg merged 6 commits intov2from
claude/update-claude-md-CZckS
Feb 21, 2026
Merged

docs: comprehensive architecture & tech stack documentation#8
jackson-jpeg merged 6 commits intov2from
claude/update-claude-md-CZckS

Conversation

@jackson-jpeg
Copy link
Copy Markdown
Owner

@jackson-jpeg jackson-jpeg commented Feb 21, 2026

Summary

Updated CLAUDE.md with comprehensive documentation of the project's architecture, tech stack, and codebase structure. This reflects the current state of the application including recent additions like Anthropic Claude integration, Capacitor mobile support, testing infrastructure, and detailed service layer organization.

Key Changes

  • Tech Stack Updates: Documented migration from OpenAI to Anthropic Claude (claude-sonnet-4-5-20250929), added Google Gemini for image generation, Tailwind CSS v4, Capacitor for mobile, and Jest testing framework
  • Server Architecture: Added detailed documentation of custom Node.js server (server.ts) running Express + Socket.IO alongside Next.js, including middleware and service layer organization
  • Service Layer: Documented 15+ services covering room management, script generation, voting, audience reactions, credits, payments, and more
  • Database Patterns: Explained write-through cache strategy for rooms with Firestore persistence and retry logic
  • Credit System: Documented two-bucket model (free weekly + banked credits) with transaction-based deductions
  • Project Structure: Expanded file tree to show all major directories, components, hooks, and services with brief descriptions
  • Testing: Added Jest testing commands and __tests__/unit/ directory structure
  • Environment Variables: Added .env.example reference with key variables documented
  • Architecture Patterns: Added sections on custom server, socket hooks, write-through cache, and credit system implementation details

Notable Details

  • Clarified that Socket.IO runs in a custom server alongside Next.js in a single process
  • Documented the adapter pattern for database abstraction (Firestore/JSON)
  • Explained socket hook state management using useRef to prevent stale closures
  • Added path alias documentation (@/* maps to project root)
  • Comprehensive list of 48+ shared UI components and 10+ custom hooks

https://claude.ai/code/session_01CpmiQmgWMZh5vDP9nswcQz

@claude
Update CLAUDE.md to match actual codebase
f521225 
- Fix AI provider: OpenAI -> Anthropic Claude + Google Gemini
- Add missing commands: test, test:watch, test:unit (remove nonexistent lint)
- Add environment variables section referencing .env.example
- Document all app routes (admin, purchase, privacy, terms, error pages)
- Add missing hooks (useAudioPlayer, useHaptics, useStandaloneMode)
- Add missing context (ThemeContext)
- Expand lib/ from 6 to 18 files with descriptions
- Expand server/ from vague categories to full file listing with descriptions
- Add architecture sections: custom server, write-through cache, credit system
- Note Capacitor mobile support, Apple App Store, Tailwind v4, path alias

https://claude.ai/code/session_01CpmiQmgWMZh5vDP9nswcQz
@claude
Fix critical production bugs: voting race, error type mismatch, DB fa…
5f2bfa3 
…llback, memory leaks

- Fix socket error type mismatch: withErrorHandler was emitting an object but
  ServerToClientEvents types it as string, causing '[object Object]' in toasts
- Fix voting double-execution race: set gameState='RESULTS' immediately in
  calculateResults() before async work to prevent concurrent calls
- Fix DB fallback bug: when Firestore fails, update useFirestore flag so
  getDatabase() returns the JSON adapter instead of the broken Firestore one
- Fix countdown race condition: update gameStateRef immediately in
  useJoinSocket to prevent duplicate countdown intervals on rapid reconnect
- Fix memory leaks: add cleanup for spectatorMessageCooldowns in periodic
  cleanup, add cleanupRoomTwists() called on room deletion/expiration
- Fix double haptic: remove redundant navigator.vibrate alongside successHaptic
- Use DISCONNECT_GRACE_PERIOD and MAX_PLAYERS constants instead of inline values
- Move @types/* and autoprefixer to devDependencies
- Fix ts-jest version: bump to ^30.0.0 to match jest ^30.2.0

https://claude.ai/code/session_01CpmiQmgWMZh5vDP9nswcQz
@claude
Extract HTTP routes and helpers from server.ts into modules
36ac60c 
- Create server/routes/ modules for Stripe, Auth, Apple, and API routes
- Create server/socket/helpers.ts with shared helpers (validateRoom,
  requireRoomMember, requireHost, isAdminSocket, findPlayerBySocketId,
  deductCreditOrReject)
- Replace 3x duplicated advanceLine closures with startTeleprompterSync calls
- Replace 2x duplicated credit-gate logic with deductCreditOrReject helper
- Remove ~750 lines of inline route code from server.ts (2655 -> 1906 lines)

https://claude.ai/code/session_01CpmiQmgWMZh5vDP9nswcQz
@claude
Add error handling and resilience: graceful shutdown, timeouts, rate …
44d93e6 
…limiting

- Add graceful shutdown handler (SIGTERM/SIGINT): persists room state to DB,
  notifies connected clients, and closes connections before exiting
- Add 2-minute timeout on Anthropic API streaming to prevent indefinite hangs
- Add 60-second voting timeout to auto-resolve results if a player disconnects
  mid-vote (prevents permanently stuck games)
- Add rate limiting (5 req/15min per IP) to Twilio SMS endpoints to prevent
  abuse and cost overruns
- Add VOTING_TIMEOUT constant to constants.ts

https://claude.ai/code/session_01CpmiQmgWMZh5vDP9nswcQz
@claude
Add tests for voting, audience, socket helpers, and DB adapter; fix J…
19658f1 
…est versions

- Add voting.service tests: vote counting, race condition guard, audience highlights
- Add audience.service tests: reactions, cooldowns, spectator messages, plot twists
- Add socket/helpers tests: validateRoom, requireHost, findPlayerBySocketId
- Add DB adapter test: fallback logic, exports
- Fix Jest/ts-jest version mismatch: downgrade to jest@29.7.0 + ts-jest@29.4.6
  (ts-jest 30.x does not exist yet)
- Fix jest.config.js: add transformIgnorePatterns for ESM uuid module
- Test count: 7 suites -> 11 suites, 89 tests -> 119 tests (30 new tests)

https://claude.ai/code/session_01CpmiQmgWMZh5vDP9nswcQz
@claude
Add reduced-motion support and consolidate animations in host/join pages
f308519 
- Create useReducedMotion hook with useMotionPrefs helper for consistent
  reduced-motion handling across components
- Add BUTTON animation presets to centralized animations module
- Replace inline animation props in host/page.tsx and join/page.tsx with
  centralized variants (fade, scaleIn) from lib/animations.ts
- Make countdown animation respect prefers-reduced-motion preference
- Spinning connection indicator uses reduced motion when appropriate

https://claude.ai/code/session_01CpmiQmgWMZh5vDP9nswcQz
@vercel
Copy link
Copy Markdown

vercel bot commented Feb 21, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
plot-twists Ready Ready Preview, Comment Feb 21, 2026 8:23am

@jackson-jpeg jackson-jpeg merged commit 9efcc83 into v2 Feb 21, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@jackson-jpeg @claude