ADR 0028 — TypeScript Architecture Boundaries
Context
Section titled “Context”Restura compiles one repository into independent renderer, Worker/Node, Electron, CLI, and extension programs. TypeScript catches local type errors, but it does not prevent an application from importing in the wrong direction, adding a runtime cycle, or growing another monolithic module.
Decision
Section titled “Decision”shared/ is the runtime-neutral dependency floor. It cannot depend on an application, and Worker, Electron main, and CLI cannot depend on renderer-owned src/ modules. Renderer compatibility barrels may re-export shared owners while callers migrate.
npm run architecture:check parses TypeScript and enforces source-zone directions, an acyclic runtime import graph, an 800-line ceiling for new production modules, and exact non-growing caps for legacy oversized files. The same exact-count ratchet also applies to configured source patterns (sourcePatternRatchets), first used to drive off-scale font sizes in src/**/*.tsx (pixel text-[Npx] classes and sub-11px text-sp-* tokens) down to zero. Type-only imports do not create runtime cycles.
The Electron preload, IPC validators, and renderer API declaration are composed from domain modules while their existing top-level entry paths remain stable. Tooling has dedicated TypeScript configs, and npm run validate is the core product static, test, web/self-host/Electron/extension build, and bundle-size contract. Docs, end-to-end, packaging, and deploy checks remain separate CI jobs.
Consequences
Section titled “Consequences”- Architecture drift fails deterministically before review.
- Cross-runtime code has a single neutral owner.
- Existing oversized modules cannot grow and lose their exception when split.
- Changes to source zones, aliases, or generated-code conventions require policy tests.
Amendment 2026-10-25
Section titled “Amendment 2026-10-25”npm run architecture:check gained these rules; the Decision above is unchanged.
- Zone bans:
electron/main->workerandcli->workerimports fail (the Worker is never bundled into Electron or the CLI). - IPC triple: every
*_IPCchannel declared inelectron/shared/channels/must be handled in Electron main and exposed by preload, and preload exports must be typed againstElectronAPI. Intentional exceptions live inipcTriplePolicyallowlists, each with a reason. - Forbidden config key:
DEV_BYPASS_AUTHin anywrangler*.json*fails. - New ratchets: direct
localStorageuse in renderer andsharedcode, and inlineipcMainhandlers that do not go throughcreateValidated*. Both may only decrease.
The executable policy lives in scripts/architecture.config.mts; its behavior is covered by tests/architecture-policy.test.ts.