docs: establish modular architecture rules — app.js is thin orchestrator #430

perplexity · 2026-03-24T17:12:37Z

perplexity commented

2026-03-24 17:12:37 +00:00

Summary

Establishes the modular ES module architecture as the law of the Nexus. app.js becomes a thin orchestrator that should almost never change.

What Changed

Architecture section: Replaced single-file description with full modules/ directory structure
Conventions: Added 6 new enforceable rules (module contract, single clock, theme, state, atomic PRs, no new code in app.js)

Data Integrity Audit

Element	Category	Data Source
N/A — documentation only	N/A	N/A

Test Plan

This is a docs-only change — no runtime behavior affected
Verify CLAUDE.md renders correctly in Gitea
All future PRs must follow the new modular architecture rules

Verification

Documentation change — no screenshot needed. The architecture will be verified as modularization phases (#420-#424) are implemented.

Refs #409, #429

## Summary Establishes the modular ES module architecture as the law of the Nexus. app.js becomes a thin orchestrator that should almost never change. ## What Changed - **Architecture section**: Replaced single-file description with full `modules/` directory structure - **Conventions**: Added 6 new enforceable rules (module contract, single clock, theme, state, atomic PRs, no new code in app.js) ## Data Integrity Audit | Element | Category | Data Source | |---------|----------|-------------| | N/A — documentation only | N/A | N/A | ## Test Plan 1. This is a docs-only change — no runtime behavior affected 2. Verify CLAUDE.md renders correctly in Gitea 3. All future PRs must follow the new modular architecture rules ## Verification Documentation change — no screenshot needed. The architecture will be verified as modularization phases (#420-#424) are implemented. Refs #409, #429

perplexity added 1 commit 2026-03-24 17:12:38 +00:00

docs: establish modular architecture rules — app.js is thin orchestrator

CI / validate (pull_request) Successful in 4s

Details

CI / auto-merge (pull_request) Successful in 2s

Details

4d19042566

- Replace single-file architecture with ES module system
- Define modules/ directory structure (core, data, panels, effects, terrain, portals, narrative, utils)
- Establish module contract: init(scene, state, theme) + update(elapsed, delta)
- Single animation clock (ticker.js) — no direct RAF calls from modules
- Theme is law — no inline hex codes
- Data flows through state.js — no fetch() outside data/ modules
- Atomic PRs — target <150 lines per PR
- No new code in app.js — new features go in modules

Refs #409, #429

Timmy merged commit 9ec5c52936 into main

2026-03-24 17:12:49 +00:00

Timmy deleted branch claude/modular-architecture-rules

2026-03-24 17:12:50 +00:00

Timmy referenced this issue from a commit

2026-03-24 17:12:51 +00:00

docs: establish modular architecture rules — app.js is thin orchestrator (#430)

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Timmy_Foundation/the-nexus#430