Go — Backend Services (clean architecture)

This skill governs Go in the a-novel backend services: repos shaped as cmd/ + internal/{config,lib,dao,core,handlers,models} + (optionally) pkg/. Aim for coherent, idiomatic, minimal code that strictly respects the layered architecture.

This skill is layered on write-go. Everything there — read-before-edit, the pnpm format:go/pnpm lint:go discipline, dependency policy, naming of packages/files/variables, constructors, error sentinels and %w wrapping, context rules, time-capture-once, secrets hygiene, the span-reporting rule — applies here unchanged; this skill adds the service-architecture-specific rules on top. Load write-go and write-go-tests (and document-code when documenting) alongside it. For shared libraries under a-novel-kit (golib, jwt, …) load write-go-kit instead of this skill.

Before touching any layer, read its sibling files, the interfaces it depends on, and the interfaces it exposes. These services are deliberately consistent — copy the established pattern exactly; coherence outranks preference.

a-novel/service-template is the shortcut to start a new service, so it tracks the services' conventions. A change that sets or changes a convention in a service ships with the matching service-template change, in a pull request opened alongside it.

Load the affected layer

Keep the architecture, interface, and security rules in this entry point active. Before planning, editing, or reviewing service behavior, read each reference matching an affected layer. Read the layer rules when testing its contract too; crossing layers requires each matching reference.

• DAO operations, constraint violations, ownership checks or transaction ownership, including core/job transactions: data access.
• Core validation/orchestration or REST/gRPC handlers: operations.
• Config, internal helpers, models, exported clients, command wiring, or fault reporting: wiring.
• REST routes, gRPC methods, request bodies, rate limits, call caps, or costly operations: request limits.
• New or changed DAO/core operations or handlers, and any other operation with a span: telemetry. Apply this to reviews even when the existing code lacks a span. Every operation that fails reports its error on its own span.
• A new service, or a change to the spans, tables or promises it exposes: its Grafana coverage in infra, as write-infra's Grafana coverage describes.
• Tests, regression coverage, or test review: layer test patterns, alongside write-go-tests. DAO integration tests and generated mocks remain required where applicable.

Consumer-owned interfaces and the mandated layer boundaries earn their place even with one implementation. Simplify within them using prefer-small-solutions; do not flatten the architecture.

After every edit

Run the base loop from write-go (pnpm generate:go when interfaces/proto changed → pnpm format:go → pnpm lint:go), then:

1. write-go-tests — follow develop-feature for timing: focused checks and necessary tests during drafting, full relevant behavioral coverage after issue scope approval. Run affected suites before readiness; do not add tests simply because a file was touched.
2. document-code — doc comments for every symbol added or changed.
3. If a REST handler change alters the public API contract (new endpoint, changed parameters, changed response shape, added/removed status codes), invoke write-openapi to update openapi.yaml. The spec is a durable public commitment; drift breaks clients.

Project structure

cmd/                   # Main targets (one binary per subdirectory)
internal/
  config/              # Static configuration types + env-driven presets
  lib/                 # Minimal internal utilities (keep as small as possible — ideally empty)
  dao/                 # Data access layer (postgres, external sources)
  core/                # Business logic layer
  handlers/            # Transport layer (REST, gRPC)
  models/
    migrations/        # SQL migrations (up/down pairs)
    proto/             # Protobuf definitions
pkg/go/                # Exported Go client library (only if another service consumes this one)

Layer import direction is one-way and strict:

config   →  (no imports from internal layers)
lib      →  (no imports from internal layers)
dao      →  config, lib
core     →  config, lib, dao   (via interfaces only)
handlers →  config, lib, core   (via interfaces only)
cmd      →  all layers (wires everything together)

Handlers never import dao directly. Core never imports handlers. No circular imports. Proto-generated types never enter the core or dao layers — handlers own all proto↔core conversion.

Static data definitions

Never inline a production static data definition in Go. Keep JSON Schemas, prompt templates, policy documents, and other declarative payloads in their native-format files, then embed them with //go:embed. Go owns loading and typing; the native file owns the definition. Small scalar constants remain code.

Place embedded production definitions by audience:

• internal/config/ — definitions internal to service behavior and not exposed to users.
• internal/models/ — definitions that shape user-facing data or contracts.

Expose each definition through a small package near its files. The binary remains self-contained; production code never reads definitions relative to its working directory.

File names

write-go already mandates camelCase for multi-word file names. Within a service, the layer/role prefix is fixed — match the existing files exactly:

Handlers use rest, never http — in file names and type names. Files named http.* and types prefixed Http are legacy; rename them when they come into scope (see Active Migrations).

Type names

The interface + implementation pattern

Every file in dao/, core/, and handlers/ exports exactly one struct implementation; the struct name mirrors the file name (camel-cased). The file also defines the dependency interfaces that implementation needs, though not every layer has them:

// File: core/userSearch.go

