DEV Community: Francis Awuor

Where Does This Code Go? Layers in Go

Francis Awuor — Wed, 18 Mar 2026 19:20:41 +0000

Until not too long ago, when I wanted to change one thing in my code, I'd end up having to touch a bunch of other things. Or I'd be staring at a function trying to figure out why it's doing three completely different jobs.

Turns out there's a name for what I was doing wrong, and a pattern that fixes it.

This article is essentially what I wish someone had shown me earlier. We're going to walk through a way of organising your Go code into three layers: Service, Repository, and Delivery…

So that each part of your code has one job, and changing one thing doesn't ripple into everything else.

I'll be using two of my own projects as examples: a netcat-based group chat app, and a URL shortener.

What is Separation of Concerns?

Before we get into the layers, it's worth naming the idea behind all of this.

Separation of concerns basically means: each part of your code should have one clear job, and should know as little as possible about everything else. That's it.

The reason this matters is that when one part of your code knows too much about another part, they get tangled. And tangled code is code that's hard to change. You touch one thing and break another.

The three-layer pattern we're about to walk through is one concrete way to apply this idea in a Go backend. Each layer gets one job. Each layer talks to the next one through a clean boundary. That boundary is what keeps things from bleeding into each other.

The Three Layers

Here's the model we need to internalize before we get into the details:

Service - this is what your app does. Your business rules. The reason the app exists. If someone asked "what does this app actually do?", the answer lives here.

Repository - this is where your app stores and retrieves data. It doesn't care about business rules. It just reads and writes.

Delivery - this is how users interact with your app. An HTTP server, a CLI, a netcat listener. It receives input, calls the service, and returns a response. It's the outermost layer, the plumbing that connects your app to the outside world.

Each layer only talks to the one below it. Delivery calls the service. The service calls the repository. None of them reach past their neighbour, and that constraint is exactly what keeps your code clean.

We'll start with the most important one: the service layer.

The Service Layer

The service layer is the core of your app. It's where your business rules live (the logic that makes your app what it is, not just plumbing or storage.)

A good way to think about it: if someone asked "what does this app actually do?", the service layer is where you'd point them.

Here's what my group chat service handles:

Registering clients when they connect
Creating groups and letting clients join them
Broadcasting messages to everyone in a group
Unregistering clients when they disconnect
Keeping a chat history per group, and sending it to new clients when they join
Notifying everyone when someone joins or leaves

All of that is business logic. Those are decisions the app makes. Not the database, not the HTTP handler.

Here's the public surface of that service:

func (s *Service) Register(client *Client) error
func (s *Service) Unregister(client *Client)
func (s *Service) Broadcast(sender *Client, content string)
func (s *Service) Rename(client *Client, newName string) error
func (s *Service) JoinGroup(client *Client, groupName string) error

Notice what's missing. There's no mention of netcat, no mention of how the client is connected, no mention of how messages are being sent over the wire. The service just does the work. How users are actually reaching the app is someone else's problem, i.e., the delivery layer's problem, which we'll get to.

One thing worth pointing out about this particular service: it uses channels and a Run() loop internally for concurrency safety, which is pretty idiomatic Go for this kind of problem. That's an implementation detail though. The outside world just calls Register, Broadcast, JoinGroup and so on. It has no idea what's happening inside.

That's the point. The service's internals are its own business.

The Repository Layer

The repository layer handles storage. Reading, writing, that's it. The service doesn't care how data is stored. It just calls clean, intention-revealing methods and expects results back.

Here's the Store interface from the URL shortener:

type Store interface {
    Save(link ShortLink) error
    Get(id string) (ShortLink, error)
    IncrementHits(id string) error
}
}

The service calls Save. The service calls Get. It has no idea whether that's hitting a Postgres database or an in-memory map. That's the whole point of defining it as an interface.

And here's what makes that useful in practice. I actually have two implementations of this interface. An in-memory one:

func (store *MemStore) Save(link ShortLink) error { ... }
func (store *MemStore) Get(id string) (ShortLink, error) { ... }
func (store *MemStore) IncrementHits(id string) error { ... }

