52 lines
3.3 KiB
Markdown
52 lines
3.3 KiB
Markdown
# Architecture Rules
|
|
|
|
Follow these rules for the whole repository. More specific `AGENTS.md` files override/add rules for their folders.
|
|
|
|
## Boundaries
|
|
- `core/`: pure domain models only. See `core/AGENTS.md`.
|
|
- `commands/`: the only write path for application state.
|
|
- `editor/`: transient editor/app state types, e.g. viewport/camera and selection.
|
|
- `renderer/`: renders the current `ImageDocument` using the graphics backend, e.g. WebGL.
|
|
- `view/`: React UI shell and controls only.
|
|
|
|
## State Ownership
|
|
- All persistent document state is represented by `ImageDocument` and related `core/` models.
|
|
- Transient editor state is application state too: viewport/camera, selection, tools, active artboard/layer, drag state, etc.
|
|
- Commands are the only code allowed to create, replace, or mutate persistent or transient state.
|
|
- React must not own, manage, derive authoritative, or alter document/editor state.
|
|
- React may hold only local ephemeral UI details with no app meaning, e.g. open popover, hovered button, uncontrolled input draft before command submit.
|
|
- Do not update state directly from React event handlers, renderer callbacks, effects, stores, services, or keybind handlers. Dispatch a command instead.
|
|
|
|
## Commands
|
|
- Every state change must be modeled as a command with an explicit id, payload, and context.
|
|
- Commands must be deterministic and testable; avoid DOM, React, WebGL, timers, network, and filesystem access inside command execution.
|
|
- Commands return/apply the next state; they should preserve domain invariants and validate payloads before changing state.
|
|
- UI actions, menus, toolbar buttons, keybinds, and renderer interactions all request changes by dispatching commands.
|
|
|
|
## React / View
|
|
- React displays current state and exposes user intent.
|
|
- React components receive state snapshots/selectors and command dispatch functions; they do not contain business rules.
|
|
- Do not put rendering engine logic, document mutation logic, or editor workflow ownership in React components.
|
|
- Effects are for UI integration/subscription setup only, not for deriving or correcting application state.
|
|
|
|
## Renderer
|
|
- The renderer draws the current `ImageDocument` plus read-only editor state overlays.
|
|
- Renderer code must not mutate document/editor state directly.
|
|
- Renderer interactions may emit intents/events that are translated into commands.
|
|
- Keep rendering backend details isolated behind renderer APIs; do not leak WebGL objects into `core/`, `commands/`, or React state.
|
|
|
|
## Keybinds
|
|
- Keybind handling is ordered and explicit.
|
|
- First check the global keybind consumer/map.
|
|
- If the global consumer handles the keybind, stop.
|
|
- If not consumed globally, the keybind may be consumed by dispatching a command.
|
|
- Keybind handlers must not mutate state directly.
|
|
- Avoid ad-hoc component-local shortcuts unless they are purely local UI behavior and cannot affect app/editor/document state.
|
|
|
|
## Imports
|
|
- `core/` imports nothing from app layers.
|
|
- `commands/` may import `core/` and `editor/`; avoid importing React or renderer backend APIs.
|
|
- `editor/` may import `core/` types; it must not import React, commands, renderer, storage, or backend APIs.
|
|
- `renderer/` may import `core/` and `editor/` types; it must not import React components.
|
|
- `view/` may import UI components and command dispatch interfaces; avoid importing renderer internals except through stable view-facing adapters.
|