Skip to content
← Back to writing

April 16, 2026

I split five monolith files and built back cleaner

Five Jira tickets sat open for months. 6,463 lines of Go in five bloated files. One PR, twenty-eight focused modules, nothing over 636 lines.

Five tickets had been open since January: through . They all said the same thing. Split this file into focused modules. The targets were apps/handlers.go at 1,429 lines, the health/ package at 2,524 lines across three files, samba_handlers.go at 853, storage/handlers.go at 975, and container/handlers.go at 682. Add it up and it is 6,463 lines of HTTP handlers sitting in five files.

git show 97a88670 --stat, the real PR #65 commit: five monolith files split into 28 focused modules across pkg/api, 26 files changed, 4,444 insertions, 4,313 deletions.

$ git show 97a88670^ -- pkg/api | head   # the before state
apps/handlers.go        1429
health/health.go         962
health/monitoring.go     988
health/routes.go         574
samba_handlers.go        853
storage/handlers.go      975
container/handlers.go    682

It all merged in one PR, #65, commit 97a88670. Twenty-six files touched, 4,444 insertions, 4,313 deletions, and not a single behavior change.

The tickets were older than some of the code in them

was filed when apps/handlers.go was around a thousand lines. By the time I opened it, it was 1,429. The v2 taxonomy work and the license-gated catalog sync had each dropped a few hundred lines into it. The ticket was not just stale. It was pointing at a file that had gotten worse since anyone wrote the ticket. The story-point estimate looked generous by the time I got there.

was the worst. The health package had two files over 900 lines and a third at 574: 962, 988, and 574 again. 2,524 lines total. The ticket asked for five modules. By the time I read it, five would not have been enough.

Sub-agents in parallel, one per ticket

I launched five agents at once. Each got its own git worktree, its own branch, and an exact list of which functions went where. The prompt had to name the modules. "Split into lifecycle, logs, stats, shell, and volumes" worked. "Split into focused modules" would have produced garbage, because the agent would have invented its own seams and I would have spent the afternoon reconciling their different seams.

Four came back fast. , the 2,524-line one, took the longest and produced nine files. The biggest, monitoring.go, landed at 636 lines because it kept the MonitoringService struct and the UI badge helpers together. Splitting those apart would have created circular imports between the new files for no real gain, so I left them in one place on purpose.

$ wc -l pkg/api/health/*.go   # the health package, after
 275 health.go
 306 handlers.go
 636 monitoring.go
 386 routes.go
 350 types.go
 329 docker.go
 282 system.go
 246 alerts.go
  55 grafana.go

The part that did not go smoothly was the coordination, not the code. Three of the five agents ended up writing into the same worktree checkout, because the isolation flag did not give each one a separate directory the way I assumed it would. Their commits stepped on each other. One agent committed files that belonged to another ticket. Two reported "nothing to commit" because their work had already been swallowed by a neighbor.

The fix was to redo three of them in series

I could have gone spelunking in the worktree bug. Untangling whose commit owned which file would have been an hour of git archaeology with cherry-picks that all looked plausible and any one of which could have dropped a function on the floor. So I threw the parallel result away for the three that collided, spawned one more agent, handed it the three remaining files, and told it to do them one at a time on a single branch. That came back with the binary building clean and all five splits applied.

The final shape, every file in the five packages after the merge:

pkg/api/apps/       handlers.go 373   templates.go 513   deployment.go 188   stacks.go 211   icons.go 171
pkg/api/health/     handlers.go 306   monitoring.go 636  routes.go 386       types.go 350    docker.go 329
                    system.go 282     alerts.go 246      grafana.go 55       health.go 275
pkg/api/samba_*.go  handlers.go 98    config.go 233      shares.go 307       users.go 237
pkg/api/storage/    handlers.go 423   snapraid.go 311    pools.go 258        cache.go 240    devices.go 304
pkg/api/container/  handlers.go 148   stats.go 177       shell.go 144        volumes.go 132
                    lifecycle.go 63   logs.go 55         cache.go 330        manager.go 704  types.go 195

The files the split actually produced all came in at 636 or under. manager.go at 704 is a pre-existing file in the container package that the PR did not touch, so it is in the listing but it is not mine to claim. The point is the files I broke up are now small enough to load one at a time.

What a split looks like up close

scanTemplates() is the function that walks the template directory and builds the app catalog. Before the split it lived at line 1,047 of apps/handlers.go, a thousand lines down a file that also did installs, stacks, notifications, and icon serving. After the split it is at line 339 of templates.go, a 513-line file whose entire job is templates. The function body did not change. Only its address did.

You can see the split in the import block, which is the part that does not lie. Here is what apps/handlers.go needed before, against what it needs after:

// BEFORE — apps/handlers.go imported everything, because it did everything
import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
	"os/exec"
	"path/filepath"
	"regexp"
	"sort"
	"strings"
	"sync"
	"time"

	"github.com/smashingtags/eightly-professional/pkg/api/container"
	"gopkg.in/yaml.v2"
)

// AFTER — what is left when the filesystem walking, yaml parsing,
// and template scanning move out to templates.go and the rest
import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"time"

	"github.com/smashingtags/eightly-professional/pkg/api/container"
)

Eight imports gone from one file. os, os/exec, path/filepath, regexp, sort, strings, sync, and the yaml parser all left with the functions that needed them. That is the real signal that a file got smaller in responsibility and not just in lines. When the import list shrinks, the file is genuinely doing less.

Zero behavior changes, and that is the whole point

The PR was 4,444 lines added and 4,313 removed, which is almost a wash, because most of it was code moving from one file to another. Same routes. Same endpoints. Same JSON shapes. The integration tests passed because no test cares which file a handler lives in, only what it returns. From outside the API, the refactor was invisible. The build came out clean.

From the inside, everything got easier. "How does the alert lifecycle work" went from scrolling 988 lines of monitoring.go to opening alerts.go at 246. "Where does the catalog scan happen" went from grepping 1,429 lines of apps/handlers.go to opening templates.go and finding scanTemplates() near the top.

Big files have a cost. Every time I opened apps/handlers.go I lost time scrolling for the one function I came for. Every time I opened monitoring.go I had to rebuild the whole mental model, because three unrelated concerns were sharing the file and I could not hold them at once. Splitting them gave me back the ability to load one concept at a time.

The wait was the damage

These tickets sat open for months because the files still worked. They were gross, not broken, and the cost of fixing them was always higher than the cost of shipping the next feature. So they got worse. apps/handlers.go grew by hundreds of lines between when was filed and when I finally did it.

That is how structural debt works. You know it is there. You tell yourself you will get to it. Every feature adds a few more lines and makes the file a little harder to work in. Then one day you cannot ship the next feature without touching the file, and the refactor is on the critical path instead of something you could have done quietly on a slow afternoon.

The thing I will actually carry forward is to name the seams in the prompt, and do not trust a parallel-isolation flag you have not verified.

mjashley.com · Eight.ly