Overview

The Game of Life project is structured as a layered monorepo: a deterministic simulation core and a separate React application shell for rendering and interaction. This separation keeps rule logic testable, keeps UI iteration fast, and allows performance tuning of simulation and rendering paths independently.

Planning

Problem Space

I wanted a project that did more than render a toy grid. The intent was to build an implementation that demonstrates practical engineering decisions around correctness, performance, and maintainability in a simulation-driven UI.

Architecture Goals

1. Preserve deterministic, testable simulation behavior independent of UI code.
2. Use sparse-state data structures so work scales with active cells instead of full-grid size.
3. Provide interactive controls and shareable state without coupling product UX to rule execution.
4. Keep package boundaries explicit so simulation and presentation layers can evolve independently.

Key Decisions

Key decisions that shaped the project:

• Monorepo split (core + app): made game logic independently testable and reusable.
• Sparse grid model: optimized for typical Game of Life patterns where most cells are dead.
• Canvas-oriented rendering path: chosen to better support larger boards than naive DOM-cell rendering.
• URL-encoded state sharing: improved collaboration and reproducibility of interesting board states.
• CI + GitHub Pages deploys: ensured the project is always runnable from a public URL.

Challenges

The most persistent challenge has been UI performance as grid size and update cadence increase. I addressed this by keeping simulation logic decoupled from rendering, using a sparse state model in the core, and iterating on the rendering path separately from rule execution.

Another challenge was balancing feature depth with maintainability. Splitting into core and app packages, plus backing rules/pattern behavior with tests, helped reduce regressions while still allowing rapid UI iteration.

Architectural Overview

The implementation separates simulation concerns from presentation concerns so performance work and UX work can evolve independently.

flowchart LR
    U[User input] --> A[React app shell]
    A --> G[Game wrapper]
    G --> C[Core simulation engine]
    C --> A
  

Core Simulation Engine

The core engine executes Conway rules as pure transformations: given a current sparse state map, it computes the next generation plus derived stats. Keeping this logic side-effect free makes behavior deterministic and straightforward to unit test.

This engine operates directly on the LifeGrid structure described in State and Data Model, so the data model and simulation step logic are intentionally paired.

Relevant core simulation code:

• calculateNextGeneration + default rules
• countLiveNeighborCoordinates and coordinate helpers
• LifeGrid and simulation interfaces
• Coordinate parser utilities

State and Data Model

The foundational board data structure is LifeGrid, which lives in the @game-of-life/core package at packages/core/src/interfaces/index.ts. LifeGrid is a coordinate-keyed hash map where each key is an "x,y" coordinate string and each value is a boolean cell state.

Board state is represented sparsely with this coordinate map instead of a dense full-grid matrix. This keeps both memory use and per-tick computation proportional to active regions, which is critical for larger boards where most cells are dead.

In practice, each simulation tick in the core engine accepts a LifeGrid, applies neighbor/rule evaluation, and returns the next LifeGrid, making this model the contract between data representation and rule execution.

// @game-of-life/core/packages/core/src/interfaces/index.ts
export interface LifeGrid {
  [coordinate: string]: boolean;
}

// Example sparse state using LifeGrid.
const gliderSeed: LifeGrid = {
  '1,0': true,
  '2,1': true,
  '0,2': true,
  '1,2': true,
  '2,2': true,
};

Rendering and Interaction Layer

The app package owns playback controls, user interactions, and canvas drawing. A thin Game wrapper adapts core outputs for the UI, so rendering concerns (frame pacing, viewport, theming, controls) can evolve without changing rule execution.

// @game-of-life/core/packages/core/src/class/Game.ts
class Game {
  constructor(grid: LifeGrid, rules: GameRules = DEFAULT_RULES) {
    this.grid = grid;
    this.rules = rules;
    this.generations = 0;
  }

  next() {
    const previousGrid = this.grid;
    this.grid = calculateNextGeneration(this.grid, this.rules);
    const stats = calculateStats(previousGrid, this.grid);
    this.generations += 1;
    return { grid: this.grid, stats };
  }

  getStatus() {
    return this.grid;
  }
}

Validation and Delivery Pipeline

The repository uses package-level testing for simulation correctness and CI-backed deployments for repeatable release quality. This supports fast iteration while preserving confidence that rule logic and core behavior remain stable over time.

