Go services

go.work
shared/foundation/       module "pkg"     — framework-agnostic shared libraries
  core/                  the ports: ReqCtx, Router, DataSource, StorageProvider, EmailSender
  integration/           the adapters that implement them: echo, bun, cache, email, …
  jobs/  bus/  httpx/  util/  tests/
shared/features/         module "shared"  — cross-service features, server bootstrap, allow, testutil
services/<name>/         module each      — one deployable domain service
tooling/architecture/    the boundary checks

services/catalog/
  cmd/server/main.go                      the FX composition root
  config/main.go                          the version and the embedded migrations
  config/db/migrations/tenant/postgres/   001_baseline.up.sql, 001_baseline.down.sql, 002_…
  internal/features/module.go             the one file listing every feature module
  internal/features/<feature>/            core/ inbound/ outbound/ module.go acceptance_test.go
  internal/testutil/                      this service's fake test app and helpers
  service.go                              the service as one composable fx.Option
  docs/                                   generated swagger

package config

import "embed"

var Version = "dev"

//go:embed all:db/migrations/tenant
var TenantMigrations embed.FS

features/projects/
  core/        entity.go  ports.go  errors.go  service.go    ← no framework imports
  inbound/     handler.go routes.go types.go
  outbound/    repository.go  models.go  project_checker.go  ← DB row structs live here
    memory/    repository.go                                  ← the in-memory store tests use
  module.go    the fx.Module
  acceptance_test.go

// Repository defines the persistence interface for projects.
type Repository interface {
	Create(ctx context.Context, project *Project) error
	GetByID(ctx context.Context, workspaceID, id string) (*Project, error)
	Update(ctx context.Context, project *Project) error
	Delete(ctx context.Context, workspaceID, id string) error
	List(ctx context.Context, workspaceID string, filter ListProjectsFilter, offset, limit int) ([]*Project, int64, error)
	ExistsByName(ctx context.Context, workspaceID, name string, excludeID *string) (bool, error)
}

type Service struct {
	repo  Repository
	clock clock.Clock
	ids   ids.Generator
}

func NewService(repo Repository, clk clock.Clock, gen ids.Generator) *Service {
	return &Service{repo: repo, clock: clk, ids: gen}
}

// Create validates and creates a new project.
func (s *Service) Create(ctx context.Context, workspaceID string, input *CreateProjectInput) (*Project, error) {
	if err := s.validateCreate(input); err != nil {
		return nil, err
	}
	name := strings.TrimSpace(input.Name)
	exists, err := s.repo.ExistsByName(ctx, workspaceID, name, nil)
	if err != nil {
		return nil, err
	}
	if exists {
		return nil, ErrDuplicateName
	}
	now := s.clock.Now()
	project := &Project{
		ID: s.ids.New("prj"), WorkspaceID: workspaceID, Name: name,
		Country:   strings.ToUpper(strings.TrimSpace(input.Country)),
		StartDate: input.StartDate, EndDate: input.EndDate,
		Status: StatusActive, CreatedAt: now, UpdatedAt: now,
	}
	if err := s.repo.Create(ctx, project); err != nil {
		return nil, err
	}
	return project, nil
}

// GetByID is a lookup, not a decision: it passes straight through.
func (s *Service) GetByID(ctx context.Context, workspaceID, id string) (*Project, error) {
	return s.repo.GetByID(ctx, workspaceID, id)
}

// Repository implements core.Repository on tenant-scoped transactions.
type Repository struct {
	ds pcore.DataSource
}

func NewRepository(ds pcore.DataSource) core.Repository {
	return &Repository{ds: ds}
}

func (r *Repository) GetByID(ctx context.Context, workspaceID, id string) (*core.Project, error) {
	conn, err := r.ds.Tx(ctx) // tenant-scoped; needs TxRequired on the route
	if err != nil {
		return nil, err
	}
	var model projectModel
	if err := conn.FindBy(&model, "id = ? AND workspace_id = ?", id, workspaceID); err != nil {
		if db.IsNotFound(err) {
			return nil, core.ErrProjectNotFound // the feature's not-found, never nil, nil
		}
		return nil, err
	}
	return toEntity(&model), nil
}

package outbound

import (
	"time"

	"github.com/uptrace/bun"

	"catalog/internal/features/projects/core"
)

