go-bootstrap

Wire a new clean-arch feature into the app — DI and route registration under internal/bootstrap/, internal/bootstrap/registry/, and cmd/api/main.go. Use when adding a feature's Setup() wiring, adding

SKILL.md

GitHub

Go Bootstrap & Dependency Injection

Authoritative description of the wiring layer that ties handler + usecase + repository together for a feature, and the three places new wiring can land. Read this before adding a new clean-arch feature end-to-end, or before touching route registration order in cmd/api/main.go.

When to use

  • Adding internal/bootstrap/{feature}/setup.go for a new feature.
  • Adding a new repository accessor to internal/bootstrap/registry/registry.go.
  • Deciding which of the three bootstrap.Setup* entrypoints a new route belongs to.
  • Touching cmd/api/main.go (logger/gin/middleware setup, legacy wiring).

The pieces and how they fit

cmd/api/main.go
  run()
    configureLogger()                -> log.Logger
    setupGin(logger, db)              -> *gin.Engine, authentication.Authenticator
      health.Register                  (unauthenticated: /healthz, /readyz)
      r.GET("/ping")                    (unauthenticated)
      bootstrap.SetupInternalJobs        (own auth: x-api-key, under /jobs)
      bootstrap.SetupPublicComponents     (unauthenticated: webhooks, etc.)
      r.Use(authenticator.Authenticate())  <-- everything registered AFTER this needs a Firebase user_token
      r.Use(authentication.LazyProvisionUser(...))
    <legacy v1 wiring, inline>          (registered after auth -> protected)
    bootstrap.SetupCleanArchComponents(r, db, authenticator)
      -> {feature}.Setup(r, reg) per clean-arch feature:
           reg.Get{X}Repository()  ->  usecase.New{Entity}(...)  ->  api.New{Entity}V2Handlers(r, &svc)

Non-negotiable rules

cmd/api/main.go

  • Keep run() as orchestration only: load env, configure logger, init metrics, open the DB, call setupGin, wire legacy v1 (the existing inline calls — don't add to this, it's migration debt), call bootstrap.SetupCleanArchComponents, start the server.
  • Pull any standalone concern into its own top-level function (configureLogger, setupGin, ping) instead of growing run(). setupGin itself owns: engine creation, recovery/logging/metrics/CORS middleware, health checks, /ping, internal jobs, public components, then the auth middleware — in that order.
  • Route registration order inside setupGin decides auth. Anything registered before r.Use(authenticator.Authenticate()) is unauthenticated by default (health, /ping, jobs, public webhooks); anything after is Firebase-protected. Never reorder these calls without checking which routes you're exposing or locking down.

The three bootstrap.Setup* entrypoints (internal/bootstrap/setup.go)

  • SetupInternalJobs(r, db) — routes under /jobs, protected by authentication.InternalAPIKeyAuth() (the x-api-key header), not Firebase. Add a new job by calling {feature}.SetupJobs(jobsGroup, reg) here; the group's middleware already covers it.
  • SetupPublicComponents(r, db, auth) — genuinely unauthenticated routes (payment-provider webhooks, etc.), called before the global Firebase middleware exists. If one of its routes still needs auth (e.g. a subscription endpoint mixed into an otherwise-public group), apply it explicitly in that feature's own Setup() — e.g. api.NewSubscriptionHandlers(r, uc, authenticator.Authenticate()) — don't rely on global middleware here, it isn't attached yet.
  • SetupCleanArchComponents(r, db, auth) — every authenticated clean-arch feature. Add your new feature's {feature}.Setup(r, reg) call here.
  • Each of the three entrypoints creates its own registry.NewRegistry(db) — they don't share one instance, so a repository built for jobs and the same repository built for clean-arch components are separate Go values (harmless: both just wrap the same *gorm.DB).
  • The import list in setup.go is alphabetical (gofumpt/goimports-enforced); the call order inside each Setup* function body has no enforced order — append new calls at the end.

internal/bootstrap/registry/registry.go

  • One unexported pointer field + one Get{X}Repository() method per repository, always following the lazy nil-check-then-construct pattern:
    func (r *Registry) Get{X}Repository() *repository.{X}Repository {
        if r.{x}Repository == nil {
            r.{x}Repository = repository.New{X}Repository(r.db)
        }
        return r.{x}Repository
    }
    
  • Registry is a process-lifetime singleton, built once per Setup* entrypoint call — not per-request. Never stash per-request state on it; request-scoped data (like user_id) flows through ctx, not the registry.
  • When a dependency composes other repositories (see GetPlanLimitsValidator, which needs the wallet/credit-card/movement/recurrent repos), build it by calling the other Get* methods — never reach into another field directly — so those dependencies stay lazily initialized too.
  • External gateways/HTTP clients (Stripe, MercadoPago, Firebase, Expo push) are not registry-backed — they're stateless clients constructed directly inside the feature's Setup() (gateway.NewStripeGateway(), push.NewExpoClient()), never memoized on the registry.

internal/bootstrap/{feature}/setup.go

  • package {feature}, one exported Setup(r *gin.Engine, registry *registry.Registry) (or SetupJobs(jobsGroup *gin.RouterGroup, registry *registry.Registry) for a job-only feature). The parameter is named registry, shadowing the imported package — that's intentional; only the type is needed in the signature, and methods are called on the parameter throughout the body.
  • Body shape: pull every dependency from the registry (or construct a gateway/client inline), build the usecase(s) — innermost dependency first when one usecase depends on another (see invoiceService built before movementService in internal/bootstrap/movement/setup.go) — then call the handler constructor.
  • If the usecase's methods use pointer receivers, take the address when passing it on: movementService := usecase.NewMovement(...); api.NewMovementV2Handlers(r, &movementService). Match whatever usecase.New{Entity} actually returns (value vs pointer use — see the go-usecases skill).
  • Wire the new {feature}.Setup call into internal/bootstrap/setup.go — either SetupCleanArchComponents (normal case) or SetupInternalJobs (job-only feature, calling SetupJobs instead).

Adding a brand-new feature, end to end

  1. internal/infrastructure/repository/{feature}_repository.go + model + FromDomain/ToDomain.
  2. internal/usecase/{feature}_usecase.go — see the go-usecases skill.
  3. internal/infrastructure/api/{feature}_api.go — see the go-api-handlers skill.
  4. Add a {feature}Repository *repository.{Feature}Repository field + Get{Feature}Repository() to registry.go.
  5. internal/bootstrap/{feature}/setup.go with Setup(r, reg), following the shape above.
  6. Add the import + {feature}.Setup(r, reg) call to SetupCleanArchComponents in internal/bootstrap/setup.go.

Anti-patterns (reject these)

Don't Do
Add a new feature's wiring inline in cmd/api/main.go's run() Create internal/bootstrap/{feature}/setup.go and call it from SetupCleanArchComponents
Register a new authenticated route before r.Use(authenticator.Authenticate()) inside setupGin Register it via SetupCleanArchComponents, which runs after the auth middleware is attached
Add a repository field to Registry without the matching nil-check lazy getter Always pair the field with a Get{X}Repository() that checks-then-constructs
Reach into another field directly inside a composite Get* (e.g. r.walletRepository instead of r.GetWalletRepository()) Call the other Get* method so that dependency also gets lazily initialized
Memoize an external gateway/HTTP client on the Registry Construct it directly in the feature's Setup() — gateways aren't registry-backed
Store request-scoped data (user ID, request context) on the Registry Keep the registry process-lifetime; pass request data through ctx

Run & verify

go build ./...
make linter
go run ./cmd/api/main.go   # confirm the app boots and the new route responds as expected