@opengroundplan/core 0.1.1

package/templates/bases/fastapi-service/files/README.md

@@ -0,0 +1,42 @@
+# {{ solutionName | title }}
+
+FastAPI service. Python {{ pythonVersion }}+, pydantic v2, managed with [uv](https://docs.astral.sh/uv/), linted and formatted with [ruff](https://docs.astral.sh/ruff/).
+
+## Quick start
+
+```bash
+uv sync                     # create .venv and install dependencies
+cp .env.example .env        # optional: every key already has a default
+uv run {{ solutionName | kebab }}
+```
+
+The service listens on `http://127.0.0.1:{{ httpPort }}` by default.
+
+| Endpoint | Purpose |
+| --- | --- |
+| `GET /health` | liveness probe — unversioned, safe for orchestrators |
+| `GET {{ apiPrefix }}/greet/{name}` | example route |
+| `GET /docs` | interactive OpenAPI UI |
+
+## Commands
+
+```bash
+uv run ruff check .         # lint
+uv run ruff format .        # format
+```
+
+## Layout
+
+```
+src/{{ solutionName | snake }}/
+├── main.py        app factory + console-script entry point
+├── settings.py    the single typed default table (env-backed)
+└── api/routes.py  health + example routes
+```
+
+## Configuration
+
+All configuration lives in `src/{{ solutionName | snake }}/settings.py` as typed fields with
+defaults. Each field is overridable by an env var prefixed `{{ solutionName | upperSnake }}_`
+(see `.env.example`). Never read `os.environ` or hardcode a host, port, or timeout elsewhere —
+add a field to `Settings` instead.

package/templates/bases/fastapi-service/files/gitignore

@@ -0,0 +1,27 @@
+# Python
+*.py[cod]
+__pycache__/
+*.egg-info/
+build/
+dist/
+
+# Environments
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+
+# Tooling caches
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db

package/templates/bases/fastapi-service/files/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "{{ solutionName | kebab }}"
+version = "0.1.0"
+description = "{{ solutionName | title }} HTTP service"
+readme = "README.md"
+requires-python = ">={{ pythonVersion }}"
+dependencies = [
+    "fastapi>=0.139.2",
+    "pydantic>=2.13.4",
+    "pydantic-settings>=2.14.2",
+    "uvicorn[standard]>=0.51.0",
+]
+
+[project.scripts]
+{{ solutionName | kebab }} = "{{ solutionName | snake }}.main:run"
+
+[dependency-groups]
+dev = ["ruff>=0.15.22"]
+
+[build-system]
+requires = ["hatchling>=1.31.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/{{ solutionName | snake }}"]
+
+[tool.ruff]
+line-length = 100
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM"]
+
+[tool.ruff.format]
+docstring-code-format = true

package/templates/bases/fastapi-service/files/src/__solutionName.snake__/__init__.py

@@ -0,0 +1 @@
+"""{{ solutionName | title }} — FastAPI service."""

package/templates/bases/fastapi-service/files/src/__solutionName.snake__/api/__init__.py

@@ -0,0 +1 @@
+"""HTTP surface."""

package/templates/bases/fastapi-service/files/src/__solutionName.snake__/api/routes.py

@@ -0,0 +1,38 @@
+"""Example HTTP surface. Architecture overlays replace this with their own layout."""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends
+from pydantic import BaseModel, Field
+
+from {{ solutionName | snake }}.settings import Settings, get_settings
+
+SettingsDep = Annotated[Settings, Depends(get_settings)]
+
+health_router = APIRouter(tags=["health"])
+router = APIRouter(tags=["example"])
+
+
+class HealthResponse(BaseModel):
+    status: str
+    service: str
+    environment: str
+
+
+class Greeting(BaseModel):
+    name: str = Field(min_length=1, max_length=64)
+    message: str
+
+
+@health_router.get("/health")
+def health(settings: SettingsDep) -> HealthResponse:
+    return HealthResponse(
+        status="ok",
+        service=settings.app_name,
+        environment=settings.environment,
+    )
+
+
+@router.get("/greet/{name}")
+def greet(name: str, settings: SettingsDep) -> Greeting:
+    return Greeting(name=name, message=f"Hello {name}, welcome to {settings.app_name}.")

package/templates/bases/fastapi-service/files/src/__solutionName.snake__/main.py

@@ -0,0 +1,34 @@
+"""ASGI entry point for {{ solutionName | title }}."""
+
+import uvicorn
+from fastapi import FastAPI
+
+from {{ solutionName | snake }}.api.routes import health_router, router
+from {{ solutionName | snake }}.settings import Settings, get_settings
+
+
+def create_app(settings: Settings | None = None) -> FastAPI:
+    """Factory so tests and other entry points can inject their own settings."""
+    settings = settings or get_settings()
+    app = FastAPI(title=settings.app_name, debug=settings.debug)
+    app.state.settings = settings
+
+    # Health sits outside the versioned prefix so probes never chase an API version.
+    app.include_router(health_router)
+    app.include_router(router, prefix=settings.api_prefix)
+    return app
+
+
+app = create_app()
+
+
+def run() -> None:
+    """Console-script entry point: `uv run {{ solutionName | kebab }}`."""
+    settings = get_settings()
+    uvicorn.run(
+        "{{ solutionName | snake }}.main:app",
+        host=settings.host,
+        port=settings.port,
+        log_level=settings.log_level,
+        reload=settings.debug,
+    )

package/templates/bases/fastapi-service/files/src/__solutionName.snake__/settings.py

@@ -0,0 +1,30 @@
+"""The one typed default table for this service. Nothing else may hardcode config."""
+
+from functools import lru_cache
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="{{ solutionName | upperSnake }}_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    app_name: str = "{{ solutionName | title }}"
+    environment: str = "local"
+    debug: bool = False
+
+    host: str = "127.0.0.1"
+    port: int = {{ httpPort }}
+    api_prefix: str = "{{ apiPrefix }}"
+    log_level: str = "info"
+    request_timeout_seconds: float = 30.0
+
+
+@lru_cache
+def get_settings() -> Settings:
+    """Cached so the environment is read once and every caller shares one instance."""
+    return Settings()

package/templates/bases/go-api/blueprint.yaml

@@ -0,0 +1,58 @@
+id: go-api
+kind: base
+name: Go HTTP API
+description: >-
+  Stdlib-first Go HTTP service on chi. Structured logging, env-driven config with one
+  typed default table, graceful shutdown, health check, and one example endpoint.
+stack: go
+tags: [go, http, api, service, chi, stdlib]
+
+provides: [http-service, go-module]
+
+# Go's implicit interfaces and flat package layout suit ports/adapters and per-feature
+# packages directly; the frontend and AI-orchestration styles have no Go story here.
+supportsArchitectures:
+  - layered
+  - clean
+  - hexagonal
+  - onion
+  - vertical-slice
+  - monolith
+  - modular-monolith
+  - microservices
+  - pipes-and-filters
+
+variables:
+  - name: moduleHost
+    prompt: Go module path prefix (VCS host and org, without the repo name)
+    type: string
+    default: github.com/example
+    required: true
+  - name: httpPort
+    prompt: Default HTTP port
+    type: string
+    default: "8080"
+    required: true
+
+files:
+  - from: files/go.mod
+    to: .
+  - from: files/gitignore
+    to: .
+  - from: files/.env.example
+    to: .
+  - from: files/README.md
+    to: .
+  - from: files/cmd/**/*.go
+    to: .
+  - from: files/internal/**/*.go
+    to: .
+
+postApply:
+  # Required, unlike every other stack's install step. go.sum is a lockfile of cryptographic
+  # hashes, so unlike package.json or pyproject.toml it cannot be composed by merging text —
+  # a layer adding a module cannot also supply a correct hash for it. Nothing in the module
+  # graph compiles without it, so a repo generated with this step skipped does not build, and
+  # marking it optional made the CLI report success for exactly that repo.
+  - run: go mod tidy
+    optional: false

package/templates/bases/go-api/files/.env.example

@@ -0,0 +1,16 @@
+# Every key here is optional. internal/config holds the compiled-in default for each one,
+# so an empty environment still starts a working server. Nothing loads this file
+# automatically — export the values, or point your process manager at it.
+
+{{ solutionName | upperSnake }}_ENV=development
+{{ solutionName | upperSnake }}_SERVICE_NAME={{ solutionName | kebab }}
+{{ solutionName | upperSnake }}_LOG_LEVEL=info
+
+{{ solutionName | upperSnake }}_HTTP_HOST=0.0.0.0
+{{ solutionName | upperSnake }}_HTTP_PORT={{ httpPort }}
+
+{{ solutionName | upperSnake }}_READ_TIMEOUT=5s
+{{ solutionName | upperSnake }}_WRITE_TIMEOUT=10s
+{{ solutionName | upperSnake }}_IDLE_TIMEOUT=120s
+{{ solutionName | upperSnake }}_REQUEST_TIMEOUT=8s
+{{ solutionName | upperSnake }}_SHUTDOWN_TIMEOUT=15s

package/templates/bases/go-api/files/README.md

@@ -0,0 +1,76 @@
+# {{ solutionName | title }}
+
+Go HTTP service built on the standard library plus [chi](https://github.com/go-chi/chi) for
+routing. No framework, no runtime dependency on the generator that created it.
+
+## Requirements
+
+- Go 1.25 or newer
+
+## Run it
+
+```bash
+go mod tidy
+go run ./cmd/{{ solutionName | kebab }}
+```
+
+Then:
+
+```bash
+curl http://localhost:{{ httpPort }}/healthz
+curl http://localhost:{{ httpPort }}/api/v1/greetings/world
+```
+
+## Endpoints
+
+| Method | Path                        | Purpose                              |
+| ------ | --------------------------- | ------------------------------------ |
+| GET    | `/healthz`                  | Liveness probe. Touches nothing else. |
+| GET    | `/api/v1/greetings/{name}`  | Example endpoint — replace it.       |
+
+## Configuration
+
+All settings resolve in `internal/config`. Every key has a compiled-in default, so the
+service starts with an empty environment. Override any key with the environment variable
+`{{ solutionName | upperSnake }}_<KEY>`; see `.env.example` for the full list.
+
+| Key                | Default            | Notes                                  |
+| ------------------ | ------------------ | -------------------------------------- |
+| `ENV`              | `development`      | Free-form environment label.           |
+| `SERVICE_NAME`     | `{{ solutionName | kebab }}` | Reported by the health endpoint. |
+| `LOG_LEVEL`        | `info`             | `debug`, `info`, `warn`, `error`.      |
+| `HTTP_HOST`        | `0.0.0.0`          | Listen interface.                      |
+| `HTTP_PORT`        | `{{ httpPort }}`   | Listen port.                           |
+| `READ_TIMEOUT`     | `5s`               | Server read timeout.                   |
+| `WRITE_TIMEOUT`    | `10s`              | Server write timeout.                  |
+| `IDLE_TIMEOUT`     | `120s`             | Keep-alive idle timeout.               |
+| `REQUEST_TIMEOUT`  | `8s`               | Per-request budget, below write timeout. |
+| `SHUTDOWN_TIMEOUT` | `15s`              | Grace period for in-flight requests.   |
+
+Nothing reads `.env` automatically. Export the variables, or point your process manager at
+the file.
+
+## Layout
+
+```
+cmd/{{ solutionName | kebab }}/   process entry point, wiring and lifecycle only
+internal/config/                  environment resolution and the default table
+internal/httpapi/                 routing, middleware, handlers, response encoding
+```
+
+`internal/` is enforced by the Go toolchain: nothing outside this module can import it.
+
+## Conventions
+
+- Handlers are constructors returning `http.HandlerFunc`, so dependencies arrive as
+  arguments instead of package-level globals.
+- `writeJSON` in `internal/httpapi/respond.go` is the only response path.
+- New settings go in the `defaults` table in `internal/config/config.go` first — never
+  read `os.Getenv` from a handler.
+
+## Build
+
+```bash
+go build ./...
+go vet ./...
+```

package/templates/bases/go-api/files/cmd/__solutionName.kebab__/main.go

@@ -0,0 +1,65 @@
+// Command {{ solutionName | kebab }} starts the HTTP service.
+package main
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+
+	"{{ moduleHost }}/{{ solutionName | kebab }}/internal/config"
+	"{{ moduleHost }}/{{ solutionName | kebab }}/internal/httpapi"
+)
+
+func main() {
+	if err := run(); err != nil {
+		slog.Error("startup failed", "err", err)
+		os.Exit(1)
+	}
+}
+
+// run keeps main free of exit paths so every deferred cleanup actually runs.
+func run() error {
+	cfg, err := config.Load()
+	if err != nil {
+		return err
+	}
+
+	logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: cfg.LogLevel}))
+	slog.SetDefault(logger)
+
+	srv := &http.Server{
+		Addr:         cfg.Addr(),
+		Handler:      httpapi.NewRouter(cfg, logger),
+		ReadTimeout:  cfg.ReadTimeout,
+		WriteTimeout: cfg.WriteTimeout,
+		IdleTimeout:  cfg.IdleTimeout,
+	}
+
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+
+	serveErr := make(chan error, 1)
+	go func() {
+		logger.Info("listening", "addr", srv.Addr, "service", cfg.ServiceName, "env", cfg.Env)
+		if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
+			serveErr <- err
+		}
+	}()
+
+	select {
+	case err := <-serveErr:
+		return err
+	case <-ctx.Done():
+	}
+
+	// Drain in-flight requests before exiting so a rolling deploy drops nothing.
+	shutdownCtx, cancel := context.WithTimeout(context.Background(), cfg.ShutdownTimeout)
+	defer cancel()
+
+	logger.Info("shutting down")
+	return srv.Shutdown(shutdownCtx)
+}