And a Postgres one:

func (store *PGStore) Save(link ShortLink) error { ... }
func (store *PGStore) Get(id string) (ShortLink, error) { ... }
func (store *PGStore) IncrementHits(id string) error { ... }

Both implement the same interface. Both are completely valid stores as far as the service is concerned. The service just calls Save. It doesn't know and doesn't care which one it's talking to. So you can easily swap one for another, or even swap in a mock version for tests.

We'll see how you actually swap between them in a minute. But first, the delivery layer.

The Delivery Layer

The delivery layer is the outermost layer. It's how users actually reach your app, e.g., via an HTTP server, a CLI, a netcat listener. Its job is simple: receive input, call the service, return a response.

That's it. It should contain no business logic.

A useful test for this: if you replaced your HTTP server with a CLI tomorrow, would you need to rewrite this code? If yes, that logic belongs in the service, not here.

Here's what a handler in my URL shortener looks like:

func (h *Handler) HandleShorten(w http.ResponseWriter, r *http.Request) {
    var req ShortenRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        http.Error(w, "invalid request", http.StatusBadRequest)
        return
    }

    link, err := h.shortener.Shorten(req.URL)
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }

    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(link)
}

The handler decodes the request, calls h.shortener.Shorten(), and writes the response. That's all it does. It has no idea how the shortener generates a short code, which store it's using, or any of the logic involved. It just calls the service and handles the result.

Things the delivery layer should not be doing:

Generating short codes
Validating business rules (e.g., checking if a URL already exists)
Knowing what database you're using
Knowing how the service implements anything internally

If you catch yourself writing that kind of logic in a handler, it's a sign it belongs one layer down.

Interfaces: The Glue That Makes It Work

We've mentioned interfaces a couple of times now. Let's actually talk about why they matter here.

In Go, an interface defines what something can do, without caring about what it is. And that distinction is what makes the whole swappability idea practical rather than theoretical.

Here's the Store interface again:

type Store interface {
    Save(link ShortLink) error
    Get(id string) (ShortLink, error)
    IncrementHits(id string) error
}

The service depends on this interface. Not on MemStore. Not on PGStore. It just knows it's talking to something that can Save, Get, and IncrementHits. What that something actually is, is decided elsewhere.

Here's what the shortener (service) constructor looks like:

func NewShortener(store Store, generator IDGenerator) *Shortener {
    return &Shortener{store: store, generator: generator}
}

It takes a Store. Not a *MemStore. Not a *PGStore. A Store. So you can pass in either, and it'll work exactly the same.

This is sometimes called programming to an interface rather than an implementation. The service doesn't care what's behind the interface, and that's precisely why you can swap things out without touching the service at all.

Encapsulation: A Goal, Not a Side Effect

There's another benefit to this pattern that's worth naming explicitly, because it's easy to miss.

When each layer only exposes a clean interface to the layer above it, the internals of each layer are hidden. And that's not just a nice accident. I’d say it’s something we should be actively aiming for.

Here's why it matters practically: if your service hides its internals, you can refactor it freely. Change how you generate short codes, swap out your concurrency strategy, restructure your internal logic, etc. None of that affects the delivery layer, because the delivery layer only ever saw the interface. It never knew what was inside.

Same goes for the repository. You could migrate from Postgres to SQLite, and as long as your new implementation satisfies the Store interface, nothing else in your codebase needs to change.

Your teammates (or future you), can work on one layer without needing to understand or touch the others. I think that's a genuinely good thing to have, even on small projects.

Putting It All Together

Here's where it all clicks. Look at the main.go from the URL shortener:

// store := shorten.NewMemStore()
store := shorten.NewPGStore(sqlDB)
generator := shorten.NewBase62Generator()
shortener := shorten.NewShortener(store, generator)

mux := http.NewServeMux()
shorten.RegisterRoutes(mux, shortener)

server := http.Server{
    Addr:    ":8080",
    Handler: mux,
}

