Architecture

io.github.carmelolg.jcal
├── core/
│   ├── CellularAutomata                   ← the grid (CellGrid); holds neighbourhood + config
│   ├── CellularAutomataConfiguration      ← immutable config; use inner Builder
│   │   └── CellularAutomataConfigurationBuilder
│   ├── AbstractCellularAutomataRule       ← shared listener management + buffer swap helper
│   ├── CellularAutomataRule               ← abstract; extend to define the transition rule
│   ├── CellularAutomataParallelRule       ← parallel variant; extend for multi-threaded rules
│   ├── CellularAutomataRunner             ← internal — Callable<Void> for parallel transition
│   ├── CellularAutomataRefinementRunner   ← internal — Callable<Void> for parallel refinement
│   └── GenerationListener                 ← @FunctionalInterface; notified after each generation
│
├── grid/
│   ├── Cell                               ← one cell; has a CellState + int[] coordinates
│   ├── CellState                          ← a cell's state; key (String) + arbitrary value Object
│   ├── CellGrid                           ← unified n-dimensional grid (2D–4D, flat array)
│   ├── GridDimensions                     ← immutable nD descriptor (sizes, strides, total)
│   └── GridSnapshot                       ← immutable snapshot of a CellGrid at a generation
│
├── neighborhood/
│   ├── Neighborhood                       ← abstract base; extend for custom neighbourhoods
│   ├── NDCapable                          ← marker interface; implement for 3D/4D custom neighbourhoods
│   ├── NeighborhoodType                   ← enum: MOORE | VON_NEUMANN
│   ├── NeighborhoodFactory                ← internal — resolves 2D/3D/4D class by type+dimension
│   ├── MooreNeighborhood                  ← built-in 2D: 8 surrounding cells
│   ├── VonNeumannNeighborhood             ← built-in 2D: 4 orthogonal cells
│   ├── Moore3DNeighborhood                ← built-in 3D: 26 surrounding cells
│   ├── VonNeumann3DNeighborhood           ← built-in 3D: 6 orthogonal cells
│   ├── Moore4DNeighborhood                ← built-in 4D: 80 surrounding cells
│   └── VonNeumann4DNeighborhood           ← built-in 4D: 8 orthogonal cells
│
├── ui/
│   ├── CellRenderer                       ← @FunctionalInterface: CellState → Color
│   ├── GridDisplay                        ← interface: accepts a GridSnapshot for rendering
│   ├── GridPanel                          ← Swing JPanel; paints the grid via CellRenderer
│   ├── CellularAutomataDisplay            ← JFrame-backed window + generation counter
│   ├── AutomataListener                   ← GenerationListener that drives a GridDisplay
│   └── CellularAutomataUIRunner           ← fluent façade: wires display + listener + thread
│
├── utils/
│   └── Utils                              ← internal helpers (isInside, cloneGrid) — final, non-instantiable
│
└── examples/
    ├── GameOfLifeExample                  ← 2D minimal runnable example
    ├── GameOfLifeUiExample                ← 2D example with Swing real-time visualisation
    ├── GameOfLifeAdvancedUiExample        ← 2D advanced patterns with full UI API
    ├── GameOfLife3DExample                ← 3D example: Carter Bays' 3D Life
    ├── GameOfLife3DUiExample              ← 3D example with Swing visualisation
    └── CustomStateExample                 ← advanced example with multi-value state

for each generation:
  1. refinements(cell)           — applied to every cell  [optional CCA hook]
  2. snapshot the grid           — clone the grid before any mutation
  3. transition(cell, neighbors)  — per cell, reads snapshot, writes result
  4. copy result back            — update the main grid with all new states

Cell   get(int[] coords)
void   set(int[] coords, Cell cell)
List<int[]> allCoordinates()
GridDimensions getDimensions()
boolean is2D()

flat index = coords[0] * stride[0] + coords[1] * stride[1] + … + coords[n-1] * stride[n-1]

public class MyRule extends CellularAutomataRule {
    @Override
    public Cell transition(Cell cell, List<Cell> neighbors) {
        // inspect cell.getCurrentStatus() and neighbors
        // return a new Cell with the next state
    }
}

CellState complex = new CellState("state", Map.of("temp", 100, "pressure", 3));

public class DiagonalNeighborhood extends Neighborhood {
    @Override
    public List<Cell> getNeighbors(Cell[][] matrix, int i, int j) {
        // return a list of neighbor cells
    }
}

public class Custom3DNeighborhood extends Neighborhood {
    @Override
    public List<Cell> getNeighbors(CellGrid grid, int[] coords) {
        // return a list of neighbor cells
    }
}

@Override
public Cell refinements(Cell cell) {
    // update internal state before neighbors are read
    return cell;
}

CellularAutomataConfigurationBuilder
    → CellularAutomataConfiguration (immutable)
    → CellularAutomata(config)       ← builds CellGrid + resolves neighborhood
    → executor.run(ca)               ← applies transition for N generations
    → updated CellularAutomata