package/templates/bases/go-api/files/gitignore

@@ -0,0 +1,27 @@
+# Binaries
+/bin/
+/dist/
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test and profiling output
+*.test
+*.out
+/coverage.*
+
+# Go workspace files
+go.work
+go.work.sum
+
+# Local environment — .env.example is the committed contract
+.env
+.env.*
+!.env.example
+
+# Editors and OS
+.idea/
+.vscode/
+.DS_Store

package/templates/bases/go-api/files/go.mod

@@ -0,0 +1,5 @@
+module {{ moduleHost }}/{{ solutionName | kebab }}
+
+go 1.25
+
+require github.com/go-chi/chi/v5 v5.3.1

package/templates/bases/go-api/files/internal/config/config.go

@@ -0,0 +1,127 @@
+// Package config resolves every runtime setting from the environment.
+package config
+
+import (
+	"errors"
+	"fmt"
+	"log/slog"
+	"net"
+	"os"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// Prefixed so several services can share one environment without colliding.
+const envPrefix = "{{ solutionName | upperSnake }}_"
+
+// The one ENV value the code branches on; every other value is just a label.
+const envDevelopment = "development"
+
+// Config is the fully resolved settings for one process.
+type Config struct {
+	Env             string
+	ServiceName     string
+	LogLevel        slog.Level
+	Host            string
+	Port            int
+	ReadTimeout     time.Duration
+	WriteTimeout    time.Duration
+	IdleTimeout     time.Duration
+	RequestTimeout  time.Duration
+	ShutdownTimeout time.Duration
+}
+
+// defaults is the single source of truth for every tunable. Add a knob here first;
+// the environment only ever overrides a key that already exists in this table.
+var defaults = map[string]string{
+	"ENV":              envDevelopment,
+	"SERVICE_NAME":     "{{ solutionName | kebab }}",
+	"LOG_LEVEL":        "info",
+	"HTTP_HOST":        "0.0.0.0",
+	"HTTP_PORT":        "{{ httpPort }}",
+	"READ_TIMEOUT":     "5s",
+	"WRITE_TIMEOUT":    "10s",
+	"IDLE_TIMEOUT":     "120s",
+	"REQUEST_TIMEOUT":  "8s",
+	"SHUTDOWN_TIMEOUT": "15s",
+}
+
+// Load reads the environment once at startup and reports every bad value at once.
+func Load() (Config, error) {
+	r := &reader{}
+	cfg := Config{
+		Env:             r.str("ENV"),
+		ServiceName:     r.str("SERVICE_NAME"),
+		LogLevel:        r.level("LOG_LEVEL"),
+		Host:            r.str("HTTP_HOST"),
+		Port:            r.intVal("HTTP_PORT"),
+		ReadTimeout:     r.duration("READ_TIMEOUT"),
+		WriteTimeout:    r.duration("WRITE_TIMEOUT"),
+		IdleTimeout:     r.duration("IDLE_TIMEOUT"),
+		RequestTimeout:  r.duration("REQUEST_TIMEOUT"),
+		ShutdownTimeout: r.duration("SHUTDOWN_TIMEOUT"),
+	}
+	if len(r.errs) > 0 {
+		return Config{}, errors.Join(r.errs...)
+	}
+	return cfg, nil
+}
+
+// Addr is the listen address for the HTTP server.
+func (c Config) Addr() string {
+	return net.JoinHostPort(c.Host, strconv.Itoa(c.Port))
+}
+
+// IsDevelopment reports whether relaxed, developer-facing behavior is allowed.
+func (c Config) IsDevelopment() bool {
+	return c.Env == envDevelopment
+}
+
+type reader struct {
+	errs []error
+}
+
+func (r *reader) str(key string) string {
+	def, declared := defaults[key]
+	if !declared {
+		r.errs = append(r.errs, fmt.Errorf("config: no default declared for %q", key))
+		return ""
+	}
+	if v, found := os.LookupEnv(envPrefix + key); found && strings.TrimSpace(v) != "" {
+		return strings.TrimSpace(v)
+	}
+	return def
+}
+
+func (r *reader) intVal(key string) int {
+	raw := r.str(key)
+	v, err := strconv.Atoi(raw)
+	if err != nil {
+		r.reject(key, "an integer", raw)
+	}
+	return v
+}
+
+func (r *reader) duration(key string) time.Duration {
+	raw := r.str(key)
+	v, err := time.ParseDuration(raw)
+	if err != nil {
+		r.reject(key, "a duration like 5s", raw)
+	}
+	return v
+}
+
+func (r *reader) level(key string) slog.Level {
+	raw := r.str(key)
+	var lvl slog.Level
+	if err := lvl.UnmarshalText([]byte(raw)); err != nil {
+		r.reject(key, "debug, info, warn or error", raw)
+	}
+	return lvl
+}
+
+// reject records one bad value so every type reports in the same shape.
+func (r *reader) reject(key, want, got string) {
+	r.errs = append(r.errs, fmt.Errorf("config: %s%s must be %s, got %q", envPrefix, key, want, got))
+}

package/templates/bases/go-api/files/internal/httpapi/greeting.go

@@ -0,0 +1,25 @@
+package httpapi
+
+import (
+	"net/http"
+	"strings"
+
+	"github.com/go-chi/chi/v5"
+)
+
+type greetingResponse struct {
+	Message string `json:"message"`
+}
+
+// handleGreeting is the reference endpoint showing the path-param, validate, respond shape.
+// Delete it once real routes exist.
+func handleGreeting() http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		name := strings.TrimSpace(chi.URLParam(r, "name"))
+		if name == "" {
+			writeJSON(w, http.StatusBadRequest, errorResponse{Error: "name is required"})
+			return
+		}
+		writeJSON(w, http.StatusOK, greetingResponse{Message: "Hello, " + name + "!"})
+	}
+}

