architecture-paradigm-functional-core

# The Functional Core, Imperative Shell Paradigm ## When To Use - Separating pure business logic from side effects - Improving testability through immutable domain models ## When NOT To Use - Performance-critical hot paths where immutability overhead matters - Purely imperative codebases with no plans to adopt functional patterns ## When to Employ This Paradigm - When business logic is entangled with I/O operations (e.g., database calls, HTTP requests), making tests brittle and slow. - When significant development time is spent rewriting adapters or dealing with framework churn. - When you require a suite of fast, deterministic unit tests that operate on plain data, complemented by a thin integration testing layer. ## Adoption Steps 1. **Inventory Side Effects**: Create a map of all side effects in the system, such as database writes, external API calls, UI events, and filesystem access. Explicitly assign these responsibilities to the "shell." 2. **Model the Core Logic**: Represent business rules and policies as pure functions. These functions should take domain data as input and return decisions or commands as output, avoiding shared mutable state. 3. **Design the Command Schema**: Define a small, explicit set of command objects that the core can return and the shell can interpret (e.g., `PersistOrder`, `PublishEvent`, `NotifyUser`). 4. **Refactor Incrementally**: Begin with high-churn or critical modules. Wrap legacy imperative code behind adapters while progressivel...