# aksh1810/fission architecture

> Architecture diagram of the GitHub repository aksh1810/fission, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aksh1810/fission
- Repository: https://github.com/aksh1810/fission

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Legend (vertical)
%% =========================
subgraph "Legend"
direction TB
L1["Blue = Pages/UI (React)"]:::ui
L2(["Purple = Hooks/Controllers (side effects + orchestration)"]):::hooks
L3["Green = Pure Core Engine (deterministic)"]:::core
L4(["Orange = Platform APIs (Web Audio)"]):::platform
L5["Gray = External Libraries (Framer Motion, Tailwind, Next runtime)"]:::external
L6["Red dashed = Tests (Vitest)"]:::tests
end

%% =========================
%% Runtime Container: Browser
%% =========================
subgraph "Browser (Next.js + React + TypeScript)"
direction TB

User(["Player (click/tap)"]):::actor

subgraph "Next.js App Router (Pages)"
direction TB
AppRouter["App Router"]:::ui
Layout["layout.tsx + globals.css"]:::ui
Home["Home Page '/' (mode select)"]:::ui
Single["Singleplayer Page '/singleplayer'"]:::ui
Two["Twoplayer Page '/twoplayer'"]:::ui
end

subgraph "UI / View Components (React)"
direction TB
ComponentsIndex["components/index.ts (barrel)"]:::ui
Navigation["Navigation"]:::ui
GameBoard["GameBoard (grid renderer)"]:::ui
GameCell["GameCell (cell interactions)"]:::ui
CellDots["CellDots (atom/dot rendering)"]:::ui
ColorBar["ColorBar (HUD)"]:::ui
Modal["Modal (win/turn dialogs)"]:::ui
Burst["BurstEffect"]:::ui
Ring["ExplosionRing"]:::ui
end

subgraph "Controller / Orchestration (Hooks)"
direction TB
HooksIndex["hooks/index.ts (barrel)"]:::hooks
UseGame(["useGame (state machine + AI integration)"]):::hooks
UseAudio(["useAudio (synthesis + playback)"]):::hooks
end

subgraph "Core Game Engine (Pure / Testable)"
direction TB
CoreIndex["core/index.ts (barrel)"]:::core
Types["types.ts (GameState/Player/Move)"]:::core
Rules["rules.ts (validate + win detect)"]:::core
Grid["grid.ts (neighbors + bounds)"]:::core
Engine["engine.ts (immutable transitions)"]:::core
Chain["chainReaction.ts (iterative BFS)"]:::core
AI["ai.ts (minimax + alpha-beta)"]:::core
end

subgraph "Side-effect Subsystems"
direction TB
WebAudio(("Web Audio API")):::platform
Framer["Framer Motion"]:::external
Tailwind["Tailwind CSS"]:::external
end

end

%% =========================
%% Dev/Build/Deploy + Tests
%% =========================
subgraph "Dev / Tooling / Deploy"
direction TB
Vercel["Vercel (deployment target)"]:::external
NextCfg["next.config.ts"]:::external
EslintCfg["eslint.config.mjs"]:::external
PostCssCfg["postcss.config.mjs (Tailwind pipeline)"]:::external
Docs["Game Rules Doc"]:::external
end

subgraph "Tests (Vitest)"
direction TB
VitestCfg["vitest.config.ts"]:::tests
TestSetup["setup.ts"]:::tests
TChain["chainReaction.test.ts"]:::tests
TEngine["engine.test.ts"]:::tests
TGrid["grid.test.ts"]:::tests
TRules["rules.test.ts"]:::tests
end

%% =========================
%% Routing / Composition
%% =========================
AppRouter -->|"wraps"| Layout
Layout -->|"renders"| Home
Layout -->|"renders"| Single
Layout -->|"renders"| Two

Home -->|"navigates_to"| Single
Home -->|"navigates_to"| Two

Single -->|"composes"| Navigation
Two -->|"composes"| Navigation

Single -->|"composes"| GameBoard
Two -->|"composes"| GameBoard

