# martinjaskulla/dmm-memory architecture

> Architecture diagram of the GitHub repository martinjaskulla/dmm-memory, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/martinjaskulla/dmm-memory
- Repository: https://github.com/martinjaskulla/dmm-memory

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser / Static Server Layer
    subgraph "Browser / Static Server"
        SS["Static Server"]:::server
        INDEX["index.html"]:::server
        GOAL[("goal.json")]:::datasource
    end

    %% React UI Layer
    subgraph "React UI Layer"
        APP["App Container"]:::ui
        BOARD["Board"]:::ui
        CARD3D["Card3D"]:::ui
        BASECARD["BaseCard"]:::ui
        EFFECTCARD["EffectCard"]:::ui
        HIDDENCARD["HiddenCard"]:::ui
        MATCHEDCARD["MatchedCard"]:::ui
        REVEALEDCARD["RevealedCard"]:::ui
        HEADER["Header"]:::ui
        COUNTDOWN["Countdown"]:::ui
        STOPWATCH["StopWatch"]:::ui
        TIMETRAVEL["TimeTravel"]:::ui
    end

    %% State & Logic Layer
    subgraph "State & Logic Layer"
        USEGAME["useGame Hook"]:::logic
        USECLOCK["useClock Hook"]:::logic
        USEHISTORY["useHistory Hook"]:::logic
    end

    %% Effects Engine Layer
    subgraph "Effects Engine"
        EFFECTREG["effectRegistry"]:::effects
        APPLYEFFECTS["applyEffects"]:::effects
        SHUFFLEE["shuffleEffect"]:::effects
        RETRYE["retryEffect"]:::effects
        TIMERE["timerEffect"]:::effects
        TRICKE["trickEffect"]:::effects
        EXPLAINE["explainEffect"]:::effects
    end

    %% API Layer
    subgraph "Data / API Layer"
        FETCH["fetchGoal()"]:::api
    end

    %% Utilities Layer
    subgraph "Utilities"
        CACHED["cachedFetch"]:::utils
        SHUFFLE["shuffle"]:::utils
        PICK["pickRandom"]:::utils
        FORMAT["formatMs"]:::utils
        CHOICES["choices"]:::utils
        DEEPFREEZE["deepFreeze"]:::utils
        INTERVAL["interval"]:::utils
    end

    %% Connections - Data Flow
    INDEX -->|serves SPA| APP
    APP -->|calls fetchGoal| FETCH
    FETCH -->|GET data| GOAL
    FETCH -->|returns goal_items| USEGAME
    USEGAME -->|initializes| BOARD
    BOARD -->|renders| CARD3D
    BOARD -->|renders| BASECARD
    BOARD -->|renders| EFFECTCARD
    BOARD -->|renders| HIDDENCARD
    BOARD -->|renders| MATCHEDCARD
    BOARD -->|renders| REVEALEDCARD
    USEGAME -->|provides state| HEADER
    USEGAME -->|provides time| COUNTDOWN
    USEGAME -->|provides time| STOPWATCH
    USEHISTORY -->|provides history| TIMETRAVEL

    %% User Interaction
    BASECARD -->|onClick| USEGAME
    EFFECTCARD -->|onClick| USEGAME
    HIDDENCARD -->|onClick| USEGAME
    MATCHEDCARD -->|onClick| USEGAME
    REVEALEDCARD -->|onClick| USEGAME

    %% Effects Control Flow
    USEGAME -.->|effect trigger| EFFECTREG
    EFFECTREG -->|delegates| APPLYEFFECTS
    APPLYEFFECTS -.-> SHUFFLEE
    APPLYEFFECTS -.-> RETRYE
    APPLYEFFECTS -.-> TIMERE
    APPLYEFFECTS -.-> TRICKE
    APPLYEFFECTS -.-> EXPLAINE

    %% Clock and History
    USECLOCK -->|timer events| USEGAME
    USEGAME -->|records| USEHISTORY

    %% Utility usage
    USEGAME --> SHUFFLE
    USEGAME --> PICK
    USEGAME --> FORMAT
    FETCH --> CACHED
    USEHISTORY --> DEEPFREEZE
    USECLOCK --> INTERVAL
    USECLOCK --> FORMAT
    USEGAME --> CHOICES

    %% Click Events
    click APP "https://github.com/martinjaskulla/dmm-memory/blob/master/src/App.tsx"
    click INDEX "https://github.com/martinjaskulla/dmm-memory/blob/master/public/index.html"
    click GOAL "https://github.com/martinjaskulla/dmm-memory/blob/master/public/goal.json"
    click FETCH "https://github.com/martinjaskulla/dmm-memory/blob/master/src/api/fetchGoal.ts"
    click BOARD "https://github.com/martinjaskulla/dmm-memory/blob/master/src/components/Board.tsx"
    click CARD3D "https://github.com/martinjaskulla/dmm-memory/blob/master/src/components/Card3D.tsx"
    click BASECARD "https://github.com/martinjaskulla/dmm-memory/blob/master/src/components/Cards/BaseCard.tsx"
    click EFFECTCARD "https://github.com/martinjaskulla/dmm-memory/blob/master/src/components/Cards/EffectCard.tsx"
    click HIDDENCARD "https://github.com/martinjaskulla/dmm-memory/blob/master/src/components/Cards/HiddenCard.tsx"
    click MATCHEDCARD "https://github.com/martinjaskulla/dmm-memory/blob/master/src/components/Cards/MatchedCard.tsx"
    click REVEALEDCARD "https://github.com/martinjaskulla/dmm-memory/blob/master/src/components/Cards/RevealedCard.tsx"
    click HEADER "https://github.com/martinjaskulla/dmm-memory/blob/master/src/components/Header.tsx"
    click COUNTDOWN "https://github.com/martinjaskulla/dmm-memory/blob/master/src/components/Countdown.tsx"
    click STOPWATCH "https://github.com/martinjaskulla/dmm-memory/blob/master/src/components/StopWatch.tsx"
    click TIMETRAVEL "https://github.com/martinjaskulla/dmm-memory/blob/master/src/components/TimeTravel.tsx"
    click EFFECTREG "https://github.com/martinjaskulla/dmm-memory/blob/master/src/effects/effectRegistry.ts"
    click APPLYEFFECTS "https://github.com/martinjaskulla/dmm-memory/blob/master/src/effects/applyEffects.ts"
    click SHUFFLEE "https://github.com/martinjaskulla/dmm-memory/blob/master/src/effects/effects/shuffleEffect.ts"
    click RETRYE "https://github.com/martinjaskulla/dmm-memory/blob/master/src/effects/effects/retryEffect.ts"
    click TIMERE "https://github.com/martinjaskulla/dmm-memory/blob/master/src/effects/effects/timerEffect.ts"
    click TRICKE "https://github.com/martinjaskulla/dmm-memory/blob/master/src/effects/effects/trickEffect.ts"
    click EXPLAINE "https://github.com/martinjaskulla/dmm-memory/blob/master/src/effects/explainEffect.ts"
    click CACHED "https://github.com/martinjaskulla/dmm-memory/blob/master/src/utils/cachedFetch.ts"
    click SHUFFLE "https://github.com/martinjaskulla/dmm-memory/blob/master/src/utils/shuffle.ts"
    click PICK "https://github.com/martinjaskulla/dmm-memory/blob/master/src/utils/pickRandom.ts"
    click FORMAT "https://github.com/martinjaskulla/dmm-memory/blob/master/src/utils/formatMs.ts"
    click CHOICES "https://github.com/martinjaskulla/dmm-memory/blob/master/src/utils/choices.ts"
    click DEEPFREEZE "https://github.com/martinjaskulla/dmm-memory/blob/master/src/utils/deepFreeze.ts"
    click INTERVAL "https://github.com/martinjaskulla/dmm-memory/blob/master/src/utils/interval.ts"
    click USEGAME "https://github.com/martinjaskulla/dmm-memory/blob/master/src/hooks/useGame/useGame.tsx"
    click USECLOCK "https://github.com/martinjaskulla/dmm-memory/blob/master/src/hooks/useClock/useClock.tsx"
    click USEHISTORY "https://github.com/martinjaskulla/dmm-memory/blob/master/src/hooks/useHistory/useHistory.tsx"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#1E70BF,stroke-width:1px
    classDef logic fill:#DFFFD0,stroke:#6D9E00,stroke-width:1px
    classDef effects fill:#FFE4C4,stroke:#E07B39,stroke-width:1px
    classDef api fill:#E0E0E0,stroke:#888888,stroke-width:1px,stroke-dasharray: 4 2
    classDef datasource fill:#C0C0C0,stroke:#606060,stroke-width:1px,stroke-dasharray: 2 2
    classDef utils fill:#F2D0FF,stroke:#A347A3,stroke-width:1px
    classDef server fill:#FFFFFF,stroke:#000000,stroke-width:1px,stroke-dasharray: 2 2
```
