CODE_MAP.md

Code Map

This is a runtime-focused map of the app. It is meant to answer two questions quickly:

1. Where does the app start in server mode and standalone mode?
2. Which files and functions should you follow for a given kind of change?

For the higher-level architecture, see ARCHITECTURE.md. For cleanup priorities and known structural pressure points, see CODE_QUALITY_ROADMAP.md. For maintenance workflows and repo-owned guardrails, see MAINTENANCE.md.

Start Here

Server runtime

1. app.py Entry script for local Flask development. Calls create_app() and starts the dev server.
2. backend/api.py Flask app factory. create_app(...) wires config, frontend assets, topology metadata, simulation extensions, and routes.
3. backend/simulation/bootstrap.py register_simulation(app) creates and stores the rule registry and session registry.
4. backend/web/routes.py HTTP entrypoints for state fetches and mutations. Server-mode simulation calls use /api/sessions/<session_id>/... and resolve the session coordinator lazily.
5. backend/web/state_actions.py Bridges validated request payloads to simulation mutations.
6. backend/simulation/sessions.py Owns session-id validation and per-session coordinator lifecycle/persistence paths.
7. backend/simulation/coordinator.py Coordinates runtime, persistence, restore, and simulation service.
8. backend/simulation/service.py Main synchronous simulation API used by the host layers.
9. backend/simulation/engine.py Pure stepping engine that asks the current rule for each cell's next state.

Standalone browser runtime

1. tools/standalone_build.py Python-first standalone packager that stages the transient build input, runs the standalone Vite build, and finalizes the published static output.
2. frontend/shell/app-shell-body.html Shared shell source used by both Flask and the standalone wrapper.
3. tools/standalone_shell.py Shared standalone wrapper renderer used by python -m tools build standalone-shell and the standalone build flow.
4. frontend/standalone.ts startStandaloneApp() loads bootstrap JSON, creates the standalone worker environment, and then calls initApp(...).
5. frontend/standalone/worker-client.ts createStandaloneEnvironment(...) creates the Web Worker, talks to Pyodide, and exposes a SimulationBackend.
6. frontend/standalone-worker.ts Worker entrypoint that loads Python and forwards commands into the browser runtime host.
7. backend/browser_runtime.py Python runtime host for standalone mode. Exposes initialize_runtime(...), handle_request(...), and tick_running().

Browser UI startup

1. frontend/server-entry.ts Canonical server host entrypoint.
2. frontend/app-runtime.ts initApp(...) mounts the wall⇄Lab workspace router into the shared shell and marks the app ready once the landing route settles; the editor controller boots lazily on first entry to #/lab.
3. frontend/app-controller.ts createAppController(...) composes state, view, actions, sync, and interactions.
4. frontend/app-controller-startup.ts initializeAppController(...) orchestrates service construction, interaction wiring, and hydration.
5. frontend/app-controller-services.ts Builds the session/config-sync/simulation-mutation service layer.
6. frontend/app-controller-wiring.ts Connects interactions, viewport sync, and the action surface.
7. frontend/app-controller-hydration.ts Preserves the async startup order for rules, controls, refresh, and listeners.
8. frontend/app-actions.ts Creates the action surface used by controls and interaction handlers.
9. frontend/app-view.ts Renders the control shell and canvas-facing UI.

Request Flow

Server-backed flow

