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^ -- 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.