r/golang · u/SatyrCodeJul 28, 2026, 6:10 PM

How do you structure medium-sized Go services to avoid a giant “services” package?

I’m building a few medium-sized services in Go and trying to keep things clean as they grow.

Right now the common pattern I see is a huge services or handlers package that slowly turns into god objects.

For those of you running Go in production, what’s worked best for you in terms of layering and package structure?

Do you stick to something like hex/clean architecture, or a more pragmatic layout?

Curious to hear how you balance simplicity and long-term maintainability - especially for services that are too big to be “just a single main.go”, but not large enough to justify a massive microservices setup.

3931

Comments

u/introvertnudist3Jul 28, 2026, 6:39 PM
I'm not sure if this is the kind of Go app you mean, but I have a social networking app which is definitely a medium-sized project (with 51 database tables and at least as many controllers, with typically a full CRUD set of controllers for each and then some). I have a stripped back, open source version of the app here to take a look: https://github.com/cuvou/gosocial To keep the code maintainable, especially for the controllers (to group them into logical folders by feature, so when I wanna find "where was the edit controller for photos?" it's under "pkg/controller/photos") I have the app split into a tree of subpackages.
- u/SatyrCode1Jul 28, 2026, 6:43 PM
  Thanks, this is super helpful, especially the context of a medium-sized social app. I like the idea of grouping controllers by feature and then splitting into subpackages under pkg/ – that sounds much more navigable than a flat “controllers” dump. I’ll take a look at the repo, thanks for sharing. In your experience, did you ever feel the need to introduce a more explicit “domain” or “use case” layer on top of that, or did grouping by feature + clear controllers stay enough as the project grew?
  - u/introvertnudist1Jul 28, 2026, 8:00 PM
u/Vegetable-Scale-260431Jul 28, 2026, 6:40 PM
Package by feature, not by layer. Instead of one big services/ package, give each domain its own package (users/, billing/, whatever) and let it own its handlers, storage and logic. Handlers stay thin: decode, validate, call, encode. main.go just wires the dependencies together. The trap is splitting by type (models/, handlers/, services/) — that structure is exactly what produces the god package you are trying to avoid. Some duplication between feature packages is cheaper than coupling everything to shared abstractions before you know where the real seams are.
- u/SatyrCode0Jul 28, 2026, 6:43 PM
  That “package by feature, not by layer” point resonates a lot. I’ve definitely seen the trap of models/handlers/services where everything slowly leaks into the “services” blob. Do you usually keep cross-cutting concerns (auth, logging, metrics, etc.) in separate shared packages, or do you also try to keep those as close to the feature packages as possible? Curious how you avoid turning shared code into another god package.
  - u/retneh1Jul 28, 2026, 6:46 PM
- u/Golle3Jul 28, 2026, 8:02 PM
  You are comparing technical partitioning and domain partitioning in the "layered architecture". Both are valid. You are recommending the domain partition way. It is good to know that both exist and what their benefits and drawbacks are. I am not arguing against you, I just wanted to add more context.
u/sigmoia61Jul 28, 2026, 6:48 PM
This comes up so often that I feel like link spamming is okay: https://rednafi.com/go/app-structure/
- u/dumindunuwan1Jul 28, 2026, 7:43 PM
  you can generate Go generics based repos now, ex bob, gorm cli. The issue is not to duplicate/ avoid circular imports of models.
- u/7heWafer7Jul 28, 2026, 10:40 PM
  Oh wow this is like ports & adapters or hex arch tuned specifically to Go idioms and without all the baggage, structural implications, etc. that aren't actually necessary. Thanks for sharing this.
- u/SatyrCode2Jul 29, 2026, 1:17 AM
  App structure post is solid, thanks for linking it good to see ports & adapters explained with actual Go code.
- u/ConsoleTVs3Jul 29, 2026, 8:48 AM
  The triky part here is pretty much how you deal with circular dependencies. It's common in complex apps that things are shared. eg. a service 1 uses a service 2, and service 2 might use service 1. Even more concerning when using things like DB models if you are expected to provide relationships, they are always bidirectional.
  - u/sigmoia3Jul 29, 2026, 9:30 AM1 reply
- u/8run02Jul 29, 2026, 10:41 AM
  I'm just not a fan of the models package - do you have one order struct with all the json tags and db tags, do you have all the representations of the order in the struct. Personally I prefer the "models" to live where they are used re: models with json tags live beside the handler, a internal representation and then the repository version. Horses for courses though, i have found models with json, db, yaml and custom tags all on one model struct with fields that are only referenced at one level of the call structure re: handler vs repository.
  - u/sigmoia1Jul 29, 2026, 11:17 AM1 reply
