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.claude/skills/go-bootstrap/SKILL.md
GitHubGo 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.gofor 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, callsetupGin, wire legacy v1 (the existing inline calls — don't add to this, it's migration debt), callbootstrap.SetupCleanArchComponents, start the server. - Pull any standalone concern into its own top-level function (
configureLogger,setupGin,ping) instead of growingrun().setupGinitself 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
setupGindecides auth. Anything registered beforer.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 byauthentication.InternalAPIKeyAuth()(thex-api-keyheader), 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 ownSetup()— 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.gois alphabetical (gofumpt/goimports-enforced); the call order inside eachSetup*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 } Registryis a process-lifetime singleton, built once perSetup*entrypoint call — not per-request. Never stash per-request state on it; request-scoped data (likeuser_id) flows throughctx, 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 otherGet*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 exportedSetup(r *gin.Engine, registry *registry.Registry)(orSetupJobs(jobsGroup *gin.RouterGroup, registry *registry.Registry)for a job-only feature). The parameter is namedregistry, 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
invoiceServicebuilt beforemovementServiceininternal/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 whateverusecase.New{Entity}actually returns (value vs pointer use — see thego-usecasesskill). - Wire the new
{feature}.Setupcall intointernal/bootstrap/setup.go— eitherSetupCleanArchComponents(normal case) orSetupInternalJobs(job-only feature, callingSetupJobsinstead).
Adding a brand-new feature, end to end
internal/infrastructure/repository/{feature}_repository.go+ model +FromDomain/ToDomain.internal/usecase/{feature}_usecase.go— see thego-usecasesskill.internal/infrastructure/api/{feature}_api.go— see thego-api-handlersskill.- Add a
{feature}Repository *repository.{Feature}Repositoryfield +Get{Feature}Repository()toregistry.go. internal/bootstrap/{feature}/setup.gowithSetup(r, reg), following the shape above.- Add the import +
{feature}.Setup(r, reg)call toSetupCleanArchComponentsininternal/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