GameBoard -->|"renders_grid"| GameCell
GameCell -->|"renders_atoms"| CellDots
GameBoard -->|"renders_HUD"| ColorBar
GameBoard -->|"renders_dialogs"| Modal
GameBoard -->|"renders_effects"| Burst
GameBoard -->|"renders_effects"| Ring

%% =========================
%% Primary gameplay loop (human input -> engine -> UI)
%% =========================
User -->|"click/tap"| GameCell
GameCell -->|"onMove(Move)"| UseGame

UseGame -->|"validate(Move,GameState)"| Rules
UseGame -->|"applyMove(Move,GameState)->GameState"| Engine
Engine -->|"reads/writes"| Types
Engine -->|"grid_ops"| Grid
Engine -->|"resolve_chain(BFS)"| Chain
Chain -->|"neighbor_lookup"| Grid
Engine -->|"win_check"| Rules

UseGame -->|"setState(GameState)"| GameBoard
GameBoard -->|"prop_drill(GameState)"| GameCell
GameBoard -->|"prop_drill(GameState)"| ColorBar
GameBoard -->|"show_win/turn"| Modal

%% Side effects (sound + animations)
UseGame -->|"play(click/explosion)"| UseAudio
UseAudio -->|"synthesize"| WebAudio

Burst -->|"animate"| Framer
Ring -->|"animate"| Framer
GameBoard -->|"styles"| Tailwind
GameCell -->|"styles"| Tailwind
Modal -->|"styles"| Tailwind
Navigation -->|"styles"| Tailwind
ColorBar -->|"styles"| Tailwind

%% =========================
%% Singleplayer loop (AI)
%% =========================
UseGame -->|"if_singleplayer_then_compute"| AI
AI -->|"simulate_moves"| Engine
AI -->|"query_legal_moves"| Rules
AI -->|"evaluate_positions"| Grid
AI -->|"choose_move(Move)"| UseGame
UseGame -->|"apply_ai_move"| Engine

%% =========================
%% Design callouts / constraints (as nodes to keep vertical)
%% =========================
subgraph "Key Design Principles (Project-specific)"
direction TB
P1["Clean layering: UI/Hooks -> Core (Core has zero React deps)"]:::note
P2["Immutable transitions: engine returns new GameState (reducer-like)"]:::note
P3["Chain reactions via iterative BFS (avoids deep recursion)"]:::note
P4["AI is pure consumer of engine (no UI coupling)"]:::note
P5["Pure functions enable unit tests focused on correctness"]:::note
end

UseGame -.->|"depends_on"| P1
Engine -.->|"guarantees"| P2
Chain -.->|"implements"| P3
AI -.->|"follows"| P4
TChain -.->|"verifies"| P5

%% =========================
%% Tests dependencies (dashed, dev-time)
%% =========================
VitestCfg -.->|"configures"| TChain
VitestCfg -.->|"configures"| TEngine
VitestCfg -.->|"configures"| TGrid
VitestCfg -.->|"configures"| TRules
TestSetup -.->|"initializes"| TChain
TestSetup -.->|"initializes"| TEngine
TestSetup -.->|"initializes"| TGrid
TestSetup -.->|"initializes"| TRules

TChain -.->|"tests"| Chain
TEngine -.->|"tests"| Engine
TGrid -.->|"tests"| Grid
TRules -.->|"tests"| Rules

%% =========================
%% Deploy/tooling relations
%% =========================
NextCfg -.->|"builds"| AppRouter
PostCssCfg -.->|"styles_pipeline"| Tailwind
EslintCfg -.->|"lint"| AppRouter
EslintCfg -.->|"lint"| ComponentsIndex
EslintCfg -.->|"lint"| HooksIndex
EslintCfg -.->|"lint"| CoreIndex
Vercel -.->|"hosts"| AppRouter
Docs -.->|"documents_rules"| Rules

%% =========================
%% Click events (from component_mapping)
%% =========================
click AppRouter "https://github.com/aksh1810/fission/tree/main/src/app"
click Layout "https://github.com/aksh1810/fission/blob/main/src/app/layout.tsx"
click Home "https://github.com/aksh1810/fission/blob/main/src/app/page.tsx"
click Single "https://github.com/aksh1810/fission/blob/main/src/app/singleplayer/page.tsx"
click Two "https://github.com/aksh1810/fission/blob/main/src/app/twoplayer/page.tsx"

