← All decisions

#0031 · 2026-08-08 · accepted · architecture

Architecture cleanup: deleted the unused glemy/cs compute-shader layer, added ARCHITECTURE.md as the standing rule set

architecturecleanupcsdocumentation

Context

User asked for a full architecture refactor: delete unnecessary files, modularize what's necessary, and -- explicitly -- not build the module structure arbitrarily, researching standard architectural choices and writing down a rule set so future work doesn't have to re-derive where things belong. An audit (counting real, non-test importers of every src/glemy module) found exactly one genuinely dead subtree: glemy/cs (cs.gleam, cs/entity_batch.gleam, cs/vector2_batch.gleam, their _ffi.mjs files, and their two test files) -- a GPU compute-shader batch-physics layer that was part of the project's original, user-requested 4-module architecture (decision 0002: io/pe/cs/render) and is fully built, tested, and passing, but has zero callers outside its own tests. pe.gleam's actual physics tick has always run on the CPU in plain Gleam; decision 0014 capped max_entities at 150 instead of ever needing cs's GPU parallelism. Every other module in the codebase (io, pe and its pe/* submodules, render, game, and their FFI) has real production callers. Separately, researched what a 'standard' architecture for this kind of project actually is rather than inventing one: Gleam's own official conventions doc (gleam.run) explicitly directs module boundaries to be drawn around business-domain concepts, never generic layering/pattern vocabulary -- which the existing pe/{vector2,entity,bounds,collision,tier} split already does. The existing FFI-minimal split between pure Gleam and @target(javascript)-gated FFI wrappers (decisions 0013/0016) is itself a named, standard pattern -- Functional Core, Imperative Shell -- not a project-specific invention, confirmed by independent research into the pattern's own literature.

Options considered

Keep glemy/cs as documented, intentionally-unused capability — rejected
Asked the user directly rather than assuming: given the user's explicit 'delete unnecessary files' instruction and that nothing currently depends on it or has concrete plans to, keeping speculative infrastructure around contradicts this project's own established practice of not building ahead of a real, current need (decision 0014's broad-phase-collision reasoning is the same argument applied to a different subsystem).
Wire glemy/cs into pe.gleam now, actually using it — rejected
A real architectural change with its own scope and verification needs (replacing pe's proven, tested CPU integration path with a GPU one), not a cleanup task -- explicitly deferred as a separate, future decision if a real need for GPU-parallel physics ever materializes, rather than bundled into this refactor.
Delete glemy/cs entirely (cs.gleam, cs/entity_batch.gleam, cs/vector2_batch.gleam, their FFI, their tests) and write ARCHITECTURE.md documenting the real, current module layout and the rules for where new code goes — chosen
Directly answers both halves of the user's request: removes the one genuinely dead subtree the audit found, and replaces ad-hoc/undocumented structure with an explicit, researched rule set (grounded in Gleam's own conventions and the Functional Core/Imperative Shell pattern already in de facto use) so future contributors -- human or agent -- don't have to reconstruct 'where does this go' from scattered decision-log entries.

Decision

Deleted src/glemy/cs.gleam, src/glemy/cs/ (entity_batch.gleam, entity_batch_ffi.mjs, vector2_batch.gleam, vector2_batch_ffi.mjs), and test/glemy/cs/ (both test files). Updated every stale doc-comment reference to glemy/cs in pe.gleam, render.gleam, io.gleam, gpu_ffi.mjs (which stays -- render_ffi.mjs still needs its shared WebGPU device singleton), and docs/development-plan.md (§8's roadmap item marked '(later removed)' with an explanation, rather than silently deleting the historical record of what was built and why). Added ARCHITECTURE.md at the repo root: documents the Functional Core/Imperative Shell split already in use with a concrete current module table, a decision tree for where new code should go, the FFI-minimality rule (decision 0016) restated as an actionable checklist, the test-mirrors-source convention, and an explicit 'what not to do' section using glemy/cs itself as the worked example of unused code that should have been caught sooner.

Verification

146 Erlang / 169 JavaScript gleam test cases passing on both targets after the deletion (169, not 180 -- the 11-test difference is exactly cs's own two removed JavaScript-only test files, gleam build produces zero errors or dangling-import warnings on either target). Confirmed via a repo-wide grep for every module's import statement, counted per-module non-test-file importers, that no other src/glemy module is similarly unused -- glemy/cs was the only genuine dead subtree, not a symptom of a broader pattern.

Consequences

The codebase now contains no built-but-unwired subsystems; every module has at least one real, non-test caller. Future work adding a genuinely new domain concept, FFI capability, or dev tool has a single, explicit reference (ARCHITECTURE.md) for which of the established patterns it should follow, rather than needing to infer the convention from example or ask. If GPU-parallel batch physics is ever genuinely needed again, ARCHITECTURE.md's 'what not to do' section explicitly says so and points at this decision as the reason it isn't already half-built waiting.

References