package/templates/bases/go-api/files/internal/httpapi/health.go

@@ -0,0 +1,25 @@
+package httpapi
+
+import (
+	"net/http"
+
+	"{{ moduleHost }}/{{ solutionName | kebab }}/internal/config"
+)
+
+type healthResponse struct {
+	Status  string `json:"status"`
+	Service string `json:"service"`
+	Env     string `json:"env"`
+}
+
+// handleHealth answers liveness probes. Keep it dependency-free — a readiness check that
+// fans out to a database belongs on its own route.
+func handleHealth(cfg config.Config) http.HandlerFunc {
+	return func(w http.ResponseWriter, _ *http.Request) {
+		writeJSON(w, http.StatusOK, healthResponse{
+			Status:  "ok",
+			Service: cfg.ServiceName,
+			Env:     cfg.Env,
+		})
+	}
+}

package/templates/bases/go-api/files/internal/httpapi/respond.go

@@ -0,0 +1,25 @@
+package httpapi
+
+import (
+	"encoding/json"
+	"log/slog"
+	"net/http"
+)
+
+type errorResponse struct {
+	Error string `json:"error"`
+}
+
+// writeJSON is the only response path, so every endpoint agrees on encoding and headers.
+// The header is already sent by the time encoding can fail, so the error is logged, not returned.
+func writeJSON(w http.ResponseWriter, status int, body any) {
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	w.WriteHeader(status)
+
+	if body == nil {
+		return
+	}
+	if err := json.NewEncoder(w).Encode(body); err != nil {
+		slog.Error("encode response", "status", status, "err", err)
+	}
+}