Add project layout, endpoints table, route guide, and shutdown note to README

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Makefile

@@ -1,9 +1,9 @@
 .PHONY: *
 
-help: ## This help dialog.
+help: 
 	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2 | "sort -u"}' $(MAKEFILE_LIST)
 
-check-docker: ## Verify Docker CLI is available
+check-docker: ## Verify Docker CLI available
 	@command -v docker >/dev/null 2>&1 || { \
 		echo "Error: docker not found."; \
 		echo "Install Docker Desktop: https://docs.docker.com/desktop/setup/install/mac-install/"; \
@@ -17,20 +17,20 @@ run: check-docker ## Start the application with Docker Compose
 run-local: ## Start the application locally (without Docker)
 	go run ./cmd/app
 
-down: check-docker ## Stop the application
+down: check-docker 
 	docker compose down --remove-orphans
 
 setup-local: copy-config install-dependencies ## Install config and Go dependencies
 
 setup-docker: setup-local run ## Install dependencies and start with Docker Compose
 
-install-lint: ## Install Go lint
+install-lint:
 	go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
 
 install-dependencies: ## Install Go project dependencies
 	go mod download
 
-copy-config: ## Copy config file if missing
+copy-config:
 	@test -f .env || cp .env.dist .env
 
 lint: install-lint ## Run lint

README.md

@@ -1,6 +1,32 @@
 # Go HTTP server
 
-A simple Go HTTP server boilerplate with Echo, structured logging, graceful shutdown, and Docker support.
+A simple Go HTTP server boilerplate with Echo, structured logging, and Docker support. Includes graceful shutdown on `SIGINT`/`SIGTERM` via `errgroup`.
+
+## Project layout
+
+    cmd/app/                     entrypoint, wiring, graceful shutdown
+    cmd/app/handler/             HTTP handlers and route registration
+    internal/config/             env-based configuration
+    internal/domain/             your business logic goes here
+    internal/infrastructure/os/  signal handling
+    pkg/logger/                  Zap logger setup
+
+## Endpoints
+
+| Method | Path      | Description               |
+|--------|-----------|---------------------------|
+| GET    | `/health` | Liveness check (`200 OK`) |
+
+## Adding an endpoint
+
+Register routes in a `setup…Routes` method and call it from `handler.New`
+(see `cmd/app/handler/health.go`):
+
+```go
+func (h *Handler) setupFooRoutes(e *echo.Echo) {
+    e.GET("/foo", h.getFoo)
+}
+```
 
 ## Prerequisites
 

cmd/app/handler/handler.go

@@ -1,4 +1,4 @@
-package httpjson
+package handler
 
 import (
 	"context"

cmd/app/handler/handler_test.go

@@ -1,4 +1,4 @@
-package httpjson
+package handler
 
 import (
 	"context"

cmd/app/handler/health.go

@@ -1,4 +1,4 @@
-package httpjson
+package handler
 
 import (
 	"net/http"

cmd/app/handler/health_test.go

@@ -1,4 +1,4 @@
-package httpjson
+package handler
 
 import (
 	"io"

cmd/app/service.go

@@ -3,7 +3,7 @@ package main
 import (
 	"context"
 
-	"github.com/kjannette/go_http_server/cmd/app/handler/httpjson"
+	"github.com/kjannette/go_http_server/cmd/app/handler"
 	"github.com/kjannette/go_http_server/internal/config"
 
 	"go.uber.org/zap"
@@ -14,7 +14,7 @@ func run(ctx context.Context, cfg *config.Config) error {
 	lg := zap.L().With(zap.String("app_name", appName), zap.String("app_version", appVersion))
 
 	eg, ctx := errgroup.WithContext(ctx)
-	app, h := httpjson.New(lg)
+	app, h := handler.New(lg)
 	serverLog := lg.Named("run_server")
 
 	eg.Go(func() error {

internal/config/config.go

@@ -5,7 +5,6 @@ import (
 	"github.com/pkg/errors"
 )
 
-// Config represents the application configuration.
 type Config struct {
 	API struct {
 		Port         int `envconfig:"API_PORT" default:"3000"`
@@ -16,7 +15,6 @@ type Config struct {
 	}
 }
 
-// NewConfig creates a new initialised application Config.
 func NewConfig() (*Config, error) {
 	var config Config
 

pkg/logger/logger.go

@@ -8,7 +8,6 @@ import (
 	"go.uber.org/zap/zapcore"
 )
 
-// init initializes zap's global loggers (i.e. zap.L() and zap.S()).
 // Log level is retrieved from environment variable LOG_LEVEL, defaulting to "info" otherwise.
 // To activate this facility, add a blank import to this package.
 func init() {