How aksh1810/fission works
What this project is (type + purpose)
Fission is a frontend-only web game (no backend/services) built with Next.js (App Router) + React + TypeScript. Its “system” is primarily an in-browser architecture split into:
• A pure game engine layer (src/core) that models rules, state transitions, chain reactions, and AI.
• A UI/presentation layer (src/components, src/app) that renders the board, animations, and routes (singleplayer vs twoplayer).
• A controller/orchestration layer (src/hooks) that binds UI events to engine transitions, runs AI turns, and triggers audio/animation effects.
• Testing via Vitest (src/__tests__) focusing on the core engine correctness.
How to read the file tree (what it implies architecturally)
Top-level signals:
• src/app/**: Next.js App Router pages: /, /singleplayer, /twoplayer.
• src/components/**: React components for board/cells/effects/navigation/modals.
• src/hooks/**: Custom hooks: useGame (state machine + AI integration) and useAudio (Web Audio API).
• src/core/**: The “domain layer”: types, grid, rules, engine (immutable transitions), chainReaction (iterative BFS), ai (minimax + alpha-beta).
• src/__tests__/**: Unit tests for core logic and chain reactions, confirming the “core is pure & testable” design.
Config/deploy signals:
• next.config.ts, next-env.d.ts, tsconfig.json, eslint.config.mjs, vitest.config.ts, tailwind/postcss configs.
• public/: static assets (though audio is synthesized, not loaded).
This strongly suggests a layered architecture with strict dependency direction:
UI → hooks/controller → core logic (and not the other way around).
The README explicitly describes:
• Chain reaction engine: iterative BFS explosion processing.
• Immutable state transitions: every move returns a new GameState.
• AI: minimax with alpha-beta pruning; difficulty = search depth; first move center-region heuristic.
• Animations: Framer Motion; visual effects components.
• Sound: synthesized via Web Audio API (no assets).
• Modes: singleplayer (vs AI) and twoplayer (local pass-and-play).
These are “architecturally significant” and should be explicitly called out as components and flows.
User input: GameCell onClick/tap
→ calls handler from useGame
useGame
→ calls rules.ts (validate move)
→ calls engine.ts (apply move immutably)
→ inside engine: uses grid.ts + chainReaction.ts (BFS explosions)
→ uses rules.ts (win detection)
useGame receives new GameState
→ updates React state
→ UI rerenders: GameBoard/GameCell/ColorBar reflect new state
Side effects triggered by state changes
• useGame → useAudio (play click/explosion)
• UI/effect components → Framer Motion animations
Singleplayer (vs AI) loop
Same as above for human move, then:
After human move completes and if game not over
useGame → ai.ts (minimax; depth determined by difficulty)
2. ai.ts queries potential moves by calling into core (engine/rules/grid) to simulate outcomes (still pure)
AI returns chosen move
useGame → engine.ts (+ chain reaction) → new state
Architectural patterns/design principles to highlight (project-specific)
• Clean layering / dependency direction: UI & hooks depend on core; core has zero React dependencies.
• Immutable state transitions: engine.ts returns a new GameState (reducer-like).
• Iterative BFS chain reaction: chainReaction.ts as a dedicated subsystem (prevents stack overflow).
• Deterministic, pure functions: makes unit tests straightforward (src/__tests__ validates core).
• AI as a pure consumer of the engine: minimax uses engine simulations (no special-case logic in UI).
What to label and how to visually encode it (don’t overthink; separate aggressively)
• Blue (Rectangles): UI / Pages (src/app, src/components)
• Purple (Rounded): Hooks/Controllers (src/hooks)
• Green (Hex/Rect): Pure Core (src/core)
• Orange (Cyl/Cloud): Platform APIs (Web Audio API)
• Gray: External Libraries (Framer Motion, Tailwind)
Include:
• Clear labels: include filename/module names where meaningful (engine.ts, chainReaction.ts, ai.ts, useGame.ts).
Minimum set of nodes (detailed but still readable):
Pages
• Home /
• /singleplayer
• /twoplayer
UI
• GameBoard → GameCell → CellDots
• Effects: BurstEffect, ExplosionRing
• HUD: ColorBar
• Modal
• Navigation
Hooks
• useGame (mode-aware: singleplayer/twoplayer)
• useAudio
Core
• types
• rules
• grid
• engine
• chainReaction (iterative BFS)
• ai (minimax + alpha-beta, depth param, opening heuristic)
External
• Framer Motion (drives effects)
• Web Audio API (sound synthesis)
• Tailwind CSS (styling)
• Vitest (tests)
• Vercel (deployment target)
Then wire these with the two main sequences:
• Human move → engine → chain reaction → update UI/effects/audio
• Human move → AI compute → engine → update UI/effects/audio