Teams Need Protocols Too: Lessons from Building Go Backends Together
Building a Go backend alone is one kind of difficulty. Building one with three or four other people, each owning a slice of it, is a different kind entirely. At Zone01 Kisumu I've now done this twice: first a web forum,
Building a Go backend alone is one kind of difficulty. Building one with three or four other people, each owning a slice of it, is a different kind entirely.
At Zone01 Kisumu I've now done this twice: first a web forum, then a Facebook-style social network with a Go backend and a Next.js frontend. The code in both projects was the easy part. What caught me out was the space between people's code: assumptions that never got written down, names that didn't match, functions one person thought another had written.
This article is about those gaps, and the habits I've adopted to close them. It's written from a beginner's perspective, but I think the lessons hold up.
Project one: the forum
The forum was a team project in Go with SQLite, session authentication, Go template rendering, routing and Docker containerisation. We had a clean package layout:
internal/models/
internal/database/
internal/auth/
internal/handlers/
cmd/server/routes.go
Each teammate owned distinct modules. Mine was a specific set of five files covering likes, dislikes and post filtering:
- a handler for toggling likes/dislikes (auth-gated)
- a handler for filtering posts by category and query params
- the SQL queries behind both
- a unit test file
The team had an architecture diagram showing who owned what, and that diagram was my map. I treated it like gospel. That was my first mistake.
Lesson 1: the diagram describes intent; the committed files describe reality
When I started writing my handlers, I wrote them against what the diagram implied. Then I looked at my teammates' real code, and things didn't line up:
- I'd assumed posts had a
bodycolumn. The real schema usedcontent, and so did comments. - I'd assumed categories were free-text strings on posts. The real schema had a normalised
categoriestable withcategory_idforeign keys.
Neither mistake was dramatic, but both would have produced SQL that failed at runtime, and only at runtime, because SQL is a string as far as the Go compiler is concerned.
The fix was a rule I now follow without exception: before writing code that touches someone else's module, read their actual committed files. Type signatures, column names, function names, constructor shapes: take them from the source, not from a diagram or a conversation.
A small example. Instead of guessing how a teammate's handlers were constructed, I read their file and matched the pattern exactly:
// Matching an existing handler's constructor style
type LikeHandler struct {
db *sql.DB
}
func NewLikeHandler(db *sql.DB) *LikeHandler {
return &LikeHandler{db: db}
}
It looks trivial. But when five people each invent their own constructor style, integration day becomes a translation exercise.
Lesson 2: scope discipline is a feature
While writing the likes feature, I realised there was no Like struct in the models package. The obvious thing to do was to create one. It would have taken two minutes.
But internal/models belonged to a teammate. If I'd added like.go there, one of two things would have happened. He'd write his own and we'd have a duplicate type, or he'd find a file in his package that he didn't write and wonder what else had changed.
So I didn't. I flagged it: "this struct is needed, and it's in your area, so is it already written?" That one message cost thirty seconds and avoided an ownership argument.
The principle: even when generating or writing something outside your scope is convenient, check the architecture first. Convenience is how ownership gets blurry, and blurry ownership is how bugs end up with no owner.
Lesson 3: integration gaps are predictable, so hunt for them
When I read everyone's files side by side, I found four problems. None were in anyone's own code. They were all in the seams:
-
A function that didn't exist. Both my handler and a teammate's called
auth.GetSessionUser(r, db), but the session file didn't define it. Two of us had written code against a function we each assumed existed. -
A route conflict.
GET /postswas claimed by both his list handler and my filtered-posts handler. Go'sServeMuxwill panic on conflicting registrations, or one handler will silently shadow the other, depending on the setup. -
A missing migration. My code queried a
likestable. No migration created it. - The schema mismatches from Lesson 1.
Every single one of these would have surfaced eventually, but on integration day, under time pressure, with everyone's code merged and nobody sure whose fault it was.
My checklist for any multi-person backend now:
- Every function I call from someone else's package: does it exist, with that exact signature?
- Every route I register: is it unique across the whole app?
- Every table or column I query: is there a migration that creates it?
- Every shared type: who owns it, and is it written?
Ten minutes of this checklist beats two hours of debugging merged code.
Testing with in-memory SQLite
One thing that worked beautifully on the forum: testing handlers against an in-memory SQLite database. No test fixtures on disk, no cleanup, no shared state between tests:
func setupTestDB(t *testing.T) *sql.DB {
t.Helper()
db, err := sql.Open("sqlite3", ":memory:")
if err != nil {
t.Fatal(err)
}
// run the same schema the app uses
if err := applySchema(db); err != nil {
t.Fatal(err)
}
return db
}
My test file covered the cases that mattered for likes: liking, disliking, toggling, rejecting guests, and keeping counts accurate. The toggle logic (like, then like again to undo, then dislike to switch) is exactly the kind of thing that feels right in your head and is wrong in code until a test says so.
Project two: the social network
The second project was bigger: a Facebook-style social network, Go backend, Next.js frontend, SQLite with golang-migrate, WebSockets for real-time features, and a Dockerised two-container setup.
Three of us split the work along data ownership boundaries, so we'd collide as rarely as possible:
- Me: the foundation, authentication and shared infrastructure
- Teammate A: content (posts, comments, groups, events)
- Teammate B: real-time (WebSockets, chat, notifications) and Docker
Having learned from the forum, I tried to put the contracts in place before the code.
Convention 1: dependency injection, everywhere
Every module follows the same pattern:
repo := NewRepository(db)
service := NewService(repo, sessions)
Nothing reaches for a global database variable. Everything receives what it needs. It makes testing easier, and more importantly, it makes every teammate's module look the same, so reading each other's code is cheap.
Convention 2: one route registration signature
To avoid merge conflicts in server.go, every module exposes the same function shape:
func RegisterRoutes(mux *http.ServeMux, db *sql.DB)
server.go just calls each module's RegisterRoutes. Nobody edits anybody else's routes, and adding a module is a one-line change. This single decision prevented more merge pain than anything else we did.
Convention 3: shared sentinel errors
A pkg/utils/errors.go defines a small vocabulary used across all modules:
var (
ErrNotFound = errors.New("not found")
ErrForbidden = errors.New("forbidden")
ErrConflict = errors.New("conflict")
ErrUnauthorized = errors.New("unauthorized")
ErrBadRequest = errors.New("bad request")
)
Services return these; handlers translate them to HTTP status codes in one place. When each teammate invents their own error strings, the frontend gets a different error shape from every endpoint. With shared sentinels, errors.Is(err, utils.ErrConflict) means the same thing everywhere.
Decision: sessions, not JWTs
For authentication I chose session-based auth with opaque UUID tokens in HttpOnly cookies with SameSite: Lax, rather than JWTs.
My reasoning: this is a single-backend application with a browser frontend. Sessions can be revoked instantly by deleting a row, and the token itself carries no data to leak or go stale. HttpOnly keeps the cookie out of JavaScript's reach, which reduces the damage from an XSS bug. JWTs are great for stateless, multi-service setups, but that's not what we were building, and I'd rather use the simpler tool that fits.
A small feature with a real lesson: nickname suggestions
Midway through, we added unique nicknames. That meant a migration with a unique constraint, which is easy. The more interesting part was the UX when a conflict happens: telling someone "taken" and leaving them guessing is annoying.
So the auth service, on a conflict, returns both the conflict and a suggested alternative in a single response. One round trip, and the frontend can show "that nickname is taken, how about this one?" immediately. A tiny feature, but it's the kind of detail that makes a project feel considered during a peer audit.
The frontend-backend handshake
Integration with the Next.js side surfaced exactly the class of problems I'd learned to expect. They were small and annoying:
-
Field naming. The frontend used
camelCase; the Go JSON tags weresnake_case. Pick one on day one and write it down. - Response shape. The frontend expected one envelope; the backend returned another.
-
Date format. The frontend sent dates as
DD/MM/YYYY. Go's time parsing uses a reference date rather than format codes, so the layout string is:
t, err := time.Parse("02/01/2006", value)
If you've never seen Go's reference-date system, it's genuinely strange at first: you write the layout using the specific date Mon Jan 2 15:04:05 2006, rather than DD/MM/YYYY. Day is 02, month is 01, year is 2006. You stop being confused after about the fifth time.
The fix for all three was the same boring one: a short shared document of "what the API accepts and returns", agreed before either side hardened their code.
The environment is part of the project
A theme across both projects was that we worked on multiple shared lab machines with different Go versions and Docker configurations. We hit:
-
GOPATHconflicts because the Go installation belonged to another user -
go.modtoolchain mismatches between machines - rootless Docker on some machines, system-wide Docker on others
- stale environment variables silently overriding our settings
What helped: pinning dependency versions, using GOTOOLCHAIN=local so Go didn't try to download a different toolchain mid-build, and, when I needed to inspect a SQLite database inside an Alpine container with no sqlite3 CLI, building a small temporary debug endpoint rather than fighting the container.
That last one is a good example of pragmatism. When the standard tool isn't available, the question is "what's the smallest thing that answers my question?", not "how do I install the standard tool?"
Docker: one image or two?
When we split the app into containers, I used a simple test: will the frontend and backend ever need to scale, deploy or fail independently? For a real product, yes, so two images. For a small tool or prototype, one image is fine.
I like having a heuristic like this because it turns an argument into a question with an answer. It also made me curious about applying the same thinking elsewhere. I sketched a Kenyan chama (group savings) app with M-Pesa integration through Daraja, where separating the financial-data service from the user-facing app is a good idea for both scaling and safety. I haven't built it, but exploring ideas on paper like that is one of the best ways I've found to make a concept stick.
Habits that survived peer audits
Zone01 runs peer audits, meaning someone else reviews your project and expects to see it working. That pressure produced some habits I now like:
- Small, focused commits with short, direct messages, split by concern rather than batched into one giant "stuff" commit.
- Plain-text PR descriptions that say what changed and why.
- Documenting finished phases in the project wiki, so the next person (or me in three weeks) can see what exists.
- Working phase by phase: scaffolding, then foundation, then auth, then shared infrastructure. Each phase is something I can demo.
What I'd tell someone starting their first team backend
- Read committed code, not diagrams. Diagrams are intent. Code is fact.
- Respect module boundaries. If you need something in someone else's area, ask. Don't just add it.
- Agree conventions before writing features: constructors, route registration, errors, JSON naming, date formats.
- Run the integration checklist early: missing functions, duplicate routes, missing migrations, mismatched columns.
- Test against in-memory databases. Cheap, fast, isolated.
- Treat your environment as part of the system. Pin versions and write down the weird fixes.
- Ship phases, not promises. A working small thing beats a half-built big thing at audit time.
Closing thought
Before Zone01, I thought the hard part of software was writing code that works. Now I think the hard part is writing code that works with someone else's code. That's a communication problem as much as a technical one, which, for someone with a communication and networks degree, felt oddly familiar.
Networks are about agreeing on protocols so independent systems can talk. Team projects turn out to be the same thing, with people instead of routers.
If you've got your own war stories from team projects, I'd love to hear them in the comments. My code is on GitHub at rjeff-sudo.
Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.