Skip to content

ADR 0028 — TypeScript Architecture Boundaries

Accepted · 2026-07-16

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.

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.

  • 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.

npm run architecture:check gained these rules; the Decision above is unchanged.

  • Zone bans: electron/main -> worker and cli -> worker imports fail (the Worker is never bundled into Electron or the CLI).
  • IPC triple: every *_IPC channel declared in electron/shared/channels/ must be handled in Electron main and exposed by preload, and preload exports must be typed against ElectronAPI. Intentional exceptions live in ipcTriplePolicy allowlists, each with a reason.
  • Forbidden config key: DEV_BYPASS_AUTH in any wrangler*.json* fails.
  • New ratchets: direct localStorage use in renderer and shared code, and inline ipcMain handlers that do not go through createValidated*. Both may only decrease.

The executable policy lives in scripts/architecture.config.mts; its behavior is covered by tests/architecture-policy.test.ts.