Dev Log #1: Building My Go App Starter Template

Introduction

Hey there 👋

This is the first entry in what I hope will become an ongoing development log series. I've been working on a little Golang starter template, a personal project that started out of pure frustration (more on that soon). This isn't meant to be a tutorial (though I hope it becomes a valuable resource for developers new to these stacks) or a deep technical breakdown. It's more like a behind-the-scenes look at what I'm building, why I'm building it, the decisions I'm making along the way, and what I've learned in the process.

If you are anything like me, someone who has a dozen new project ideas buzzing around at any given time, you've probably felt the same drag. You get all excited about an idea, open up your editor, and then bam: you're neck-deep in setting up boilerplate, configuring logs, wiring up the database… again. Every single time. It kills momentum. It's not exciting work, but it's necessary work.

After a few projects, I did what most of us probably do: I started copying bits and pieces from older repos. A logging setup here, an authentication flow there, a database configuration; I remember setting it up correctly last time. It worked… kind of. But it was messy, inconsistent, and always felt like I was dragging technical debt into a brand‑new idea before I'd even written a single line of actual business logic. And honestly, I got tired of that too.

This dev log is my way of journaling that journey. It's a mix of reflection, rough edges, technical decisions, and future plans. Whether you're a solo hacker, an indie builder, or just playing around with Go, this gives you insight (and maybe even a push to start your own thing too).

Let's rewind a bit and talk about where this all started.

The Idea Behind The Template

Given all of that, the idea for the template was pretty straightforward: I wanted a setup where I could drop in a project skeleton and start from real application logic, rather than spending the first evening wiring the same pieces together again. As a perfectionist, I often find myself stuck polishing infrastructure and tweaking setup scripts before there's even a real app to run. That kind of thinking can be helpful later on, but in the early stages, it just slows things down.

So I started jotting down the pieces I always reach for. A solid logger, some basic HTTP middleware, and a way to write and run integration tests without too much setup. Postgres is usually my go-to database, so I wanted that configured with sensible defaults and auto-migrations out of the box using golang-migrate. I knew I'd want JWT-based authentication, so I built in a basic auth flow early.

Once I had that rough list of building blocks, the next step was deciding how they should fit together and how opinionated I wanted this starter to be. That's where the design philosophy started to take shape.

Design Philosophy

The template is opinionated, but in a way that stems from having done this numerous times across different projects, rather than from trying to declare the "right" way to write Go. The structure, middleware choices, and the way logging and configuration are wired up are all things I've tweaked and refined over multiple iterations, real projects, and a fair share of mistakes. It's less "here's the official best practice" and more "here's what has consistently worked well for me."

I also tried to be really intentional about dependencies. It's easy to pull in a bunch of packages to avoid writing boilerplate, but that can snowball into unnecessary complexity. I've kept things relatively minimal, bringing in dependencies that add clear, obvious value.

Structurally, I wanted the codebase to feel clean but not over-engineered. It should be something you can comfortably use for a small side project, but that doesn't fall apart if the idea turns into something bigger. A lot of existing templates seem to land at the extremes: either so barebones that you still have to wire everything yourself, or so bloated that you need to read a few blog posts to understand the folder layout. I'm trying to strike a balance, providing enough structure so you're not starting from scratch, but not so much that you're learning a framework instead of building your app.

Current Features: what's built so far

Currently, the starter includes a small backend feature set that covers the basics I need for almost every project. The core of it is a simple authentication flow: local signup and login using Argon2id for password hashing (with OWASP-suggested parameters) and a credential-checking layer that plugs into the authentication middleware. It's not a comprehensive identity system, but it provides a solid and secure foundation.

On the data side, it's built around Postgres with a connection pool (via pgx) and a few helper functions for common user operations. Migrations are handled by golang-migrate and embedded into the binary, allowing schema changes to be applied automatically at startup or in CI without requiring extra manual steps. There's also a basic health endpoint that checks database readiness, which is useful both locally and when it is deployed behind any orchestration.

I've treated logging and tests as part of the core setup rather than something to add later. Structured logging (using zerolog) is integrated into both the HTTP and database layers, providing useful context such as request information and service metadata in your logs. For tests, there are integration-style checks around the authentication flow using hurl.dev. Because the migrations are embedded, these tests can run in CI or locally with minimal additional setup.

