How martinjaskulla/dmm-memory works
Project Type and Purpose
• This is a front-end single-page application (SPA) built in React with TypeScript.
• Purpose: A memory matching game that retrieves word-pair data (Japanese ↔ English) from a local JSON API and includes special effect cards.
File-Structure Highlights
• public/
• goal.json – static data source for the game (“API” endpoint).
• index.html – SPA entry point.
• src/
• api/fetchGoal.ts – data-fetch layer.
• components/ – presentational UI components (Board, Cards, Header, Countdown, StopWatch, TimeTravel).
• config/ – game constants (messages, rules, gameOver conditions).
• effects/ – effect registry and implementations (shuffle, timer, retry, trick).
• hooks/ – custom hooks for state & logic: useGame (core game state), useHistory (move history/time travel), useClock (move timer).
• utils/ – helper functions (shuffle, pickRandom, formatMs, cachedFetch).
Key Architectural Patterns
• Component-based UI (React).
• Hooks for stateful logic and separation of concerns:
• useGame – game management (board state, flip logic, special-card triggers).
• useHistory – supports replay/rewind (persisted move history).
• useClock – enforces move time limit.
• Effects plugin pattern: effectRegistry dynamically loads effect implementations.
• Simple data-fetch abstraction over static JSON.
Main Components & Interactions
A. Browser / SPA Layer
• React App Container (App.tsx)
• Static Server (serving index.html, goal.json)
B. UI Components
• Board → renders grid of Card components (BaseCard, EffectCard, HiddenCard, etc.)
• Header / Countdown / StopWatch – display game stats & timer
C. State & Logic Layer
• useGame Hook → manages current board state, flip logic, win/lose checks
• useClock Hook → move timer, start/stop/reset
• useHistory Hook → records each move, supports time-travel UI
D. Effects Engine
• effectRegistry → registers effects (shuffle, timer, retry, trick)
• applyEffects → applies effect logic to game state
E. Data Layer
• fetchGoal → HTTP GET public/goal.json → returns goal_items array
F. Utilities
• shuffle, pickRandom → board shuffling
• cachedFetch → optional caching layer
Relationships & Data Flow
1. App mounts → calls fetchGoal → retrieves game data → passes to useGame.
2. useGame initializes board (mix word cards + effect cards).
3. User clicks a card → UI Card component emits onClick → useGame flipCard handler.
4. flipCard updates game state → if effect card → delegate to applyEffects → effectRegistry invokes appropriate effect.
5. State update triggers React re-render → Board & other components update.
6. useClock monitors elapsed time between flips → on expiry → communicates “game over” back to useGame.
7. useHistory captures each state change for time-travel.
Essential Details to Capture
• Life cycle: Fetch → Initialize → User interactions → State updates → Effects → Rendering.
• Move timer logic and reset on effect-card flips (interaction between useClock and useGame).
• Effect cards as first-class participants in the board (plugin registry).
• History stack enabling time-travel.