Go Maintainable Code Skill

This skill ensures all Go code follows Clean Architecture principles and project-specific patterns used in ChecklistApplication.

Core Principles

1. Clean Architecture Layers (CRITICAL)

Dependency Flow: server → service → repository

internal/
├── server/           # HTTP layer (Gin, OpenAPI controllers)
│   └── Depends on: service (via interfaces)
├── core/
│   ├── service/      # Business logic (framework-independent)
│   │   └── Depends on: repository interfaces, domain
│   ├── domain/       # Entities, value objects (no dependencies)
│   └── repository/   # Repository interfaces (no implementation)
└── repository/       # PostgreSQL implementations
    └── Depends on: repository interfaces, domain

Rules:

• ✅ Server calls service interfaces
• ✅ Service calls repository interfaces
• ✅ Domain has NO external dependencies
• ❌ NEVER import concrete types across layers
• ❌ NEVER import internal/repository from internal/core/service

2. Interface-Based Design

Pattern from codebase:

// Define interface in core/repository
package repository
type IChecklistService interface {
    DeleteChecklistById(ctx context.Context, id uint) domain.Error
}

// Implement in core/service
package service
type checklistService struct {
    repository repository.IChecklistRepository  // Interface, not concrete
}

// Wire provides concrete implementation
// internal/deployment/wire.go

3. Dependency Injection via Wire

ALWAYS use Wire for dependencies:

// Add to internal/deployment/wire.go
func InitializeApp() (*App, error) {
    wire.Build(
        // ... existing providers ...
        NewMyService,           // Add your constructor
        wire.Bind(new(IMyService), new(*myService)),
    )
    return nil, nil
}

Then run:

./generate.sh  # Regenerates wire_gen.go

Code Quality Standards

Error Handling

Use domain.Error (custom error type):

// ✅ Good
func (s *service) Delete(ctx context.Context, id uint) domain.Error {
    if err := s.repo.Delete(ctx, id); err != nil {
        return domain.Wrap(err, "failed to delete", 500)
    }
    return nil
}

// ❌ Bad - using standard error
func (s *service) Delete(ctx context.Context, id uint) error {
    return errors.New("something failed")
}

Error patterns:

• Return domain.Error from service/repository methods
• Use domain.NewError(message, statusCode) for new errors
• Use domain.Wrap(err, context, statusCode) to wrap errors
• Guard rails return 404 for access denied (security pattern)

Context Usage

Extract user context:

// In service layer
userId, err := domain.GetUserIdFromContext(ctx)
if err != nil {
    return err
}

// Guard rail checks
if err := s.checklistOwnershipChecker.HasAccessToChecklist(ctx, checklistId); err != nil {
    return error.NewChecklistNotFoundError(checklistId)
}

Extract client ID (for SSE):

// In controller
clientId := serverutils.GetClientIdFromContext(ctx)

Transaction Handling

Use connection.RunInTransaction:

runQueryFunction := func(tx pool.TransactionWrapper) (ResultType, error) {
    // Execute queries using tx, not connection
    result, err := tx.Exec(ctx, query, args)
    return processedResult, err
}

res, err := connection.RunInTransaction(connection.TransactionProps[ResultType]{
    Query:      runQueryFunction,
    Connection: r.connection,
    TxOptions:  pgx.TxOptions{IsoLevel: pgx.Serializable},
})

Testing Requirements

Every service method needs tests:

func TestMyService_MethodName_SuccessCase(t *testing.T) {
    // Arrange
    mockRepo := new(mockRepository)
    mockRepo.On("Method", mock.Anything, expectedArgs).Return(expectedResult, nil)

    svc := &myService{repository: mockRepo}

    // Act
    result, err := svc.Method(context.Background(), args)

    // Assert
    if err != nil {
        t.Fatalf("unexpected error: %v", err)
    }
    mockRepo.AssertExpectations(t)
}

Test patterns:

• Success case
• Error cases
• Guard rail failures
• Edge cases (nil, empty, boundary values)

See testing-guide.md for complete examples.

Project-Specific Patterns

1. OpenAPI-First Development

Workflow:

1. Update openapi/api_v1.yaml with new operation
2. Run ./generate.sh to generate server interfaces
3. Implement generated interface in controller
4. NEVER edit *_gen.go files manually

Example:

# openapi/api_v1.yaml
paths:
  /api/v1/checklists/{checklistId}/archive:
    post:
      operationId: archiveChecklist
      # ... rest of spec

// internal/server/v1/checklist/controller.go
// Implements generated ServerInterface
func (c *controller) ArchiveChecklist(ctx context.Context, req ArchiveChecklistRequestObject) (ArchiveChecklistResponseObject, error) {
    // Implementation
}

2. SSE Notifications

After mutations, publish events:

func (s *service) Delete(ctx context.Context, id uint) domain.Error {
    if err := s.repository.Delete(ctx, id); err != nil {
        return err
    }

    // Publish SSE event
    s.notifier.NotifyItemDeleted(ctx, checklistId, id)
    return nil
}

SSE patterns:

• Events filtered by Client ID (no echo to originating client)
• Non-blocking publish with buffered channels
• Guard rail check on subscribe

3. Database Patterns

Doubly-linked list ordering:

// Items use NEXT_ITEM_ID/PREV_ITEM_ID
// Use recursive CTE view: CHECKLIST_ITEMS_ORDERED_VIEW
// Phantom items: IS_PHANTOM = true, filtered in queries

CASCADE constraints:

FOREIGN KEY (parent_id) REFERENCES parent(id) ON DELETE CASCADE

Named arguments (pgx):

args := pgx.NamedArgs{
    "checklist_id": id,
    "user_id":      userId,
}
result, err := tx.Exec(ctx, "DELETE FROM t WHERE id = @checklist_id", args)

4. Struct Constructors

Private structs with public interfaces:

// Public interface
type IMyService interface {
    DoSomething(ctx context.Context) error
}

// Private implementation
type myService struct {
    repo repository.IMyRepository
}

// Public constructor for Wire
func NewMyService(repo repository.IMyRepository) IMyService {
    return &myService{repo: repo}
}

Anti-Patterns to Avoid

❌ Don't Do This

// ❌ Importing concrete types across layers
import "com.raunlo.checklist/internal/repository"

// ❌ Business logic in controllers
func (c *controller) Delete(ctx context.Context, req Request) Response {
    // Validating, processing here - NO!
}

// ❌ SQL in service layer
func (s *service) Find(ctx context.Context) {
    rows, _ := db.Query("SELECT ...") // NO!
}

// ❌ Not using guard rails
func (s *service) Delete(ctx context.Context, id uint) {
    return s.repo.Delete(ctx, id) // Missing access check!
}

// ❌ Hardcoded dependencies
type service struct {
    repo *postgresRepo  // Should be interface
}

// ❌ Ignoring errors
s.repo.Delete(ctx, id)  // No error handling

// ❌ Empty error messages
return domain.NewError("", 500)

✅ Do This Instead

// ✅ Interface imports only
import "com.raunlo.checklist/internal/core/repository"

// ✅ Thin controllers
func (c *controller) Delete(ctx context.Context, req Request) Response {
    domainCtx := serverutils.CreateContext(ctx)
    if err := c.service.DeleteById(domainCtx, req.Id); err != nil {
        return mapError(err)
    }
    return success()
}

// ✅ SQL in repository layer
func (r *repo) Find(ctx context.Context) ([]Entity, domain.Error) {
    rows, err := r.connection.Query(ctx, query)
    // ...
}

// ✅ Guard rail checks
func (s *service) Delete(ctx context.Context, id uint) domain.Error {
    if err := s.guardrail.HasAccessToChecklist(ctx, id); err != nil {
        return error.NewChecklistNotFoundError(id)
    }
    return s.repo.Delete(ctx, id)
}

// ✅ Interface dependencies
type service struct {
    repo repository.IMyRepository  // Interface
}

// ✅ Proper error handling
if err := s.repo.Delete(ctx, id); err != nil {
    return domain.Wrap(err, "failed to delete checklist", 500)
}

// ✅ Descriptive errors
return domain.NewError("Checklist is not empty", 400)

Checklist for New Code

Before submitting code, verify:

• Follows Clean Architecture (correct layer separation)
• Uses interfaces for dependencies
• Added to Wire configuration if new service/repo
• Ran ./generate.sh if OpenAPI changed
• Proper error handling (domain.Error)
• Guard rail checks for authorization
• SSE notifications for mutations (if applicable)
• Unit tests with mocks (testify)
• No magic numbers or strings
• Context passed through all layers
• Ran go test ./... and all pass
• Ran go build ./... successfully
• No TODO comments without issue number

See code-review-checklist.md for complete review guide.

Quick Reference

Common commands:

./generate.sh           # OpenAPI + Wire code generation
go test ./...          # Run all tests
go build ./...         # Build all packages
go test ./internal/core/service -v -run TestMyTest  # Run specific test

File locations:

• Controllers: internal/server/v1/
• Services: internal/core/service/
• Service interfaces: internal/core/repository/
• Repository impls: internal/repository/
• Domain entities: internal/core/domain/
• SQL queries: internal/repository/query/
• Wire config: internal/deployment/wire.go
• OpenAPI spec: openapi/api_v1.yaml

Related Documentation

• Go Patterns - Language-specific best practices
• Testing Guide - Comprehensive testing examples
• Code Review Checklist - Quality checklist
• Project: CLAUDE.md - Full architecture guide