- u/Academic-Side-27561Aug 2, 2026, 3:19 AM
  This is an amazing article.
u/SatyrCode1Jul 28, 2026, 7:27 PM
Really appreciate all the examples in this thread especially the “package by feature” approaches and the links to real repos. For context, what I’ve been doing so far on my side is roughly: cmd/ for entry points internal/http (or internal/api) for handlers and routing internal/usecase for application logic internal/domain for core models and domain rules internal/infrastructure for DB, queues, external services, etc. It’s worked reasonably well, but over time I’ve noticed the “usecase” layer wanting to split by feature anyway, which is why I asked the question. This thread is giving me a lot of ideas on how to keep things feature-oriented without losing clear boundaries.
- u/dumindunuwan0Jul 29, 2026, 6:16 AM
  
  internal/http (or internal/api) for handlers and routing
  
  internal/usecase for application logic
  
  internal/domain for core models and domain rules
  
  internal/infrastructure for DB, queues, external services, etc
  
  Move /internal/usecase -> just /app.
  
  In old languages dependency injection is a thing. Go makes things simple. Unlearn about technical layerings like DDD/ Clean archetecture folders. Think allocations or how you handle memory. Group related functionality uses same dependencies together. Start think how to not to duplicate memory.Avoid duplicate code is secondary. In Go what you write is exactly how it runs in memory. Do not add too much runtime layers to you app.
  
  Simply,
  
  start dependencies like DB, queue from main go -> panic immediately if anything failing. Start router (router can be in /app/router)
  
  Create a func New(*dependenciesAsPointers) on each /app/{usecase} folder and call it from router. Each usecase may have a handler.go, model.go, repo.go, ... . To avoid circular dependency move, models outside.
  
  Don't maintain middle types. Directly stream from form to model, model to response. Use new format attributes/ UnmarshalJSON directly on types.
  
  Go std is battery included. Don't start with frameworks (unless GRPC/ ConnectRPC) or code generators. You don't need lot of 3rd party dependencies in Go. Don't choose huge/ "Swiss army knife kind libraries" on Go. Keep everything decouple and simpler. Don't start with interfaces/ add interfaces when it needed (for tests).
  - u/SatyrCode1Jul 29, 2026, 7:22 AM
u/dumindunuwan1Jul 28, 2026, 7:29 PM
Ex. https://github.com/learning-cloud-native-go/myapp
- u/SatyrCode1Jul 28, 2026, 7:32 PM
  Nice, thanks for the link this is exactly the kind of repo I was hoping people would share. I’ll go through the structure in myapp as well, it’s helpful to see how different teams layout their packages in real cloud-native services
u/Healthy_Landscape4171Jul 29, 2026, 7:00 AM
Package by feature is right, and where you put the interfaces decides whether it holds. Split users/ and billing/ and within a week one needs the other, then both need each other, and you have an import cycle. The Go review guide answers it: the interface belongs in the package that uses it, not the one that implements it. So billing declares the small lookup it needs, and users just returns its concrete type and satisfies it without importing anything. No cycle, and no shared interfaces package waiting to become the next god object.
u/sazzer1Jul 29, 2026, 7:01 AM
I personally always go for the Modular Monolith pattern, and try to use DDD concepts and hexagonal architecture structure. (Yes, it may be overkill for Go, but it works for me)

So, for example, it might look like:

- service - service.go - platform - httpserver - httpserver.go - modules - posts - module.go - internal - adapters - inbound - http - routes.go - get.go - outbound - database - database.go - application - postsQueryService.go - domain - post.go - repository.go

What we have here is:

The platform/httpserver module contains everything to do with building the HTTP server. This is constructed by passing in a set of routes in some appropriate form. There may also be other platform concepts too - e.g. MQ, database, etc. This is just an abstraction from the underlying technology to make things easier to work with.

The modules/posts module contains everything to do with the Posts bounded context, and only the Posts bounded context. If there's another bounded context added then it becomes another module adjacent to this one.

The adapters/inbound/http module contains all of the HTTP handlers for that bounded context. There can potentially be other adapters/inbound modules too if needed.

The adapters/outbound module contains all of the ways that this bounded context can talk to anything outside of it. That can included calls to remote services, external infrastructure, or to other modules in the same application.