click ComponentsIndex "https://github.com/aksh1810/fission/blob/main/src/components/index.ts"
click GameBoard "https://github.com/aksh1810/fission/blob/main/src/components/GameBoard.tsx"
click GameCell "https://github.com/aksh1810/fission/blob/main/src/components/GameCell.tsx"
click CellDots "https://github.com/aksh1810/fission/blob/main/src/components/CellDots.tsx"
click Burst "https://github.com/aksh1810/fission/blob/main/src/components/BurstEffect.tsx"
click Ring "https://github.com/aksh1810/fission/blob/main/src/components/ExplosionRing.tsx"
click ColorBar "https://github.com/aksh1810/fission/blob/main/src/components/ColorBar.tsx"
click Modal "https://github.com/aksh1810/fission/blob/main/src/components/Modal.tsx"
click Navigation "https://github.com/aksh1810/fission/blob/main/src/components/Navigation.tsx"

click HooksIndex "https://github.com/aksh1810/fission/blob/main/src/hooks/index.ts"
click UseGame "https://github.com/aksh1810/fission/blob/main/src/hooks/useGame.ts"
click UseAudio "https://github.com/aksh1810/fission/blob/main/src/hooks/useAudio.ts"
click WebAudio "https://github.com/aksh1810/fission/blob/main/src/hooks/useAudio.ts"

click CoreIndex "https://github.com/aksh1810/fission/blob/main/src/core/index.ts"
click Types "https://github.com/aksh1810/fission/blob/main/src/core/types.ts"
click Grid "https://github.com/aksh1810/fission/blob/main/src/core/grid.ts"
click Rules "https://github.com/aksh1810/fission/blob/main/src/core/rules.ts"
click Engine "https://github.com/aksh1810/fission/blob/main/src/core/engine.ts"
click Chain "https://github.com/aksh1810/fission/blob/main/src/core/chainReaction.ts"
click AI "https://github.com/aksh1810/fission/blob/main/src/core/ai.ts"

click VitestCfg "https://github.com/aksh1810/fission/blob/main/vitest.config.ts"
click TChain "https://github.com/aksh1810/fission/blob/main/src/__tests__/chainReaction.test.ts"
click TEngine "https://github.com/aksh1810/fission/blob/main/src/__tests__/engine.test.ts"
click TGrid "https://github.com/aksh1810/fission/blob/main/src/__tests__/grid.test.ts"
click TRules "https://github.com/aksh1810/fission/blob/main/src/__tests__/rules.test.ts"
click TestSetup "https://github.com/aksh1810/fission/blob/main/src/__tests__/setup.ts"
click Docs "https://github.com/aksh1810/fission/blob/main/docs/game-rules.md"
click NextCfg "https://github.com/aksh1810/fission/blob/main/next.config.ts"
click EslintCfg "https://github.com/aksh1810/fission/blob/main/eslint.config.mjs"
click PostCssCfg "https://github.com/aksh1810/fission/blob/main/postcss.config.mjs"
click Tailwind "https://github.com/aksh1810/fission/blob/main/postcss.config.mjs"

%% =========================
%% Styles
%% =========================
classDef actor fill:#111827,stroke:#0b1220,color:#ffffff,stroke-width:1px
classDef ui fill:#1d4ed8,stroke:#0b3aa6,color:#ffffff,stroke-width:1px
classDef hooks fill:#7c3aed,stroke:#4c1d95,color:#ffffff,stroke-width:1px
classDef core fill:#16a34a,stroke:#065f46,color:#ffffff,stroke-width:1px
classDef platform fill:#f59e0b,stroke:#92400e,color:#111827,stroke-width:1px
classDef external fill:#6b7280,stroke:#374151,color:#ffffff,stroke-width:1px
classDef tests fill:#ef4444,stroke:#7f1d1d,color:#ffffff,stroke-width:1px,stroke-dasharray: 6 4
classDef note fill:#fef3c7,stroke:#d97706,color:#111827,stroke-width:1px
```