// UserSearchDao is the DAO interface this service depends on (defined here, not in dao/).
type UserSearchDao interface {
    Exec(ctx context.Context, request *dao.UserSearchRequest) ([]*dao.User, error)
}

// UserSearch searches for users matching the given criteria.
type UserSearch struct {
    dao UserSearchDao
}

// UserSearchRequest carries the inputs for [UserSearch.Exec].
type UserSearchRequest struct {
    Name string
}

func (s *UserSearch) Exec(ctx context.Context, request *UserSearchRequest) ([]*User, error) {
    // ...
}

func NewUserSearch(dao UserSearchDao) *UserSearch {
    return &UserSearch{dao: dao}
}

Key rules:

• One exported struct per file; its name mirrors the file name.
• Interfaces proxy the imported package — always defined by the consumer, never the producer. A service that imports dao.PgUserSearch does not use that concrete type directly; it declares a local UserSearchDao interface describing only the methods it needs. The DAO package has no interface of its own. The consumer owns the contract and the producer satisfies it, so neither layer forces the other to import it. The one accepted exception is genai's connector registry, described under lib.
• One method per interface, named Exec. Idiomatic Go names interface methods after what they do; this is a deliberate project standard that trades that for consistency. Follow it.
• The method signature is (ctx context.Context, request *XxxRequest) (Result, error) — Result is a struct pointer, slice, or named type, never a bare primitive, so fields can be added later without breaking callers. A check returns its one answer bare, since that answer never grows a field: an existence or ownership DAO returns bool.
• Exceptions in handlers: gRPC method signatures are protoc-generated; REST handlers implement ServeHTTP(w, r). Both are accepted exceptions to the Exec shape.
• Service and DAO types are stateless after construction — every field is set by New* and never mutated, so every type is safe for concurrent use without synchronization. This is a requirement.
• Shared sentinels/types within a layer go in that layer's single common.go (one per layer at most), never duplicated across files.

Security

write-go covers secrets hygiene (never log/trace/return key material; constant-time secret comparison; equalize auth-miss timing) and the "use established crypto, never roll your own" rule — all of which apply here. The service-specific additions:

• Validate at the core layer. Handlers reject only structurally malformed input (unparseable UUID); inputs that parse but are semantically wrong (blank required string, out-of-range value, value outside a known set) are rejected in the core layer with ErrInvalidRequest. Bound every length that feeds storage or a downstream system.
• No string-built SQL — ever. Every DAO query is //go:embed-ed from a .sql file and run through bun's parameterized API (NewRaw(query, args...)). The embed pattern keeps SQL visible and reviewable; do not move SQL into Go string literals to sidestep it. (See write-sql.)
• No error-information disclosure in REST responses. Map to a generic status text (http.StatusText(...)); the helper does this for you. Structured bodies count too — a health/status JSON body carries a binary state ("up" / "down") and at most a stable error code, never err.Error(): a wrapped DB error routinely contains hostnames, ports and schema names, so one err.Error() on a downed dependency leaks topology to an unauthenticated caller. Log/trace the full error; return only the public shape. Richer detail goes on a separate, auth-gated endpoint. gRPC (internal) tolerates slightly more context in status messages but still no raw DB/crypto detail.
• Transport boundaries. REST is public — anything in a REST response may reach an end user or be logged by an intermediary; return only what the client is entitled to. gRPC is internal — route all external traffic through REST, never expose gRPC directly.
• A security gate never turns itself off on empty configuration. An unset issuer, caller list or key stops the process at startup, and only an explicit opt-out that production never sets starts it without the gate. json-keys' gRPC server refuses to start without SERVICE_TOKEN_ISSUER unless SERVICE_ISSUER_OPTIONAL is true, which only its standalone gRPC image and the CI smoke runs set, and a table test of cmd/grpc's newServer covers the three cases.

Active migrations

Apply these when a file is already in scope — never speculatively:

A repo that has not yet taken the rename is migrated in its own session. Do not migrate one piecemeal as a side effect of another change.

Common pitfalls

(write-go lists the language-level ones — context-in-struct, new deps without asking, logging secrets, multiple time.Now(), bare return nil, ErrXxx from a layer with a span, new(T), discarding errors. These are the service-architecture ones, each stated in full in its section above:)

• HTTP/gRPC concerns in a core file — http.Error, json.Marshal, status.Errorf → move to the handler.
• dao imported in handlers. Handlers depend on core components via interfaces; a handler that needs a DAO sentinel checks the core re-export core.ErrXxx (in core/common.go if shared).
• Inline SQL instead of a //go:embed-ed .sql file, or a query built with fmt.Sprintf instead of bun parameters.
• Hand-written mocks. Mocks are mockery-generated from the interfaces in each file; run pnpm generate:go after adding/changing an interface.
• http in new file or type names instead of rest.
• Raw error detail in a REST response, including in a structured JSON field.
• Validation in handlers instead of the core layer.
• A span on a constructor or config loader.
• A transaction started in a handler instead of the core layer or cmd/.