type projectModel struct {
	bun.BaseModel `bun:"table:projects"`

	ID          string     `bun:"id,pk"`
	WorkspaceID string     `bun:"workspace_id,notnull"`
	Name        string     `bun:"name,notnull"`
	Country     string     `bun:"country,notnull"`
	Status      string     `bun:"status,notnull"`
	StartDate   *time.Time `bun:"start_date,type:date"`
	EndDate     *time.Time `bun:"end_date,type:date"`
	CreatedAt   time.Time  `bun:"created_at,notnull"`
	UpdatedAt   time.Time  `bun:"updated_at,notnull"`
	DeletedAt   *time.Time `bun:"deleted_at,soft_delete,nullzero"`
}

func toEntity(m *projectModel) *core.Project {
	return &core.Project{
		ID: m.ID, WorkspaceID: m.WorkspaceID, Name: m.Name, Country: m.Country,
		Status: core.Status(m.Status), StartDate: m.StartDate, EndDate: m.EndDate,
		CreatedAt: m.CreatedAt.UTC(), UpdatedAt: m.UpdatedAt.UTC(),
	}
}

func fromEntity(e *core.Project) *projectModel {
	return &projectModel{
		ID: e.ID, WorkspaceID: e.WorkspaceID, Name: e.Name, Country: e.Country,
		Status: string(e.Status), StartDate: e.StartDate, EndDate: e.EndDate,
		CreatedAt: e.CreatedAt, UpdatedAt: e.UpdatedAt,
	}
}

// tasks/core/ports.go
// ProjectChecker answers whether a project exists.
type ProjectChecker interface {
	ProjectExists(ctx context.Context, workspaceID, id string) (bool, error)
}

// tasks/outbound/project_checker.go
type ProjectCheckerAdapter struct {
	repo projectscore.Repository
}

func NewProjectChecker(repo projectscore.Repository) core.ProjectChecker {
	return &ProjectCheckerAdapter{repo: repo}
}

func (a *ProjectCheckerAdapter) ProjectExists(ctx context.Context, workspaceID, id string) (bool, error) {
	_, err := a.repo.GetByID(ctx, workspaceID, id)
	if errors.Is(err, projectscore.ErrProjectNotFound) {
		return false, nil
	}
	if err != nil {
		return false, err
	}
	return true, nil
}

// features/popularsearches/module.go
var Module = fx.Options(
	fx.Provide(func() core.ScopeCatalog { return catalog{} }),
	sharedpopular.Module(sharedpopular.Config{
		PruneJob:     PruneJob,
		PruneSubject: "catalog-popular-searches-prune",
	}),
	fx.Invoke(registerRoutes),
)

type WebhookPublisherStub struct{}

func NewWebhookPublisherStub() core.WebhookPublisher { return &WebhookPublisherStub{} }

func (s *WebhookPublisherStub) PublishPaymentCompleted(context.Context, *core.PaymentIntent) error {
	return nil
}

package projects

import (
	"go.uber.org/fx"

	pcore "pkg/core"

	"catalog/internal/features/projects/core"
	"catalog/internal/features/projects/inbound"
	"catalog/internal/features/projects/outbound"
)

var Module = fx.Module("projects",
	fx.Provide(
		outbound.NewRepository, // port ← adapter
		core.NewService,        // takes the port, the clock and the id generator
		inbound.NewHandler,     // takes the service
	),
	fx.Invoke(registerRoutes),
)

type registerRoutesParams struct {
	fx.In
	Router  pcore.Router
	Handler *inbound.Handler
	DS      pcore.DataSource
}

func registerRoutes(p registerRoutesParams) {
	inbound.RegisterRoutes(p.Router, p.Handler, p.DS)
}

type CreateProjectRequest struct {
	WorkspaceID string  `param:"workspaceId" json:"-" validate:"required"`
	Name        string  `json:"name" validate:"required"`
	Country     string  `json:"country" validate:"required"`
	StartDate   *string `json:"startDate,omitempty"`
	EndDate     *string `json:"endDate,omitempty"`
}

func (r *CreateProjectRequest) ToInput() (*core.CreateProjectInput, error) {
	start, err := parseDate(r.StartDate)
	if err != nil {
		return nil, err
	}
	end, err := parseDate(r.EndDate)
	if err != nil {
		return nil, err
	}
	return &core.CreateProjectInput{Name: r.Name, Country: r.Country, StartDate: start, EndDate: end}, nil
}

// Package memory is the project table held in a map. It is the adapter the faked HTTP tests put in
// place of the PostgreSQL repository beside it, and it keeps that repository's rules: a project is
// only reachable through its own workspace, a deleted one is gone from every read, names are unique
// per workspace, and lists come back ordered by name.
//
// It lives beside the real adapter rather than in a _test file so any test in the service can
// import it, and it never reaches production because no module provides it.
package memory

