Implement web API foundation

Add application container, Gin router, graceful shutdown handler,
and version endpoint. This establishes the skeleton for the WebDisk
HTTP API as described in the architecture.

- Add internal/app/WebApp for runtime dependencies and version
- Add internal/server/router with GET /api/v1/version route
- Add graceful shutdown runner with signal handling in cmd/serve
- Add internal/api/ErrorResponse for standard HTTP error body
- Update roadmap, architecture, and decisions documentation

internal/server/router.go

@@ -0,0 +1,32 @@
+package server
+
+import (
+	"github.com/gin-gonic/gin"
+
+	"github.com/dhao2001/mygo/internal/app"
+	"github.com/dhao2001/mygo/internal/handler"
+)
+
+// NewRouter builds the Gin router and registers API routes.
+func NewRouter(webApp *app.WebApp) *gin.Engine {
+	router := gin.Default()
+
+	rootGroup := router.Group("/api/v1")
+
+	publicGroup := rootGroup.Group("")
+	setupVersionRoutes(publicGroup, handler.NewVersionHandler(webApp.Version))
+
+	authGroup := rootGroup.Group("")
+	setupProtectedRoutes(authGroup)
+
+	return router
+}
+
+func setupVersionRoutes(rg *gin.RouterGroup, h *handler.VersionHandler) {
+	rg.GET("/version", h.Get)
+}
+
+func setupProtectedRoutes(rg *gin.RouterGroup) {
+	// Protected routes will be registered after auth middleware exists.
+	_ = rg
+}

internal/server/server.go

@@ -0,0 +1,49 @@
+package server
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"time"
+
+	"github.com/dhao2001/mygo/internal/config"
+)
+
+// Address returns the HTTP listen address for a server config.
+func Address(cfg config.ServerConfig) string {
+	return fmt.Sprintf("%s:%d", cfg.Host, cfg.Port)
+}
+
+// RunWithGracefulShutdown starts an HTTP server and shuts it down when ctx is canceled.
+func RunWithGracefulShutdown(ctx context.Context, addr string, handler http.Handler) error {
+	if handler == nil {
+		return errors.New("handler: must not be nil")
+	}
+
+	httpServer := &http.Server{
+		Addr:              addr,
+		Handler:           handler,
+		ReadHeaderTimeout: 5 * time.Second,
+	}
+
+	errCh := make(chan error, 1)
+	go func() {
+		errCh <- httpServer.ListenAndServe()
+	}()
+
+	select {
+	case <-ctx.Done():
+		shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+		defer cancel()
+		if err := httpServer.Shutdown(shutdownCtx); err != nil {
+			return fmt.Errorf("shutdown server: %w", err)
+		}
+		return nil
+	case err := <-errCh:
+		if errors.Is(err, http.ErrServerClosed) {
+			return nil
+		}
+		return fmt.Errorf("listen and serve: %w", err)
+	}
+}

internal/server/server_test.go

@@ -0,0 +1,48 @@
+package server
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/dhao2001/mygo/internal/app"
+	"github.com/dhao2001/mygo/internal/config"
+)
+
+func TestVersionRoute(t *testing.T) {
+	webApp := app.NewWebApp(&config.Config{})
+	router := NewRouter(webApp)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/version", nil)
+	rec := httptest.NewRecorder()
+
+	router.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	if got := rec.Header().Get("Content-Type"); got != "application/json; charset=utf-8" {
+		t.Fatalf("content-type = %q, want %q", got, "application/json; charset=utf-8")
+	}
+
+	var body struct {
+		Version string `json:"version"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+		t.Fatalf("unmarshal response: %v", err)
+	}
+
+	if body.Version != app.AppVersion {
+		t.Errorf("version = %q, want %q", body.Version, app.AppVersion)
+	}
+}
+
+func TestAddress(t *testing.T) {
+	got := Address(config.ServerConfig{Host: "127.0.0.1", Port: 8080})
+	want := "127.0.0.1:8080"
+	if got != want {
+		t.Errorf("Address() = %q, want %q", got, want)
+	}
+}