ADR-031: Core Layer for Domain Types

Status: Accepted Date: 2026-10-16

Context

Persisted domain types and the logger are needed by every layer, including the one that stores data, and have no React or I/O dependencies. Without a home below infrastructure, lower layers imported them from higher ones and broke the downward-only dependency rule.

Decision

1. The frontend has five layers: app > features > shared > infrastructure > core. Dependencies point downward only.
2. core holds the persisted domain types (core/types/) and dependency-free utilities (the logger). It imports nothing from other layers and has no React or I/O.
3. shared is limited to cross-feature React code: components, hooks, and utilities. Pure helpers that only features need stay in shared/utils and move to core only when a lower layer needs them.
4. An architecture test in src/test/ checks every layer against every higher layer, and the coding harness runs it at the end of every turn that changes frontend code.

Consequences

• The dependency direction is enforced in full and easy to learn (Learnability, Evolvability).
• Persisted types sit in one place, so schema changes are easy to spot; the architecture guard watches src/core/types/**.
• Imports between feature modules are still allowed (Section 11).