September 10, 2025
6,345 lines in one file: the refactor that saved the project
My main server file was 6,345 lines. 212% past the emergency refactor threshold. I broke it into 8 modules across two days. 56 story points. Zero breaking changes.
The file

It was the Go backend for HomelabARR, one file, and it had started honest. A few hundred lines of HTTP handlers, some Docker integration, a health check. Then I kept adding. Storage management. ZFS operations. SnapRAID. MergerFS pooling. Cache mover logic. SSE events. VPN config. Traefik, Authelia, container orchestration.
Every new feature went into the same file because that was faster than making a new one. Every function sat next to every other function because that was easier than thinking about where it belonged. It worked, for a while.
Then it was 6,345 lines. The Confluence summary I wrote when the epic closed records the number flatly: "Before: 6,345-line monolithic server." That is past the point where the usual rules of thumb (refactor around 1,000, emergency around 2,000) stop being advice and start being a diagnosis.
The pain
Opening the file felt like dread. Ctrl+F was my primary development tool. Search a function name, scroll past forty others to get to it, forget what I came for, start again. Features that should have taken minutes took an afternoon because I could not hold the whole thing in my head.
Debugging was archaeological. A bug could be anywhere in those lines, and fixing one thing broke three others because everything shared state and nothing had a boundary. So I was afraid to touch it, which meant I was afraid to improve it, which meant the product stopped moving.
Context-switching between Docker code and ZFS code and cache code in the same scroll burns energy I do not have to spare. The file was eight different problems interleaved into one.
The extraction
The work landed across the back half of Sprint 5 and into the epic that closed it. The storage piece went first as its own story, , the Storage Management API extraction, and it came out the far side at 74.6% test coverage. That was September 6. The full transformation ran under epic , eight stories, one per domain:
- : Container Management
- : Storage Management
- : Health and Monitoring
- : VPN and Authentication
- : ZFS Management
- : File Sharing
- : Core API and App Management
- : Final cleanup and integration testing
The shape they were extracted into is the pkg/api/ tree, one package per domain. This is the structure as it sat at the first commit after the split:
pkg/api/
health/ health.go, monitoring.go, routes.go, handlers.go
container/ handlers.go, manager.go, cache.go, types.go
storage/ handlers.go, devices.go, cache.go
zfs/ handlers.go, manager.go, types.go
vpn/ config.go, proxy.go, handlers.go
events/ manager.go, sse.go, handlers.go, types.go
cache/ manager.go, backends.go, strategies.go, metrics.go, types.go
server.go the wiring: one place that registers every module's routes
Eight domains, each one a thing I can open without seeing any of the other seven. The single endpoint dispatch that used to be buried in the monolith is now a flat, readable route table in pkg/api/server.go:
// pkg/api/server.go — setupRoutes, the modular wiring
func (s *Server) setupRoutes() {
s.router.GET("/health", s.healthCheck)
v1 := s.router.Group("/api/v1")
{
stacks := v1.Group("/stacks")
containers := v1.Group("/containers")
{
containers.GET("", s.listContainers)
containers.GET("/:id", s.getContainer)
containers.POST("/:id/start", s.startContainer)
containers.POST("/:id/stop", s.stopContainer)
containers.POST("/:id/restart", s.restartContainer)
containers.GET("/:id/logs", s.getContainerLogs)
}
state := v1.Group("/state")
validation := v1.Group("/validation")
operations := v1.Group("/operations")
}
}
68 endpoints ended up distributed across those eight domains. Zero breaking changes. I verified it the only way that counts: a real app install through the new path, a netdata container deployed end to end, before I called the epic done.
One honest correction to my own bragging. The clean target I had in my head was "every module under 500 lines." The real files did not land that small. pkg/api/health/health.go came out near 900 lines, storage handlers around 800. Smaller than 6,345 by an order of magnitude, and each one a single domain you can reason about, but not the tidy 200-line modules I pictured. What I bought was the boundaries rather than a smaller line count.
Story points in a day
The epic was 56 story points, delivered over two days. In a previous life that is multiple sprints for a full team; I did it with Claude as the pair.
I am no 50x developer. Refactoring is just the dream task for this kind of work. The requirements are perfectly defined, the code already exists, you are moving it. The acceptance criteria write themselves, every existing endpoint must still answer. The scope is bounded, you are not adding features, you are sorting them, and an AI is genuinely good at mechanical reorganization.
My job was deciding what goes where. Claude's job was moving it correctly. That split works for refactoring and it does not work for novel feature design, where the hard part is the deciding and there is no existing answer to copy. Knowing which kind of work you are doing is most of the trick.
After
I can open the codebase now and feel relief instead of dread. I can work on storage without scrolling past Docker, change the cache layer without seeing ZFS. Each module fits in my head, which means I spend my time writing code instead of hunting for it.
The modularization did not make me a better developer. It made the codebase something a person can work in. Six weeks ago I could not write code at all. This was the proof, to me, that the trajectory was real.