This is the wiring. main.go is where all three layers meet (and it's really the only place they meet.)

Notice the commented out line at the top. Switching from in-memory storage to Postgres is literally a one line change. That's the payoff of having defined a Store interface and having both implementations satisfy it.

The flow is:

main creates a store and passes it to the service
main creates the service and passes it to the delivery layer
The delivery layer handles requests and calls the service
The service does the work and calls the repository
Nobody reaches past their neighbour

Each layer was built independently. Each layer can be changed independently. And main is just the place that plugs them all together.

Conclusion

So to recap. Three layers, three jobs:

Service: what your app does
Repository: where your app stores data
Delivery: how users reach your app

Each layer talks to the one below it through a clean boundary. None of them know more than they need to. That's separation of concerns in practice.

The payoff isn't always obvious on a small project. But even on small projects, I've found it makes the code easier to reason about, easier to change, and easier for someone else to pick up. You always know where something belongs. And when you need to change something, you know exactly where to go.

It's one of those things that feels like a bit of extra work upfront, but saves you a lot of pain later.

A Beginner’s Guide to Testing in Go

Francis Awuor — Wed, 11 Feb 2026 19:33:37 +0000

I’ve been writing tests in Go for a few weeks now. And I’ve had more than a few moments of uncomfortable confusion.

So here’s a few things I wish someone had told me upfront.

Examples are in Go, but the ideas aren’t really language dependent.

Tests Enforce Contracts

Now right off the bat, you don’t want to get this wrong.

When writing tests, I’ve found the key thing to keep in mind is we should treat what we’re testing like a black box.

Give it specific inputs, expect specific outputs. For example, let’s take a look at function I had in a recent project (simplified). The project was a simple URL shortener I built.

func Create(url string) (shortCode string, err error)

The idea is, the function should take a URL string, e.g., https://exampleurl.com/this/is/really/long. That’s the input.

And it should return a short code that represents the long URL, e.g., bdcagl. Or an error if things go wrong. Those are the outputs.

That right there, that’s the contract. We’re saying if you give me a URL (a valid one), I should give you back a short code. Unless something goes wrong. In which case, I should give you an error.

This is what we test. So our test might look like this:

t.Run("Valid URL", func(t *testing.T) {
    url := "https://example.com"

    shortCode, err := Create(url)
    if err != nil {
        t.Fatalf("expected nil err, got %v", err) // if there's an unexpected error, fail the test
    }

    // Check that shortCode was generated
    if shortCode == "" {
        t.Error(`expected short code, got ""`) // after Creation, short code should not be empty
    }
})

Now the test above is what we call the happy path. It’s what we expect to happen when everything goes right. But what happens if something goes wrong?

Errors Are Part of the Contract Too

Of the outputs we expect, specific error cases are included.

What I mean is, if, for example, I pass in bad input, I should get back one error. But if something fails internally, I should get back a different error.

This is part of the contract. And it took me quite a while to realize.

Cause see what I’d often do is, in cases where I expected an error, I’d simply check for the presence of errors, e.g.,

url := "https:invalid-url//example./com" // invalid input should fail and return an error

shortCode, err := Create(url)
if err == nil {
        t.Fatalf("expected error, got nil") // if there's no error where you expect one, fail the test
    }

This is not enough!

I’ve since found that a better way to handle this, would be to check for specific errors, e.g,

if !errors.Is(err, ErrInvalidURL) { // Check for invalid url error
        t.Fatalf("expected ErrInvalidURL, got %v", err)
}

The contract should specify what error you get back.

NOTE: Testing error cases is just as important as testing happy paths. DO NOT sleep on it.

And we’re not done yet. Cause important as it is to have this mental model of contracts, it’s even more essential to understand how to structure our tests.

But in order to understand that, I have to first clear up what a unit test is. Cause it is not what I thought it was.

What Even Is a Unit?

For this section, it’s useful to quickly outline a commonly recommended structure for backend systems:

(We organize our HTTP server into layers)

HTTP Request
     |
   v
Handlers → receive HTTP requests and send responses
   |
   v
Services → apply business rules and coordinate work
   |
   v
Repository → reads and writes data in the database
   |
   v
Database

Now back to unit tests.

You might have heard of unit tests before. And if not, you’ll be glad you read this.

Cause see for a long time, when I heard “unit test”, I thought that referred to testing a function.

So if I had three functions, I thought that was three separate units to test.

I was wrong.

In our code, a unit is actually a “cohesive chunk of behavior, with one responsibility, that can be reasoned about independently.”

Which sounds fancy, but it really just means, if I have a service like this:

type Shortener struct {
    store Store // where you store the generated short code and its associated long URL
    gen   Generator // consider this a function that generates the short code
}

func (s *Shortener) Create(url string) (string, error) {
    // generates short code and saves it
}

func (s *Shortener) Resolve(shortCode string) (string, error) {
    // looks up original URL
}

func (s *Shortener) Stats(shortCode string) (int, error) {
    // returns hit count for a short code
}

Then that entire struct — the Shortener plus all its public methods (Create, Resolve , Stats) is ONE unit.

Not three units. One.

So when I write tests for Create, Resolve, and Stats, I’m just testing different behaviors of the same unit.

A way to say it that helped me understand better is:

A unit is the smallest part of your code where you can say: “If this breaks, I know exactly what kind of problem it is. Failures don’t blur together.”

This matters because once I understood this, test organization made way more sense.

So let’s get to it shall we? How to structure our tests.

Good Test Structure

See after writing a bunch of messy tests, I found a structure that works:

Setup → Subject → Assertion

Setup

Here you get everything ready for the test.

Say you want to test the Create function above. Well you need a generator, and a store. The Shortener’s Create function uses the generator to generate short codes, and the store to store the generated codes alongside the original URLs. This is the setup stage. You have to prepare what the element being tested needs, e.g.,:

// Setup
store := NewMockStore()
gen := NewMockGenerator()
service := NewShortener(store, gen)

Subject

The thing you’re actually testing. Call the method, trigger the behavior, e.g.,

// Subject
shortCode, err := service.Create("https://example.com")

Assertion

Verify the contract holds. Check outputs, check errors, check side effects. (Side effects are tricky though. We’ll talk about them in a bit)

Example:

// Assertion
if err != nil {
    t.Fatalf("Expected no error, got %v", err)
}

if shortCode != "abc123" {
    t.Errorf("Expected abc123, got %s", shortCode)
}

And one critical thing to keep in mind (trust me, I made this mistake quite a few times): If setup fails, fail the test immediately. E.g.,:

func TestCreate(t *testing.T) {
    store := NewMockStore()
    if store == nil {
        t.Fatal("Failed to create mock store") // t.Fatal() stops the test here
    }

    service := NewShortener(store, mockGenerator)
    if service == nil {
        t.Fatal("Failed to create service") // stops test here
    }

    // Now do the actual test...
}

There’s a simple reason why, i.e., if setup fails and you keep going, you’ll likely get misleading errors. The test will fail at unexpected points, and it’ll be a nightmare to debug.

And here’s where the bit about what a unit is gets particularly interesting.

See while working on my shortener, I had cases like this:

func TestResolve(t *testing.T) {
    service := NewShortener(mockStore, mockGen)

    // SEE THIS? We need to use Create for setup, cause to resolve (i.e., get the URL a short code points to), we need to have created the short code
    shortCode, err := service.Create("https://example.com")
    if err != nil {
        t.Fatalf("Setup failed: %v", err) // fail fast if setup fails
    }

    // Now test Resolve
    url, err := service.Resolve(shortCode)
    if err != nil {
        t.Errorf("Resolve failed: %v", err)
    }

    if url != "https://example.com" {
        t.Errorf("Expected https://example.com, got %s", url)
    }
}

It’s a case where we have to use the Create function to setup tests for the Resolve function. Because to resolve (i.e., get the URL a short code points to), we need to have created the short code.

Which seems reasonable enough. Until we, for example, go a level up and have a handler that needs another handler for setup. Here’s a snippet:

func TestHandleRedirect_OK(t *testing.T) {
// Setup
    // We would call HandleShorten() here, which creates a short code given the URL to shorten
    handler.HandleShorten(rr, req)

// Subject (the thing we're testing)
// Create a mock request specifically for testing
        req := httptest.NewRequest(http.MethodGet, "/"+shortCode, nil) // NOTICE the short code?
    rr := httptest.NewRecorder()

// Given a short code, HandleRedirect redirects to the URL the short code represents. It internally calls Resolve() to get this done.
    handler.HandleRedirect(rr, req)

    res := rr.Result()
    res.Body.Close()

    if res.StatusCode != http.StatusFound {
        t.Fatalf("expected status 302, got %d", res.StatusCode)
    }
}

Like the test for Resolve() earlier, we need the short code in order to test HandleRedirect. But in order to get the short code, we’d either have to call another handler, HandleShorten , to generate the short code for us…

Or we’d have to reach into the service and call service.Create().

So which approach is better?

Using Other Functions for Test Setup

The key principle I found to deal with these kinds of test setup issues is: A test should not depend on the behavior of another unit.

The key issue here, is unit boundaries. (See? Units came back)

See calling HandleShorten to set up HandleRedirect might feel symmetrical, but it’s actually the wrong move.

This is cause handlers are separate units.

If the HandleRedirect test failed, you wouldn’t be able to easily tell what broke. Was it HandleRedirect or HandleShorten? It messes with failure attribution.

HandleRedirect should not have to depend on HandleShorten to work.

The better approach, would be to reach down, not sideways.

func TestHandleRedirect_OK(t *testing.T) {
    service := NewShortener(mockStore, mockGen)
    handler := NewHandler(service)

    // Setup: reach down to the service
    shortCode, err := service.Create("https://example.com") // We have Create from the service setting up HandleRedirect
    if err != nil {
        t.Fatalf("Setup failed: %v", err)
    }

    // Subject
    req := httptest.NewRequest(http.MethodGet, "/"+shortCode, nil)
    rr := httptest.NewRecorder()

    handler.HandleRedirect(rr, req)

    res := rr.Result()
    res.Body.Close()

    if res.StatusCode != http.StatusFound {
        t.Fatalf("expected status 302, got %d", res.StatusCode)
    }
}

This is better because:

You’re testing one handler
Setup uses lower-level implementation
No handler depends on another handler’s behavior
If the test fails, we know where to look

And if service.Create breaks, the handler test should fail. Because in the real app, the handler relies on the service. It’s honest dependency.

However, it’s pretty important to note that the earlier example of using Create to set up Resolve, is different.

That’s perfectly fine, because

Create and Resolve belong to the same unit.
If Create is broke, Resolve is broken too.

A single service is a single unit. Handlers don’t have that relationship.

A “rule of thumb” of sorts that helps me with this is (and this ties back to the backend layers idea):

A test can depend on lower layers, but it shouldn’t depend on same layer entities unless it’s from the same unit.

However do note that an exception to this is the Service layer. For the service layer, you don’t want to call lower layer functions (from repository/db layer) directly for setup in your service tests, cause you’d be bypassing business rules, which is the core of your application. It’s at a base level, what your application should do.

And now one last thing I mustn’t forget to mention: Side Effects.

Side Effects Are Tricky

I say they’re tricky cause, a side effect is something your function changes internally, that’s not part of its return value.

My service.Resolve function, for example, internally increments a hits counter for a URL every time someone requests that URL.

“hits”, however, is not part of its return values, so you have to observe or test hits separately, for example by creating a separate function for metrics (e.g., my service.Stats function), through database queries, etc.

Key Takeaways

A unit is a cohesive module with a single responsibility, not a single function. (Think, “if something fails, can I tell what kind of problem it is?” - Clear failure attribution)
Tests enforce contracts - Specific inputs → Specific outputs
A reasonable test structure: Setup → Subject → Assertion
Fail fast on setup failures (t.Fatal() ) to avoid misleading errors
Side effects need indirect observation