2026-04-10 | 🧩 Breaking Up the God Module 🏗️
🎯 The Mission
🏗️ Every large codebase eventually grows a god module, that one file that does everything, knows everything, and is afraid of nothing.
📏 In our Haskell automation project, that file was RunScheduled.hs, weighing in at 906 lines with 33 imports.
🔨 Today we took the first swing at breaking it apart into focused, testable modules.
🗂️ What We Extracted
🖥️ Automation.CliArgs
🎚️ The simplest extraction: a data type and a parser for command-line arguments.
📦 The CliArgs type now derives Show and Eq, making it trivially testable.
🧪 Twelve tests cover every combination of flags, duplicate handling, trailing flags without values, and property-based verification that parsed values match inputs.
📂 Automation.VaultSync
🔄 File synchronization logic for copying blog posts between the local repo and the Obsidian vault.
📊 The pure functions like findBestMatch and showScore moved cleanly into a library module.
🪵 The interesting design choice was how to handle logging: rather than importing a logging module and creating a dependency, we accept a logger callback of type Text to IO unit.
🧪 Fourteen tests cover similarity matching, score formatting, threshold validation, and property-based checks.
⚙️ Automation.TaskRunner
🏃 The task dispatch infrastructure: running tasks sequentially with delays between them, catching exceptions, and tracking results.
⏱️ The key design insight was making the inter-task delay configurable.
🧪 Production code calls runTasks which uses the default 30-second delay.
🔬 Tests call runTasksWithDelay with zero delay, avoiding 30-second waits per task pair.
🧪 Fourteen tests verify dispatch behavior, error handling, execution order, and properties like result count always equaling input count.
🐛 Fixing Error Patterns Along the Way
⚠️ While extracting modules, we found two lingering instances of the dangerous validatedTitle and validatedRelativePath functions.
💣 These wrapped smart constructors with error, creating runtime crash points that should have been eliminated in the previous architecture phase.
✅ We replaced them with proper Either handling: call mkTitle or mkRelativePath, log a warning on Left, and skip the invalid entry using mapMaybe.
📐 Lessons Learned
⏱️ Configurable Delays for Testability
🎛️ When a module includes timing behavior, expose a configurable variant alongside the production default.
🧪 Tests use zero delay to run instantly, while production uses the real delay.
🏗️ This pattern applies broadly: anywhere you have a hard-coded constant that makes tests slow or non-deterministic, parameterize it.
🪵 Logger Callbacks Decouple IO Modules
🔌 When an extracted module needs to log but should not depend on a specific logging implementation, accept a callback parameter.
🧹 This keeps the extracted module focused on its domain and lets the caller decide how logging works.
🏗️ The pattern is simple: where you would write logMsg directly, accept a Text to IO unit parameter instead.
💥 Use throwIO Not error in Tests
🤯 We discovered that pure error calls produce bottom values that GHC 9.14 may not reliably catch with try.
✅ The fix is straightforward: use throwIO from Control.Exception to create proper IO-level exceptions.
📏 This is more explicit about intent anyway: throwIO says I am raising an exception in IO, while error says I am a program bug.
🎲 Banker’s Rounding in Haskell
🏦 Haskell’s round function uses round-half-to-even, also known as banker’s rounding.
🔢 This means round applied to 250.5 equals 250, not 251, because 250 is the nearest even integer.
🧪 When writing tests for rounding behavior, you need to account for this or your tests will fail on exact half-values.
📊 By the Numbers
📉 RunScheduled.hs shrank from 906 lines to 722 lines, a 20 percent reduction.
📦 Three new library modules were created totaling 224 lines.
🧪 Forty new tests were added, bringing the total from 1112 to 1152.
⚠️ Zero compiler warnings across all changed files.
🔧 The codebase now has 47 library modules organized by domain.
🔮 What Remains
📏 At 722 lines, RunScheduled.hs is still larger than the aspirational 100-line target.
🏗️ The remaining bulk consists of individual task runner functions like runBlogSeries, which are complex orchestration logic that is specific to this application.
🤔 Further reduction would involve either moving these to domain-specific modules or introducing a task runner framework that declaratively describes each task’s workflow.
🗺️ The architecture roadmap for this project has been steadily improving the codebase through vertical slices: domain types, pure extraction, error ADTs, data-behavior separation, and now module decomposition.
📚 Book Recommendations
📖 Similar
- Algebra-Driven Design by Sandy Maguire is relevant because it teaches how to decompose complex systems into small, composable, algebraically-lawful modules, which is exactly what we did when breaking apart the god module into focused domain modules.
- Domain Modeling Made Functional by Scott Wlaschin is relevant because it demonstrates how to organize code around domain concepts using algebraic data types and module boundaries, mirroring our approach of extracting CliArgs, VaultSync, and TaskRunner by their domain responsibilities.
↔️ Contrasting
- A Philosophy of Software Design by John Ousterhout is relevant because it argues that deep modules with simple interfaces are preferable to many shallow ones, which presents an interesting counterpoint to our decomposition approach and raises the question of when a module is too small to justify its existence.
🔗 Related
- Effective Haskell by Rebecca Skinner is relevant because it covers practical Haskell patterns including module organization, testing strategies, and exception handling, all of which we exercised today in the extraction process.