go-client

Implement or review the client layer for $ARGUMENTS following the specs below exactly.

Service Architecture — Overview

This document describes the top-level structure for a service in this project. Before building any layer, read this file. Then read the spec file for the specific layer you are implementing.

---

Directory Structure

Every service follows this layout:

services/<name>/
├── main.go         # Env validation, dependency wiring, server start
├── handler/
│   └── handler.go  # Transport layer
├── service/
│   └── service.go  # Business logic
├── database/
│   └── database.go # Data access
├── client/
│   └── client.go   # Outbound clients to other services or APIs
├── types/
│   └── types.go    # Local interfaces for every dependency
└── Dockerfile

Each directory is its own Go package named after the directory.

---

Build Order

Implement layers in this order. Each layer depends on the one before it.

1. types/ — define all interfaces first so every other layer has a contract to depend on
2. database/ — implement the data access layer against the Database interface
3. client/ — implement any outbound clients against their interfaces
4. service/ — implement business logic using only the interfaces from types/
5. handler/ — implement the transport layer using only the Service interface from types/
6. main.go — wire all concrete implementations together and start the server

---

Core Principles

Depend on interfaces, not implementations. Every layer holds its dependencies as interfaces from types/. Nothing is imported directly from sibling packages except in main.go.

Inject all dependencies through constructors. All dependencies are passed into New* functions. Nothing is instantiated inside the service or handler.

One responsibility per layer. Transport logic does not touch the database. Business logic does not build queries. Queries do not make outbound calls.

Crash on bad config, log on recoverable errors. Missing environment variables are fatal at startup. Cache failures and best-effort side effects are logged and swallowed. Anything that prevents a correct response is returned as an error.

Shared infrastructure lives in services/common. Reusable clients, interfaces, and domain models are defined there and imported. Never copy infrastructure code into a service.

---

Layer Spec — types/types.go

Responsibility

Define the interfaces that every other layer in the service depends on. This file is the contract layer — it describes what each dependency must provide without specifying how.

---

Rules

• One interface per dependency: Service, Database, SomeClient, etc.
• The Service interface must exactly match the public methods implemented on the service struct — the handler depends on it
• No concrete types, no structs, no implementation details — interfaces only
• Shared domain models used across multiple services (e.g. common database models, queue message types) live in services/common and are imported here as needed
• Do not import from sibling packages (handler, service, database, client) — only from services/common and standard libraries

---

Pattern

package types

import (
    "context"

    commontypes "github.com/kabradshaw1/story/services/common"
    "github.com/kabradshaw1/story/services/common/genproto/<name>"
)

type Service interface {
    MethodOne(ctx context.Context, req *proto.Request) (*proto.Response, error)
    MethodTwo(ctx context.Context, req *proto.Request) (*proto.Response, error)
}

type Database interface {
    FindRecord(ctx context.Context, id int) (*commontypes.SomeModel, error)
    SaveRecord(ctx context.Context, record commontypes.SomeModel) error
}

type SomeClient interface {
    Notify(ctx context.Context, payload SomePayload) error
}

---

Checklist

• One interface defined for each dependency the service layer requires
• Service interface matches the service struct's public methods exactly
• No concrete types or structs defined here
• All shared domain types imported from services/common, not redefined

---

Layer Spec — client/client.go

Responsibility

Handle all outbound calls to external services or third-party APIs. This is the only layer that makes outbound network requests.

---

Rules

• Wraps the underlying transport (HTTP client, gRPC connection, SDK, etc.) in a struct
• A New* constructor initializes and returns the client struct
• Every method accepts context.Context as its first argument and passes it to the underlying call
• Validate required inputs before making any call — return an error immediately for missing or invalid fields
• Return a descriptive error for any non-success response from the remote
• No business logic — only request construction, sending, and response validation

---

Pattern

package client

type SomeClient struct {
    // underlying transport (http.Client, grpc.ClientConn, etc.)
}

func New() *SomeClient {
    return &SomeClient{
        // initialize transport
    }
}

func (c *SomeClient) Notify(ctx context.Context, payload SomePayload) error {
    if payload.RequiredField == "" {
        return fmt.Errorf("RequiredField is required")
    }
    // construct and send request using ctx
    // check response and return error on failure
    return nil
}

---

Checklist

• Underlying transport is wrapped in a struct, not used directly
• New* constructor initializes the transport
• Every method accepts and passes through context.Context
• Required inputs are validated before the call is made
• Non-success responses from the remote return a descriptive error
• No business logic, no database access, no cache access