// internal/features/module.go
var Module = fx.Options(
	health.Module(config.Version),
	tenants.Module,
	settings.Module,
	categories.Module,
	search.Module(search.Config{Product: "catalog", ReconcileJob: "catalog.search.reconcile"}),
	projects.Module,
	tasks.Module,
	popularsearches.Module,
)

// Command server runs the catalog service.
package main

import (
	"go.uber.org/fx"

	"shared/server"

	"catalog/config"
	"catalog/internal/features"
)

func main() {
	opts := []fx.Option{
		server.CoreModule("catalog", &config.TenantMigrations), // infrastructure
		server.ServerModule,    // transport
		features.Module,        // domain
		server.LifecycleModule, // start/stop
	}
	fx.New(opts...).Run()
}

// Provide a struct as an interface the graph asks for.
fx.Annotate(
	providePublicDBTransactionManager,
	fx.As(new(core.TransactionManager)),
),

// Two values of the same type in the graph — name them.
fx.Annotate(
	func() *embed.FS { return tenantMigrations },
	fx.ResultTags(`name:"tenantMigrations"`),
),
fx.Annotate(
	provideTenantSchemaManager,
	fx.ParamTags(``, `name:"tenantMigrations"`),
),

var LifecycleModule = fx.Options(
	fx.Provide(NewServer),
	fx.Invoke(registerLifecycle),
)

func registerLifecycle(lc fx.Lifecycle, srv *Server, ds core.DataSource) {
	lc.Append(fx.Hook{
		OnStart: func(ctx context.Context) error {
			go srv.Start()
			return nil
		},
		OnStop: func(ctx context.Context) error {
			if err := srv.Shutdown(ctx); err != nil {
				return err
			}
			if ds != nil {
				return ds.Close()
			}
			return nil
		},
	})
}

func (h *Handler) Create(c pcore.ReqCtx, req CreateProjectRequest) error {
	input, err := req.ToInput()
	if err != nil {
		return c.BadRequest("invalid date format, expected YYYY-MM-DD")
	}

	project, err := h.service.Create(c.Context(), req.WorkspaceID, input)
	if err != nil {
		return err // coded errors answer their own status; anything else is a logged 500
	}
	return c.Created(toResponse(project))
}

package inbound

import (
	pcore "pkg/core"
	"pkg/integration/router"
	"shared/allow"
)

func RegisterRoutes(r pcore.Router, h *Handler, ds pcore.DataSource) {
	g := r.Group("/workspaces/:workspaceId/projects",
		router.TenantRequired(),
		router.TxRequired(ds),
	)
	g.POST("", allow.Staff(allow.Member).To(h.Create))
	g.GET("", allow.Staff(allow.Viewer).To(h.List))
	g.GET("/:id", allow.Staff(allow.Viewer).To(h.GetByID))
	g.PUT("/:id", allow.Staff(allow.Member).To(h.Update))
	g.DELETE("/:id", allow.Staff(allow.Member).To(h.Delete))
}

// Package allow is the one place a service decides who may call a route.
//
// A route states its rule where it is registered, in one line, and the layer does the rest: the
// router resolves who the caller is and their live role on the tenant's own team, and the rule
// refuses with a coded error the router answers.
//
//	g.GET("", allow.Staff(allow.Viewer).To(h.List))
//	g.POST("", allow.Staff(allow.Member).To(h.Create))
//
// A feature never reads a role itself. A route that declares no rule stops its service from
// starting.
package allow

err := s.txManager.RunInTransaction(ctx, func(txCtx context.Context) error { … })

// EmailSender sends emails.
type EmailSender interface {
	Send(ctx context.Context, msg *EmailMessage) error
}

// EmailSenderFactory gives the sender of the tenant in ctx.
type EmailSenderFactory interface {
	GetSender(ctx context.Context) (EmailSender, error)
}

// EmailProviderFactory is a pure function that creates a sender from a tenant's config.
// The feature layer fetches the config and calls it.
type EmailProviderFactory func(config *EmailConfig) (EmailSender, error)

// NewFakeTestApp boots this service in-process with every outside dependency faked, a clock stopped
// at FakeNow and counting ids. stores are one fx.Decorate per repository port the test replaces
// with an in-memory fake. TEST_DATABASE_URL decides whether they apply (unset or "memory") or the
// real repositories run on a temporary PostgreSQL database (a postgres:// URL).
func NewFakeTestApp(t *testing.T, stores ...fx.Option) *FakeTestApp {
	t.Helper()
	return sharedtest.NewFakeTestApp(t, serviceModules(), stores...)
}