flowchart TD
    PR[Pull request to master/main] --> TESTS[Run Unit Tests]
    PR --> PREVIEW[Deploy Pages preview]
    PREVIEW --> COMMENT[Post preview URL to PR]

    MERGE[Push/merge to master/main] --> TESTS_MAIN[Run Unit Tests]
    MERGE --> PAGES[Deploy to GitHub Pages]
    MERGE --> CODEQL[CodeQL analysis]

    CLOSE[PR closed] --> CLEANUP[Cleanup PR preview]
  

Current workflow files:

• run-tests.yml
• deploy-pages.yml
• cleanup-pr-preview.yml
• codeql-analysis.yml
• canonical-path-guard.yml

Test Pyramid and Coverage

The test pyramid is intentionally weighted toward the core simulation layer. Unit tests cover rule evaluation, coordinate handling, and sparse state transitions at the base of the pyramid, while a smaller set of integration tests exercises the Game wrapper and key UI flows.

Coverage is strongest where behavior is deterministic and easiest to verify: the core package, pattern seed behavior, and transition logic. The UI layer keeps a lighter coverage profile focused on smoke tests, user controls, and regression checks around rendering and state syncing, which keeps the suite fast without losing confidence in the app shell.

Runtime Generation Loop

The core simulation uses a sparse dictionary/grid representation keyed by coordinates, keeping work proportional to active areas instead of a fixed full-board matrix. Rule execution and neighbor checks stay in the core package, while the UI consumes results through a Game wrapper and renders the snapshot to canvas.

sequenceDiagram
    box rgba(45, 79, 128, 0.95) Presentation Layer
    participant User
    participant App as React App
    end

    box rgba(47, 124, 83, 0.95) Simulation Engine
    participant Game as Game Wrapper
    participant Core as Core Engine
    end

    box rgba(125, 74, 168, 0.95) Render Output
    participant Render as Canvas Renderer
    end

    User->>App: Start simulation
    loop each generation tick
      App->>Game: step()
      Game->>Core: calculateNextGeneration(state)
      Core-->>Game: next state + stats
      Game-->>App: updated snapshot
      App->>Render: draw(snapshot)
      Render-->>User: updated board and metrics
    end
  

Packages

The project is organized as an Nx monorepo with clear package boundaries and explicit TypeScript project references.

@game-of-life/core

@game-of-life/core is the simulation engine package. It owns deterministic rule evaluation, sparse grid transitions, coordinate utilities, and reusable pattern seed data, and remains framework-agnostic so it can be tested in isolation.

@game-of-life/app

@game-of-life/app is the product-facing UI package. It owns the React + Vite interface, playback controls, canvas rendering, and URL-based state sharing, and consumes the core package through a thin Game adapter layer.

flowchart LR
    UI["@game-of-life/app\nReact + Vite UI"] --> GAME["Game class\nadapter layer"]
    GAME --> CORE["@game-of-life/core\nPure simulation logic"]
    CORE --> RULES["Rule engine\nneighbor checks + transitions"]
    CORE --> PATTERNS["Pattern library\nseed presets"]
    UI --> CANVAS["Canvas renderer\nviewport + draw loop"]
    UI --> CONTROLS["Controls + URL state\nplayback, speed, sharing"]
    classDef app fill:#2d4f80,stroke:#88a9d8,stroke-width:1.5px,color:#ffffff;
    classDef core fill:#2f7c53,stroke:#9fd7b8,stroke-width:1.5px,color:#ffffff;
    classDef supporting fill:#a86f12,stroke:#f3c97a,stroke-width:1.5px,color:#ffffff;
    classDef output fill:#7d4aa8,stroke:#d9b3f7,stroke-width:1.5px,color:#ffffff;
    class UI app;
    class GAME supporting;
    class CORE core;
    class RULES supporting;
    class PATTERNS supporting;
    class CANVAS output;
    class CONTROLS output;
    click UI "https://github.com/wintermuted/game-of-life/tree/master/packages/app" "Open app package" _blank
    click CORE "https://github.com/wintermuted/game-of-life/tree/master/packages/core" "Open core package" _blank
    click PATTERNS "https://github.com/wintermuted/game-of-life/tree/master/packages/core/src/data" "Open pattern data" _blank
    click CONTROLS "https://wintermuted.github.io/game-of-life/" "Open live demo" _blank
  

Outcomes

The project now functions as both an interactive demo and a maintainable engineering sample:

• Rules and canonical patterns are validated by automated tests.
• The simulation is publicly deployed on GitHub Pages for easy sharing.
• Pull request preview deployments support faster iteration and review.
• The architecture provides a clear path for future optimization work without rewriting core logic.