Browser UI
  -> frontend/api.ts
  -> backend/web/routes.py (/api/sessions/<session_id>/...)
  -> backend/simulation/sessions.py
  -> backend/web/state_actions.py
  -> backend/simulation/coordinator.py
  -> backend/simulation/service.py
  -> backend/simulation/engine.py + backend/rules/*
  -> snapshot response
  -> frontend/state/snapshot-reducer.ts
  -> canvas + controls rerender

Standalone flow

Browser UI
  -> frontend/standalone/worker-client.ts
  -> frontend/standalone-worker.ts
  -> backend/browser_runtime.py
  -> backend/simulation/service.py
  -> backend/simulation/engine.py + backend/rules/*
  -> worker response
  -> frontend/state/snapshot-reducer.ts
  -> canvas + controls rerender

Frontend Map

App composition

• frontend/app-runtime.ts initApp(...), disposeApp()
• frontend/server-entry.ts Server-only host bootstrap.
• frontend/app-controller.ts createAppController(...)
• frontend/app-controller-startup.ts initializeAppController(...)
• frontend/app-controller-services.ts Service-phase startup wiring.
• frontend/app-controller-wiring.ts Interaction, viewport, and action wiring.
• frontend/app-controller-hydration.ts Async hydration and control-binding order.
• frontend/app-controller-sync.ts createAppControllerSync(...)
• frontend/app-controller-bootstrap.ts createAppControllerBootstrap(...), createViewportControllerDependencies(...)
• frontend/config-sync-controller.ts createConfigSyncController(...)
• frontend/ui-session-controller.ts createUiSessionController(...)
• frontend/server-environment.ts createServerEnvironment()
• frontend/bootstrap-data.ts installBootstrapData(...), bootstrapDataFromWindow(), fetchBootstrapData(...)

App state

• frontend/state/simulation-state.ts Main app state container and mutation helpers. Key functions: createAppState(), setRules(...), setActiveRule(...), setTopology(...), setSpeed(...)
• frontend/state/snapshot-reducer.ts applySimulationSnapshot(...)
• frontend/simulation-reconciler.ts createSimulationReconciler(...)
• frontend/state/selectors.ts currentEditorRule(...), currentDimensions(...), topologyRenderPayload(...)
• frontend/state/sizing-state.ts Cell-size and patch-depth rules.
• frontend/state/overlay-state.ts Drawer, inspector, hint, blocking, and edit-mode state.
• frontend/state/polling.ts schedulePolling(...), syncPolling(...), stopPolling(...)

Actions and control flow

• frontend/app-actions.ts createAppActions(...)
• frontend/app-action-groups.ts Groups action composition into simulation/config, pattern/preset/showcase, and editor/UI seams.
• frontend/actions/simulation/index.ts createSimulationActions(...)
• frontend/actions/simulation/topology-selection-plan.ts Pure topology reset and selection planning.
• frontend/actions/simulation/topology-selection-runtime.ts Transaction layer for optimistic topology changes, reset dispatch, and rollback.
• frontend/actions/simulation/run-actions.ts Start, pause, resume, step actions.
• frontend/actions/simulation/rule-actions.ts Rule changes.
• frontend/actions/simulation/topology-actions.ts Topology changes.
• frontend/actions/pattern-import-plan.ts Pure pattern-import confirmation, reset-request, and cell-update helpers.
• frontend/actions/pattern-import-runtime.ts Pattern import parsing, mutation orchestration, validation, and status handling.
• frontend/actions/preset-actions.ts Applies built-in seed presets.
• frontend/actions/pattern-actions.ts Thin import/export/copy/paste entrypoints and export serialization.
• frontend/actions/ui-actions.ts Theme, drawer, and disclosure UI actions.

Controls and view

• frontend/app-view.ts Top-level UI composition.
• frontend/controls-view.ts renderControls(...)
• frontend/controls-model.ts collectConfig(...), buildControlsViewModel(...)
• frontend/controls-model/shared.ts Shared view-model builders for run state, blocking state, overlay state, and numeric controls.
• frontend/controls-bindings.ts bindControls(...)
• frontend/controls Shell, simulation, editor/pattern, chrome, and disclosure render/binding modules.

Canvas, rendering, and geometry

• frontend/canvas-view.ts createCanvasGridView(...), hit testing, and cell-center helpers.
• frontend/canvas/render-layers.ts drawCommittedLayer(...), drawPreviewLayer(...)
• frontend/canvas/render-style.ts Color and line-style resolution. Key functions: resolveCanvasRenderStyle(...), resolveDeadCellColor(...), resolveRenderedCellColor(...)
• frontend/canvas/draw.ts Shared polygon and triangle path/stroke helpers.
• frontend/canvas/cache.ts resolveGeometryCache(...)
• frontend/geometry/registry.ts getGeometryAdapter(...), listGeometryAdapters() Bootstraps geometry adapters from topology render_kind metadata instead of hand-maintained geometry lists.
• frontend/geometry/square-adapter.ts
• frontend/geometry/hex-adapter.ts
• frontend/geometry/triangle-adapter.ts
• frontend/geometry/periodic-mixed-adapter.ts Main mixed-tiling adapter.
• frontend/geometry/penrose-adapter.ts
• frontend/geometry/aperiodic-prototile-adapter.ts

Interaction and editor stack

• frontend/interactions.ts createInteractionController(...)
• frontend/interaction-groups.ts Splits interaction composition into mutation policy, editor runtime, and surface/command wiring.
• frontend/interactions/editor-session.ts Edit-session lifecycle.
• frontend/interactions/simulation-mutations.ts Commits UI edit intents to the simulation backend.
• frontend/interactions/command-dispatch.ts Serialized command dispatch.
• frontend/editor-operation-builders.ts Brush, line, rectangle, and fill cell builders.
• frontend/editor-history.ts Undo/redo stack and edit diff handling.

Patterns, presets, and topology metadata

• frontend/pattern-io.ts buildPatternPayload(...), serializePatternPayload(...), readPatternFile(...), clipboard helpers.
• frontend/presets.ts listAvailablePresets(...), buildPresetSeed(...)
• frontend/presets/registry.ts Rule-to-preset registry.
• frontend/topology-catalog.ts Frontend topology definition lookup and picker metadata.
• frontend/topology.ts Topology helpers like indexTopology(...), findTopologyCellById(...)

Compare mode

A self-contained overlay that runs one seed under one rule across many tilings and renders the result. It is mounted once from frontend/app-runtime.ts and talks to the backend through SimulationBackend.compareSeed(...) (HTTP POST /api/compare on the server, the /api/compare worker command in standalone). The UI asks for optional state payloads so each result row can open or copy share links for the seed state and final state on that tiling, and can expand an inline begin/end thumbnail.

• frontend/compare/compare-panel.ts mountComparePanel(...): the launcher button, modal form (rule/seed/traversal/steps/tilings), run orchestration, results rendering, compare-row share/open actions, and the per-row thumbnail expander (fetches geometry via SimulationBackend.previewTopology(...), cached per tiling).
• frontend/compare/compare-charts.ts Pure layout helpers plus the SVG phase portrait (live(t)/live(0) per tiling) and the end-state classification grid, including the optional per-row action cell hook.
• frontend/compare/compare-thumbnail.ts Renders a tiling's board as an SVG (one polygon per cell, coloured by state) from a topology_preview payload, with pure bounds/fit helpers.
• frontend/compare/compare-seed-pad.ts createSeedPad(...): a paint grid for designing the seed by drawing, two-way bound to the seed bit string (the exact inverse of the traversal: read row-major to bits, fill row-major from bits). Pure bit/grid helpers are exported for tests.
• frontend/compare/compare-seed-preview.ts createSeedPreview(...): a live strip showing where the drawn seed lands on the first few selected tilings. Fetches each tiling's geometry and canonical cell order once (via previewTopology with a traversal), then places the seed client-side (placeSeedOnOrder, the same mapping the comparison uses) and re-renders begin-state thumbnails as you draw.
• frontend/compare/compare-panel.css and frontend/compare/compare-options.ts Injected stylesheet (imported ?inline so it ships minified inside the compare-panel chunk) and the traversal option list.

Backend Map

Flask host and request layer

• backend/api.py create_app(...)
• backend/app_shell.py Shared shell rendering for the Flask wrapper and standalone shell generation.
• backend/web/routes.py Thin Flask routes and JSON response helpers. Main endpoints: get_state(), get_rules(), get_bootstrap(), start(), pause(), resume(), step(), reset(), update_config(), toggle_cell(), set_cell(), set_cells(), compare() (POST /api/compare, runs a seed sweep without mutating simulation state), topology_preview() (POST /api/topology/preview, builds one tiling with per-cell geometry for thumbnails)
• backend/web/state_actions.py StateActionService
• backend/web/requests.py get_payload(request)
• backend/contract_validation.py Shared payload validation for both Flask and standalone browser runtime.

Simulation façade and runtime

• backend/simulation/bootstrap.py register_simulation(app)
• backend/simulation/coordinator.py SimulationCoordinator
• backend/simulation/coordinator_persistence.py Persistence scheduling and save/load orchestration.
• backend/simulation/coordinator_restore.py Persisted-state restore flow.
• backend/simulation/coordinator_mutations.py Immediate vs deferred mutation dispatch.
• backend/simulation/service.py SimulationService Key methods: get_state(), step(), reset(...), update_config(...), toggle_cell_by_id(...), set_cell_state_by_id(...), set_cells_by_id(...)
• backend/simulation/runtime.py SimulationRuntime
• backend/simulation/engine.py SimulationEngine.step_board(...)
• backend/simulation/service_transitions.py apply_reset_transition(...), apply_config_transition(...)
• backend/simulation/service_boards.py Board creation, coercion, and transfer helpers.
• backend/simulation/service_cells.py Cell mutation helpers.
• backend/simulation/service_snapshots.py snapshot_state(...)

Models, topology, persistence

• backend/simulation/models.py TopologySpec, SimulationConfig, RuleSnapshot, SimulationSnapshot, SimulationStateData
• backend/simulation/topology.py Public compatibility façade for topology types and board builders.
• backend/simulation/topology_types.py LatticeCell, LatticeTopology, SimulationBoard, regular cell ids, revision hashing.
• backend/simulation/topology_regular.py Square, hex, and triangle lattice builders.
• backend/simulation/topology_specialized.py Periodic-face and aperiodic patch conversion helpers.
• backend/simulation/topology_builders.py Shared topology assembly and cached build_topology(...). Delegates geometry dispatch through the topology implementation registry.
• backend/simulation/topology_implementation_registry.py Internal builder and render dispatch registry. Maps each geometry key to a builder_kind, render_kind, and backend builder entrypoint.
• backend/simulation/topology_boards.py empty_board(...), board_from_states(...), board_from_cells_by_id(...)
• backend/simulation/rule_context.py Public compatibility façade for rule-context frames and queries.
• backend/simulation/rule_context_frames.py TopologyFrame, frame cache, and topology_frame_for(...).
• backend/simulation/rule_context_queries.py RuleContext, NeighborSelection, build_rule_contexts_for_board(...).
• backend/simulation/persistence.py SimulationStateStore
• backend/simulation/state_restore.py SimulationStateRestorer
• backend/simulation/persistence_coordinator.py Debounced save scheduling.
• backend/simulation/transition_planner.py Pure transition planning for reset, config, and restore.

Topology catalog and generated tilings

• backend/simulation/topology_catalog.py Public topology catalog façade.
• backend/simulation/topology_catalog_data.py Static topology definitions.
• backend/simulation/topology_catalog_types.py Catalog dataclasses and definition types.
• backend/simulation/topology_catalog_build.py Catalog assembly.
• backend/simulation/topology_catalog_queries.py Serialization helpers.
• backend/simulation/periodic_face_tilings.py Periodic mixed-face tiling descriptors and generated cells.
• backend/simulation/penrose.py Penrose patch builder.
• backend/simulation/aperiodic_prototiles.py Public aperiodic patch facade and Penrose P3 conversion path.
• backend/simulation/aperiodic_support/ Shared aperiodic patch package. types.py holds the dataclasses and TypedDict records, geometry.py the vertex/edge/centroid helpers, affine.py the 2D affine math + orientation/chirality tokens, neighbors.py the float and exact-Fraction edge-neighbour detection, and patches.py the high-level patch constructors. __init__.py re-exports everything so legacy from backend.simulation.aperiodic_support import X callers work unchanged.
• backend/simulation/aperiodic_substitution.py Reusable substitution-recipe helper for recursive affine expansion, structured substitution nodes, metadata propagation, and deterministic leaf flattening.
• backend/simulation/aperiodic_registry.py Registry-backed dispatch for family-specific aperiodic builders and recipe styles.
• backend/simulation/literature_reference_specs.py Source-backed reference specs for literature-faithfulness verification of the full topology catalog.
• backend/simulation/literature_reference_verification.py Verifier that compares canonical regular, periodic, and aperiodic topology samples against source-backed invariants, and checks the exact-affine Pinwheel path.
• backend/simulation/aperiodic_golden_triangles.py Shared golden-triangle geometry and metadata helpers for Robinson and Tuebingen families.
• backend/simulation/aperiodic_penrose_p2.py
• backend/simulation/aperiodic_ammann_beenker.py
• backend/simulation/aperiodic_spectre.py
• backend/simulation/aperiodic_taylor_socolar.py
• backend/simulation/aperiodic_sphinx.py
• backend/simulation/aperiodic_hat.py
• backend/simulation/aperiodic_tuebingen_triangle.py
• backend/simulation/aperiodic_dodecagonal_square_triangle.py
• backend/simulation/aperiodic_shield.py
• backend/simulation/aperiodic_pinwheel.py Family-specific aperiodic patch builders, including Spectre, the Taylor-Socolar half-hex factor, Sphinx, Hat, Tuebingen Triangle, Schlottmann Square-Triangle, Shield, and Pinwheel. Pinwheel uses the exact-record helper path in aperiodic_support.patches (via the new ExactSimilaritySubstitution shared helper); the other rebuilt families still emit the standard polygon patch format.

Rules

• backend/rules/init.py RuleRegistry
• backend/rules/base.py AutomatonRule, CellStateDefinition
• backend/rules/life_like.py Shared binary and kind-aware Life helpers.
• Concrete rules:
  • backend/rules/conway.py
  • backend/rules/highlife.py
  • backend/rules/hexlife.py
  • backend/rules/trilife.py
  • backend/rules/kagome_life.py
  • backend/rules/archlife488.py
  • backend/rules/archlife_extended.py
  • backend/rules/wireworld.py
  • backend/rules/whirlpool.py
  • backend/rules/penrose_greenberg_hastings.py

Seed comparison

backend/simulation/seeding maps one seed onto many topologies so the same rule can be compared across tilings. It is headless and reuses the cached TopologyFrame, so it works without Flask.

• backend/simulation/seeding/traversal.py Canonical cell-id orderings (bfs_ring_order, row_major_order) plus paint_bits. The seed bit-string is walked in traversal order, preserving live-cell count across tilings.
• backend/simulation/seeding/metrics.py Rule-agnostic measurement: population, hamming change rate, and end-state classify (extinct / still-life / oscillator / unsettled).
• backend/simulation/seeding/comparison.py compare_seed(...) sweeps a seed across geometries, detects cycles, isolates per-tiling errors, flags degenerate seeds, and can optionally return sparse begin/end board states for callers that need reconstructable links. Accepts a pattern for shape-mode seeding.
• backend/simulation/seeding/shapes.py Policy A: a named-pattern library (glider, R-pentomino, …) and place_pattern(...), which centres a recognisable shape on a topology and lights the nearest cell to each point — preserving the 2-D shape across tilings instead of the live-cell count.

Tests And Tooling

Tests

• tests/api API contract and route coverage.
• tests/unit Backend service, topology, persistence, validation, and frontend-support unit tests.
• tests/e2e Playwright-backed browser coverage for both server and standalone runtimes.

Tooling

• tools/cli.py Unified python -m tools ... entrypoint. Registers the public command groups and dispatches into task-focused command modules.
• tools/command_docs.py Single source of truth for command metadata, examples, and generated tools documentation.
• tools/commands/build.py Public build group wiring for standalone, standalone-shell, and bundle-size.
• tools/standalone_build.py Builds the static standalone site and writes the provenance manifest.
• tools/standalone_shell.py Shared standalone-shell renderer behind python -m tools build standalone-shell.
• tools/playwright_runner.py Public Playwright runner behind python -m tools test e2e. Lists suites, prepares standalone builds, repairs Linux browser libraries when possible, and dispatches Python unittest modules.
• tools/commands/browser.py Public browser-diagnosis command wiring for review, managed checks, sweeps, diffs, workbenches, and standalone smoke tests.
• tools/render_review/review.py Focused browser-backed render-review implementation. Renders one topology through the real canvas path, supports named profiles, profile-owned literature metadata, optional reference montages, and writes PNG plus JSON summary output.
• tools/render_review/browser_check.py Managed browser-diagnosis runner. Owns standalone/server host startup, readiness, logging, cleanup, and run-manifest output for focused render reviews or targeted Python unittest browser checks.
• tools/render_review/sweep.py Small-matrix render-review orchestrator. Expands one named profile across selected hosts, themes, and sizes, reuses the managed runner for each case, and writes one top-level sweep manifest plus one comparable artifact directory per case.
• tools/render_review/diff_review.py One-command render-review comparison sheet builder. It can run a new sweep or consume an existing sweep-manifest.json, then emits one HTML sheet plus one PNG contact sheet for side-by-side review.
• tools/dev_processes.py Repo-scoped process inspection and cleanup helper for known browser/server helper processes, including the quick stale-host cleanup command and Windows listening-port discovery.
• tools/commands/tilings.py Public tilings group wiring for validation, verification, reporting, previews, sketching, aperiodic scaffolding, and seed comparison.
• tools/compare_seed.py Backs python -m tools tilings compare: runs a seed under one rule across many tilings and reports population, end-state classification, and the degenerate-seed guard as a table or JSON.
• tools/validate_tilings.py Manifest-wide geometric sanity checker for catalog tilings.
• tools/verify_reference_tilings.py Literature-faithfulness verifier for the full topology catalog.
• tools/export_bootstrap_data.py Exports bootstrap metadata for standalone mode.
• tools/tools_docs.py Generates and checks docs/TOOLS.md from the command registry.
• tools/render_review/browser_support/artifacts.py Shared browser-failure artifact writer used by the managed runner, render-review tool, and Playwright harness so local diagnosis and failing tests emit the same core bundle shape.
• vite.config.ts Frontend build configuration.

Current Refactor Targets

Use this list to decide where cleanup work should start. These are the files with the most structural pressure today, not necessarily the files with the most defects.

• Frontend gesture orchestration: surface-bindings.ts, paint-drag.ts, editor-session.ts, command-dispatch.ts
• Canvas transient overlays: canvas-view.ts, render-layers.ts, render-style.ts
• Drawer metadata and inspector modeling: drawer.ts, view-sections.ts, app-view.ts
• Aperiodic implementation quality: aperiodic_registry.py, aperiodic_substitution.py, aperiodic_support/, aperiodic_shield.py
• Literature verification size and ownership: literature_reference_specs.py, literature_reference_verification.py
• Frontend/backend contract drift: types/domain.d.ts, types/controller-api.d.ts, payload_types.py, contract_validation.py

If You Want To Change...

• HTTP endpoint behavior: Start with backend/web/routes.py and backend/web/state_actions.py
• Simulation transitions or board mutation: Start with backend/simulation/service.py and backend/simulation/service_transitions.py
• Rule logic: Start with backend/rules/base.py and the concrete rule file under backend/rules
• Topology generation: Start with backend/simulation/topology.py, backend/simulation/topology_builders.py, and backend/simulation/topology_catalog.py
• Canvas rendering: Start with frontend/canvas/render-layers.ts, frontend/canvas/render-style.ts, and the relevant adapter under frontend/geometry
• Control UI: Start with frontend/controls-model.ts, frontend/controls-view.ts, and frontend/controls-bindings.ts
• Editor behavior: Start with frontend/interactions/editor-session.ts, frontend/editor-operation-builders.ts, and frontend/editor-history.ts
• Standalone browser runtime: Start with frontend/standalone.ts, frontend/standalone/worker-client.ts, and backend/browser_runtime.py
• Shared shell or startup wrappers: Start with frontend/shell/app-shell-body.html, backend/app_shell.py, and tools/standalone_shell.py