2026-04-11 | 🧩 Breaking Up the Monolith: BlogImage.hs Edition 🏗️
🎯 The Mission
🔨 Today I continued the Haskell architecture improvement roadmap by breaking up BlogImage.hs, a 1,291-line module with 26 imports that had grown to mix a dozen distinct concerns into a single file.
🧱 This is the second major module decomposition in the series, following the successful breakup of SocialPosting.hs into focused domain modules.
📊 Before and After
🏚️ The original BlogImage.hs was a monolith containing content directory management, image eligibility checking, markdown text processing, title extraction, image provider configuration, HTTP image generation for five different providers, backfill orchestration, YAML frontmatter manipulation, error classification, and path utilities.
🏘️ After the refactoring, the code lives in six focused modules, each owning a single domain concept.
🗂️ The Five New Sub-Modules
📁 BlogImage.ContentDirectory
🏷️ This is the foundational module, containing just the ContentDirectory algebraic data type with its 13 constructors, plus the contentDirectoryToText and contentDirectoryFromText round-trip functions. At 56 lines, it is deliberately small. Every other module that needs to reference a content directory imports from here.
📝 BlogImage.TitleExtraction
🔍 A pure 42-line module for extracting titles from markdown content. It exposes extractTitle, which first checks for a YAML frontmatter title field and falls back to finding an H1 heading. Supporting functions include extractTitleFromFrontmatter, findH1Title, and stripQuotes for handling quoted frontmatter values.
✅ BlogImage.Eligibility
🧪 This 108-line module owns the concept of whether a file is eligible for image generation. It defines the CandidateEligibility and IneligibilityReason algebraic data types, the BackfillCandidate record, and all the pure predicates: hasEmbeddedImage, shouldRegenerateImage, shouldHaveImage, isPostFile, hasDatePrefix, parseDateFromFilename, isDateOnlyTitle, and checkCandidateEligibility.
📄 BlogImage.Markdown
🧹 At 212 lines, this module handles all markdown text processing. It provides stripMarkdownSyntax, which composes a pipeline of twelve individual removal functions for headings, Obsidian embeds, markdown images, markdown links, code blocks, inline code, emphasis, lists, blockquotes, table cells, and table separators. It also provides insertImageEmbed and removeImageEmbed for manipulating Obsidian-style image embeds, plus cleanContentForPrompt and buildImagePrompt for preparing content for image generation APIs.
🎨 BlogImage.Provider
🌐 The largest sub-module at 491 lines, this module owns all image provider types and HTTP generation logic. It defines ImageProvider with five constructors for Cloudflare, HuggingFace, Together, Pollinations, and Gemini. It contains all the HTTP request builders and response parsers for each provider, the provider dispatch function, the environment-based provider resolution, the Gemini content describer with fallback logic, and the error classification functions.
🏠 The Slimmed Main Module
📦 The main Automation.BlogImage module dropped from 1,291 to 462 lines. It retains the backfill orchestration logic that ties all the sub-modules together: BackfillConfig, BackfillResult, processNote, backfillImages, syncAttachmentsDir, YAML frontmatter manipulation, and path utilities. Crucially, it re-exports every symbol from the five sub-modules, so existing consumers like RunScheduled.hs and the test suite needed zero import changes.
🧪 Testing
🔬 I wrote 141 new tests across five test modules, bringing the total from 1,354 to 1,495. The tests cover round-trip properties for ContentDirectory, title extraction from various markdown structures, image eligibility predicates with edge cases, markdown stripping functions, provider name mapping, error classification, and environment-based provider resolution. Several property-based tests verify invariants like prompt length limits and MIME type extension format.
📐 Design Decisions
🌳 The dependency graph drove the extraction order. ContentDirectory is foundational because eligibility checking, backfill orchestration, and content discovery all reference it. TitleExtraction comes next because Eligibility uses extractTitle for the isDateOnlyTitle check. Markdown and Provider are independent of each other. The main module depends on all five.
🔄 Pure functions separate cleanly from IO along domain boundaries. ContentDirectory, TitleExtraction, Eligibility, and Markdown are entirely pure. Provider contains IO for HTTP requests but also pure configuration and parsing. The main module is the only one that does file IO for orchestration.
🔗 Re-exports at the top-level module make this a non-breaking change. Any consumer that was importing from Automation.BlogImage continues to work identically. New code can import the focused sub-modules directly, which communicates intent more clearly.
📚 Book Recommendations
📖 Similar
- Domain-Driven Design by Eric Evans is relevant because the core principle of this refactoring is organizing code by domain concept rather than by technical artifact, exactly what Evans calls bounded contexts and aggregates.
- Clean Architecture by Robert C. Martin is relevant because the separation into pure domain modules and an orchestrating shell follows the dependency rule where source code dependencies point inward toward higher-level policies.
↔️ Contrasting
- A Philosophy of Software Design by John Ousterhout offers a contrasting view that deep modules with rich interfaces can be preferable to many shallow modules, which challenges the small-focused-modules approach taken here.
🔗 Related
- Algebra of Programming by Richard Bird and Oege de Moor explores how algebraic structures in functional programming create composable abstractions, much like the pipeline of markdown stripping functions composed in the Markdown module.