Architecture Paradigm Functional Core
Refactor entangled business logic and I/O using Functional Core, Imperative Shell so unit tests run fast and adapters stay thin.
Overview
Architecture Paradigm Functional Core is an agent skill most often used in Build (also Ship review, Ship testing) that separates pure business logic from I/O using Functional Core, Imperative Shell.
Install
npx skills add https://github.com/athola/claude-night-market --skill architecture-paradigm-functional-coreWhat is this skill?
- Functional Core, Imperative Shell paradigm with explicit when-to-use and when-not-to-use gates
- Adoption steps start with inventorying side effects: DB, APIs, UI events, filesystem
- Aimed at fast deterministic unit tests on plain data plus a thin integration test layer
- Tagged intermediate complexity with architecture, testability, and ADR support usage patterns
- Use when tests are slow and brittle because logic is mixed with I/O—not for hot-path immutability overhead
- Documented estimated_tokens: 1200 in skill metadata
- Explicit when-not-to-use cases include performance-critical hot paths and purely imperative codebases
Adoption & trust: 1 installs on skills.sh; 304 GitHub stars; 3/3 security scanners passed (skills.sh audits); trending (+100% hot-view momentum).
What problem does it solve?
Your domain rules live inside framework and database calls, so every change needs slow, brittle tests and endless adapter rewrites.
Who is it for?
Indie backend builders refactoring services where correctness rules should be testable without hitting real databases on every case.
Skip if: Codebases refusing any functional structuring, or subsystems where immutability overhead on a proven hot path is unacceptable.
When should I use this skill?
Business logic is entangled with I/O or unit tests are slow and brittle—use when separating pure logic from the imperative shell.
What do I get? / Deliverables
You get a repeatable refactor plan that isolates immutable core logic behind a thin imperative shell, enabling fast unit tests and clearer integration boundaries.
- Side-effect inventory and boundary plan for core vs shell
- Refactoring steps aligned to FC/IS with ADR-friendly rationale
- Test layout recommendation: deterministic core units plus thin integration layer
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Structural separation of domain logic from side effects is canonical backend architecture work while you are actively building or refactoring services. The paradigm targets server-side business rules, database calls, and HTTP boundaries—the backend shelf—not distribution or analytics.
Where it fits
Map database and HTTP side effects then peel payment rules into a pure core module.
Check a PR does not smuggle new I/O into functions that should remain deterministic.
Replace broad integration-only coverage with fast core unit tests plus shell integration tests.
Apply the inventory step when a new third-party API adapter threatens to spread across domain code.
How it compares
Architectural refactoring playbook—not a linter rule pack or a one-shot code generator for a single framework.
Common Questions / FAQ
Who is architecture-paradigm-functional-core for?
Developers and small teams whose business logic is mixed with I/O and who want agent-guided FC/IS boundaries and test strategy.
When should I use architecture-paradigm-functional-core?
In Build while extracting cores from handlers, in Ship review before merging a large refactor, and in Ship testing when you redesign the unit versus integration test pyramid.
Is architecture-paradigm-functional-core safe to install?
It is documentation and refactoring guidance only; review the Security Audits panel on this page and still run your normal CI and review on any agent-produced diffs.
SKILL.md
READMESKILL.md - 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 progressively extracting pure calculations into the functional core. 5. **Enforce Boundaries**: Use code reviews and automated architecture tests to validate a strict separation. The shell should only handle orchestration, sequencing, and retries, while the core should never call directly into frameworks or I/O libraries. ## Key Deliverables - An Architecture Decision Record (ADR) detailing why this pattern was chosen, which modules are affected, and the scope of the migration. - A suite of unit tests for the core with high (>90%) and deterministic code coverage. Where applicable, use property-based or fixture-based testing to cover a wide range of inputs. - A suite of contract and integration tests for the shell that verify correct command interpretation, retry logic, and telemetry. - A set of rollout metrics (e.g., deployment lead time, incident rate in the shell layer) to demonstrate the value of the architectural change. ## Risks & Mitigations - **Logic Drifting Between Core and Shell**: - **Mitigation**: It's common for business logic to accidentally be duplicated or placed in the shell. Enforce a "core owns all decisions" checklist during code reviews to prevent this. - **Mismatch with Frameworks**: - **Mitigation**: The imperative shell may still need to interact with framework-specific lifecycle hooks. Before committing to a large rewrite, build small proof-of-concept adapters to validate the integration strategy. - **Team Unfamiliarity with the Pattern**: - **Mitigation**: Introduce the pattern using pair programming and internal "brown-bag" learning sessions. Document common anti-patterns that are discovered during the pilot phase to guide future development. ## Concrete Components These vocabulary items name the concrete tools and abstractions that show up when the paradigm is implemented. They are not required dependencies and they are not part of the skill's ``tools:`` frontm