Skeleton — module, Chi, your first server

Code

The server — handlers, router, main

Now the server itself — three files, as tabs, in dependency order: handlers.go → router.go → main.go (a handler, then the router that mounts it, then the main that runs the router). Build them top to bottom; main won't compile until the handler and router exist.

1. internal/handlers/handlers.go — the Handlers struct bundles shared dependencies (right now just config + a logger; it gains a database field in lesson 3). Home writes a plain HTML string — lesson 2 swaps it for a Templ template. Health answers /healthz with "ok" — the endpoint Railway will poll in the deploy phase.

2. internal/handlers/router.go — the Chi router and the middleware stack, outermost first:

r.Use(middleware.RequestID)
r.Use(middleware.RealIP)
r.Use(middleware.Logger)    // one log line per request
r.Use(middleware.Recoverer) // a panic becomes a 500, not a crash
r.Get("/", h.Home)
r.Get("/healthz", h.Health)

Recoverer is the one that saves you at 2am: a panic in any handler becomes a clean 500 instead of taking the whole server down.

3. cmd/signflow/main.go — the entry point. It loads config, builds the router, and serves with graceful shutdown: on Ctrl-C (SIGINT) or SIGTERM it stops accepting new requests and drains in-flight ones for up to 15 seconds before exiting. (cmd/ holds the runnable entrypoint; everything else is a library under internal/.)

Verify. Run it:

go run ./cmd/signflow

You should see structured logs:

level=INFO msg="starting signflow" env=dev port=8080 base_url=http://localhost:8080
level=INFO msg=listening addr=:8080

In another terminal:

$ curl -s localhost:8080/healthz
ok
$ curl -s localhost:8080/
<!doctype html>
<title>SignFlow</title>
<h1>✍️ SignFlow</h1>
<p>The skeleton is up and serving.</p>

Open http://localhost:8080 in a browser — there's your (unstyled) SignFlow. Ctrl-C the server and watch it log shutting down and exit cleanly, not with a stack trace.

Gotcha (port already in use). Start it twice and the second one dies with:
level=ERROR msg="server error" err="listen tcp :8080: bind: address already in use"
Something is already on 8080 (often a forgotten go run). Stop the other process, or run this one on another port: PORT=8081 go run ./cmd/signflow — the config default you just wrote makes that Just Work.

handlers.go CREATE

Create this file in internal/handlers/

// Package handlers holds the HTTP handlers. In this skeleton there is only the
// home page and a health check; later lessons add auth, documents, and signing.
package handlers

import (
	"fmt"
	"log/slog"
	"net/http"

	"github.com/programuoki/signflow/internal/config"
)

// Handlers bundles the dependencies every handler needs. Constructed once in
// main; its methods are registered on the router. It gains fields as the app
// grows (a database in lesson 3, sessions in lesson 4, ...).
type Handlers struct {
	Cfg config.Config
	Log *slog.Logger
}

func New(cfg config.Config, log *slog.Logger) *Handlers {
	return &Handlers{Cfg: cfg, Log: log}
}

// Home renders the landing page. For now it is a plain HTML string — lesson 2
// replaces it with a type-safe Templ template.
func (h *Handlers) Home(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "text/html; charset=utf-8")
	fmt.Fprint(w, `<!doctype html>
<title>SignFlow</title>
<h1>✍️ SignFlow</h1>
<p>The skeleton is up and serving.</p>`)
}

// Health is a plain-text liveness probe for Railway / uptime checks.
func (h *Handlers) Health(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "text/plain")
	_, _ = w.Write([]byte("ok"))
}

router.go CREATE

Create this file in internal/handlers/

package handlers

import (
	"net/http"

	"github.com/go-chi/chi/v5"
	"github.com/go-chi/chi/v5/middleware"
)

// Router builds the Chi router with the base middleware stack. Route groups for
// static assets (lesson 2) and auth-protected pages (lesson 5) are added later.
func (h *Handlers) Router() http.Handler {
	r := chi.NewRouter()

	// Base middleware, outermost first.
	r.Use(middleware.RequestID)
	r.Use(middleware.RealIP)
	r.Use(middleware.Logger)    // request logging
	r.Use(middleware.Recoverer) // turn panics into 500s instead of crashing

	r.Get("/", h.Home)
	r.Get("/healthz", h.Health)

	return r
}

main.go CREATE

Create this file in cmd/signflow/

// Command signflow is the HTTP server entrypoint. On startup it loads config,
// builds the Chi router, and serves with graceful shutdown. Lesson 3 adds the
// database (migrations + a connection pool) between config and serving.
package main

import (
	"context"
	"errors"
	"log/slog"
	"net/http"
	"os"
	"os/signal"
	"syscall"
	"time"

	"github.com/programuoki/signflow/internal/config"
	"github.com/programuoki/signflow/internal/handlers"
)

func main() {
	log := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo}))
	if err := run(log); err != nil {
		log.Error("fatal", "err", err)
		os.Exit(1)
	}
}

func run(log *slog.Logger) error {
	cfg, err := config.Load()
	if err != nil {
		return err
	}
	log.Info("starting signflow", "env", cfg.Env, "port", cfg.Port, "base_url", cfg.BaseURL)

	h := handlers.New(cfg, log)

	srv := &http.Server{
		Addr:              ":" + cfg.Port,
		Handler:           h.Router(),
		ReadHeaderTimeout: 10 * time.Second,
	}

	// Graceful shutdown: stop accepting on SIGINT/SIGTERM, then drain in-flight
	// requests for up to 15s before exiting.
	shutdownCtx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()

	go func() {
		log.Info("listening", "addr", srv.Addr)
		if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
			log.Error("server error", "err", err)
			stop()
		}
	}()

	<-shutdownCtx.Done()
	log.Info("shutting down")

	timeout, cancel := context.WithTimeout(context.Background(), 15*time.Second)
	defer cancel()
	return srv.Shutdown(timeout)
}