2026-04-07 | 🏛️ Toward a Haskell Architecture That Prevents Mistakes 🧱
🔍 The Problem
🏗️ This Haskell codebase was born from a TypeScript port, and it shows.
🧬 TypeScript and Haskell share some DNA in their love of types, but they diverge sharply when it comes to effects. 📜 In TypeScript, every function can silently perform IO, read the clock, or throw an exception. 🎭 The type system simply doesn’t distinguish between pure computation and side effects. 🔄 When you port TypeScript code to Haskell line by line, you carry those assumptions with you, and you end up with Haskell that has IO sprinkled everywhere, even where it doesn’t belong.
🏗️ What We Found
🔬 A thorough architectural review revealed several patterns inherited from the TypeScript origin.
🌊 IO Everywhere
📊 The most pervasive issue is functions that live in IO unnecessarily. 🕐 A function that checks whether a reflection is eligible for social media posting was reading the system clock internally, even though its entire logic is just date comparison. 🧮 That date comparison is pure math, and pure math doesn’t need IO.
📝 Text for Everything
🏷️ Domain concepts like URLs, titles, dates, and file paths are all represented as plain Text. 🔀 This means the compiler cannot prevent you from passing a title where a URL is expected, or mixing up a vault path with a repository path. ⚠️ These are exactly the kinds of mistakes that slip through code review and show up as subtle bugs in production.
🏰 The God Module
📏 The main orchestrator, RunScheduled, weighs in at over nine hundred lines with thirty-three module imports. 🕸️ It acts as a giant switchboard that knows about every feature. 💥 Any change to any feature risks touching this central file, which increases the chance of accidental breakage.
🎯 The Architecture We Want
🧅 The target architecture follows a pattern called Functional Core, Imperative Shell.
🧊 The idea is simple but powerful. 🧮 Keep your domain logic pure, meaning no side effects, no reading files, no calling APIs, no checking the clock. 🐚 Then wrap that pure logic in a thin shell of IO at the very edges of your program. 🧪 Pure functions are trivially testable because they always produce the same output for the same input. 🔬 You can write hundreds of deterministic test cases without needing temporary directories, mock servers, or careful timing.
🔧 The First Step
🎯 We chose the simplest possible demonstration of this principle. 📋 The function isReflectionEligibleForPosting previously took a date as a raw Text string and a posting hour as a bare Int, performed IO to get the current time, then did string comparisons on formatted dates to determine eligibility.
✨ After the refactoring, the function accepts proper domain types from the standard time library. 📅 The reflection date is a Day, representing a calendar date that supports real date arithmetic like predecessor and comparison. 🕐 The posting cutoff is a TimeOfDay, which represents a time of day that the compiler prevents from being confused with an arbitrary integer. ⏰ The current time comes in as a UTCTime parameter, making the function pure with no IO. 📍 The callers, which already live in IO because they do file system operations, simply pass in the current time they already have access to.
🧪 The test improvement tells the story clearly. 🔢 We went from one test that depended on the system clock, which meant it could only test old dates safely, to six deterministic tests covering yesterday before the posting cutoff, yesterday after the posting cutoff, yesterday at exactly the posting cutoff, today which is never eligible, two days ago which is always eligible, and the original very old date case. 🎯 Every test uses a specific constructed time value, so the tests will give the same result whether you run them at midnight or noon, in January or July.
📋 The Roadmap Ahead
🗺️ We documented a six-phase improvement plan in the specs directory, designed so each phase is a vertical slice delivering types, logic, tests, and documentation together.
🌿 Phase one continues extracting pure cores from IO functions across the codebase, targeting six more candidates including date calculation, file discovery, and eligibility checking. 🧪 Each extraction comes with property-based and unit tests.
🏷️ Phase two introduces domain-specific newtypes like Url, Title, and RelativePath so the compiler can catch misuse at build time. 🔬 Each type is delivered with smart constructors, property tests, and migration of existing call sites.
📦 Phase three consolidates the scattered Manager, repo root, and vault directory parameters into a single AppContext record. ✅ Tests for context construction and validation come along with the module.
⚠️ Phase four replaces silent failures and bare Text errors with domain-specific error types that preserve context. 🧪 Each error migration is delivered with test coverage for the failure paths.
🧩 Phase five separates data from behavior in the image provider configuration, removing IO callbacks embedded in data structures. ✅ Tests for provider configuration and selection logic are included.
✂️ Phase six breaks up the nine hundred line orchestrator into focused modules. 🧪 Each extracted module gets its own test suite.
🏛️ Why This Matters
🛡️ Each of these changes makes it harder to introduce bugs accidentally. 🧱 When functions are pure, you cannot forget to handle a side effect because there are none. 🏷️ When domain types are distinct, you cannot pass a URL where a title is expected because the compiler will reject it. 📦 When modules are small and focused, a change to image generation cannot accidentally break social posting because they live in separate, independent modules.
🌱 The beauty of this approach is that it is incremental. 🔄 Every intermediate state builds, passes all tests, and is a better codebase than the one before it. ⏳ No big bang refactoring, no risky multi-week branches, just steady progress toward a codebase where the type system catches the mistakes before they reach production.
📚 Book Recommendations
📖 Similar
- Algebra of Programming by Richard Bird and Oege de Moor formalizes computation as algebraic structures. 🔗 This is the theoretical foundation for the functional core pattern we are moving toward.
- Domain Modeling Made Functional by Scott Wlaschin demonstrates how strong type systems encode business rules and prevent invalid states. 🏷️ This directly parallels our goal of using newtypes and ADTs to prevent domain value misuse.
↔️ Contrasting
- Clean Architecture by Robert C. Martin approaches modularity and dependency management from an object-oriented angle. 🔄 Comparing its principles with functional architecture reveals how different paradigms solve the same problems.
🔗 Related
- Functional Design and Architecture by Alexander Granin is the definitive guide to structuring real-world Haskell applications. 🎯 It covers the ReaderT pattern, effect systems, and service handles that our roadmap targets.
- Real World Haskell by Bryan O’Sullivan, Don Stewart, and John Goerzen covers practical patterns for IO management and testing. 🧪 These patterns directly inform our incremental improvement strategy.