By the time I publish this post, I hope to have a basic Flutter client (iOS and Android) connected to this backend for authentication, allowing me to reuse the same patterns across mobile apps without having to rethink the flow every time.

Learning From The Community

If you end up using this template or even skimming the repository, I'd love to hear what you typically set up in every new project. What are the first few things you always add? Are there patterns you've seen work really well in production that you now reuse everywhere? It could be a specific way of structuring handlers, a preferred logging pattern, how you organize modules, or even small details like how you write tests or handle configuration.

The Bigger Vision

Right now, the focus is mainly on the backend, but I don't really want this to stay "just a Go API starter." Long term, I'd like this to be a genuinely solid starting point for full-stack projects, something that's close to a no-brainer when you're about to start a new app.

On the frontend side, the first step is to use Flutter for iOS and Android, which is wired up to the same authentication flow that the backend exposes. The idea is to have a simple authentication flow (login, signup, home screen placeholder) that you can either keep or discard. Still, at least you don't have to figure out the wiring every time. Eventually, I would like the Flutter setup to also support web, Linux, Windows, and macOS, so you can reuse the same codebase across all platforms. How much of the UI is "predefined" is still an open question. I don't want this template to impose strong UI or design opinions on people. Still, if the community prefers to have some basic, reusable UI patterns in place, I'm open to collaborating on that.

In parallel, I'd like to add a React web client built with Bun for tooling, TanStack Router for routing, and TanStack Query for the data layer. Similar idea: small, focused, and wired into the same auth and API stack.

Beyond the clients, there are a few "infrastructure and ergonomics" pieces I want to tackle. I'd like to have a more comprehensive Docker setup for local and development deployments, as well as some basic Kubernetes manifests for those who wish to take it further. I'm also interested in adding a small setup CLI that guides you through customizing the template, including module paths, app name, and toggling optional features. Hence, it feels like starting your own project rather than forking mine.

On the auth side, the current flow is intentionally minimal. Still, the plan is to expand it: OAuth logins (Google, GitHub, etc.), password reset, magic links, basic email verification, and at least a simple roles/permissions story (user, admin, superadmin) with middleware to enforce it. None of this needs to be enterprise-grade, but it should be clean enough that you can either use it as-is or treat it as a reference implementation for your own version.

Overall, the vision isn't to build a giant framework. It's to keep polishing this into something that feels like a very good default, something I'd happily reach for on most new projects, and hopefully something other people can say the same about.

Challenges So Far

So far, most of the friction has been in the less glamorous parts of the project. One of the early challenges has been dealing with environment differences. I've primarily tested the Makefile and development setup on Linux, which is my primary operating system. That means there are rough edges on macOS and Windows, especially around the availability of shell commands, tools, and small details like how sed or awk behave.

Another ongoing challenge is deciding how generic or specific to be. Since this starter is based on patterns from my own projects, it's easy to lean too hard into my personal preferences and workflows. At the same time, if I try to make every piece abstract and configurable enough to fit all possible use cases, it quickly becomes bloated and more complicated to understand. Finding that middle ground, useful out of the box, but not over-engineered, takes more thought than I expected. Balancing those tradeoffs is still a work in progress.

FAQs

How can I contribute or share patterns I use in my own projects?
If you spot a bug, rough edge, or have a small feature / quality-of-life idea, the best place to start is by opening a GitHub issue; if it's something bigger, like a new feature area, a different way to structure parts of the app, or "I always do X in all my Go services, maybe this template should too", then opening a GitHub Discussion is better so others can chime in. We can talk it through as a group before anyone spends time implementing it. In both cases, I'm especially interested in hearing what you usually set up in every new project (how you structure handlers, logging patterns, testing approaches, config handling, etc.) so the template can evolve based on real usage, not just my habits.

How "locked in" am I to your stack choices if I start with this?
The template is opinionated, things like Postgres, Argon2id, zerolog, pgx, and hurl.dev are there because they've worked well for me, but it's not meant to lock you in; the structure is simple enough that if you're comfortable with Go, you can swap out pieces (logger, database, auth approach, etc.) over time without having to tear everything down and start again.

What if I only care about the backend and don't want the Flutter/React pieces?
That's completely fine, the backend is designed to stand on its own, and you can treat the mobile and web clients as optional extras or just as examples; if all you want is a Go API starter with sane defaults for auth, Postgres, logging, and tests, you can ignore the frontend pieces entirely and use only the parts that actually fit your project.