The module.go file contains a Module struct and a New() method to construct the entire module. This will accept any shared config/infrastructure/etc that's needed - e.g. an HTTP client instance - and otherwise is entirely self-contained.

I personally find this makes it really easy to find exactly what you want really easily, and it keeps each of the modules small and self-contained. Especially since VSCode will do partial matching well, so I can search for "posts/inbound/get" and it will take me directly to that file.

The biggest structural problem I find is that you need to be careful with package names. For example, if you have a bounded context that's backed by a remote service you could easily end up with adapters/inbound/http and adapters/outbound/http, and suddenly it's a bit more awkward to construct the module since you need to rename the imports. That should only happen inside the module.go file though and not very often.
- u/dumindunuwan2Jul 29, 2026, 7:44 AM
  If you need to add more module, you can use Go workspaces That is most idiomatic way to handle multi-module env.
  - u/sazzer1Jul 29, 2026, 9:58 AM
u/Used_Indication_5361Jul 29, 2026, 10:51 AM
I’m surprised nobody’s posted the link to the Organizing a Go module documentation on the official website. It gives you 7 suggestions based on the goal of your project. I’d ignore every other link ITT and try one of these options first.
- u/SatyrCode1Jul 29, 2026, 10:54 AM
  Good catch, I’d missed that doc thanks for the link. I’ll review the suggested layouts on go.dev/doc/modules/layout before overthinking my own folder structure too much.
u/titpetric1Jul 29, 2026, 2:56 PM
See https://github.com/titpetric/platform-app ; a structural linter documents the conventions, each service is a top level dir, and you can create / bind services together, usually by using the storage package in the request and coupling against the user module for auth. Alternatively circa 2018, https://github.com/titpetric/microservice. Less flexible around go.mod, while the platform-app repo could have submodules. The difference is just an inverted folder structure.
u/khalon231Jul 29, 2026, 4:15 PM
I stopped having a giant services package and put each feature in its own package: billing, users, notify. Each one exports a small interface for what others need, and main (or a thin app package) wires the concrete types.

Handlers stay dumb: decode request, call one method, encode response. Shared DB access lives behind repositories owned by the feature, not a global store. When two features need the same thing I extract a third package with a boring name (clock, idgen, mailer) instead of dumping helpers into pkg/utils.
u/AdPrestigious20951Jul 29, 2026, 5:35 PM
The god-object thing usually comes from splitting by technical role (handlers/, services/, repos/) instead of by domain. Every feature ends up reaching into all three, so nothing has a clear owner and the middle layer becomes a dumping ground. What's held up for us: one package per business concept (order, billing, user), each owning its handlers, logic, and storage. internal/order, internal/billing, and so on. The package name is a noun, not a verb. If you can't name it without "service" or "manager" in it, it's probably two things. Skip full hex until you feel the pain. Most medium services only need a couple of habits: define interfaces where they're consumed, not where they're implemented, and keep them to the 2-3 methods the caller actually uses. Storage returns domain types, not DB rows. Wire dependencies in main and pass them down, no global container. The rule that helped most: no feature package imports a sibling feature package directly. If order needs billing, it goes through a small interface that order defines. Keeps the graph a DAG and makes god-object drift annoying to do by hand, which is sort of the point. Clean/hex is good vocabulary to steal from, but treating it as law on a service this size mostly buys you boilerplate.
u/mstgnz1Jul 29, 2026, 6:55 PM
Pragmatic layering, not full hex. cmd/ for wiring, internal/{domain,repository,service,handler}, pkg/ for standalone utils. The rule that actually prevents the god package: domain holds types and interfaces with zero external imports, service depends on those interfaces, repository implements them, and main is the only place concrete meets interface. One service per business area, not one per layer. Do that and the giant "services" package never forms.
u/Elara_Schaefer1Aug 1, 2026, 8:55 AM
The strict import cycle prohibition in Go is genuinely one of its best architectural features. It forces you to make dependency direction explicit early. The pattern that works best for medium services: domain packages are leaf nodes (zero external imports, only stdlib), and everything flows inward toward them. HTTP handlers depend on domain, repositories implement domain interfaces, domain never knows about HTTP or DB. The moment a domain package imports anything outside itself, you have the wrong abstraction. For cross-cutting concerns like auth middleware, keep them in the transport layer (http package) and inject user identity into the context rather than having the domain depend on an auth package.