Conventions

• Service methods — take context.Context as first arg; cancel on context expiry.
• CLI commands — synchronous cobra RunE bodies; long-running work goroutined inside via errgroup.
• API handlers — synchronous http.HandlerFunc bodies; long-running work uses the operation registry + SSE.
• Database operations — *sql.DB is goroutine-safe; queries thread the request context so cancellation propagates.

// Service
type Service struct{ /* … */ }

func (s *Service) CreateBackup(ctx context.Context, stack string) (*BackupModel, error) {
    // …
}

// CLI handler
func newBackupCommand() *cobra.Command {
    return &cobra.Command{
        Use:   "backup <stack>",
        Args:  cobra.ExactArgs(1),
        RunE:  func(cmd *cobra.Command, args []string) error {
            return runBackup(cmdCtx(cmd), args[0])
        },
    }
}

• Request types — *Request or *Create / *Update suffix
• Response types — *Response suffix
• Internal model types — *Model suffix
• Wire envelopes — capitalised generic alias on api.MethodResponse[T] / api.DocResponse[T]

type BackupCreate struct {
    StackName    string `json:"stack_name"`
    IncludeVault bool   `json:"include_vault,omitempty"`
}

type BackupResponse struct {
    ID         string    `json:"id"`
    CreatedAt  time.Time `json:"created_at"`
    SizeBytes  int64     `json:"size_bytes"`
}

• Table names — singular, lowercase (deployment, backup)
• Go model names — *Model suffix
• Always include — created_at, updated_at columns (Atlas generates both)

type DeploymentModel struct {
    ID         int       `json:"id"`
    Name       string    `json:"name"`
    TenantName string    `json:"tenant_name"`
    // ...
    CreatedAt  time.Time `json:"created_at"`
    UpdatedAt  time.Time `json:"updated_at"`
}

• Method-style endpoints — POST /api/method/shc.{module}.{operation}
• Resource-style endpoints — GET|POST|PUT|DELETE /api/resource/{Resource}[/{id}]

• YAML files — Use snake_case for all keys
• Environment vars — Use SHC_ prefix, SCREAMING_CASE
• CLI flags — Use --kebab-case

# config.yaml (snake_case)
log_level: debug
max_backup_size: 10G

# CLI (kebab-case)
shc backup create --include-vault --max-size 10G

gofmt enforces three groups separated by blank lines: stdlib, third-party, internal.

package backup

import (
    "context"
    "fmt"
    "time"

    "github.com/go-chi/chi/v5"

    "gitlab.com/bitspur/selfhosted-cloud/ce/core/coded"
    "gitlab.com/bitspur/selfhosted-cloud/ce/core/validation"
)