Migration Playbook for Coding Agents

A1. Survey, and write the plan down

Produce, and keep updated, an inventory of: every route (method, path, handler), every middleware and the order it runs in, every config read, every data-access call site, every background job, and the test entrypoints.

Verify: the route count in your inventory equals the route count the application prints at startup, or that grep finds in the router setup.

A2. Install and take over the entrypoint

go get -u github.com/klass-lk/ginboot

Replace the router construction with ginboot.New(), move server-wide middleware to server.Engine().Use(...) before any route registration, and register the existing route tree on server.Engine(). Change nothing else.

Verify:

go build ./... && go vet ./...
go test ./...
# start the app, then:
curl -fsS localhost:8080/healthz

Plus one curl per route family, compared against responses recorded before the change.

A3. Configuration

Create ginboot.yml using the environment variable names the deployment already sets, and replace scattered os.Getenv calls with server.Config().

ginboot:
  server:
    port: ${PORT:8080}
    base-path: /api/v1
    env: ${ENV:development}

Verify: the app starts both with the real environment and with an empty one. If you set base-path, confirm no route now answers at a doubled prefix.

A4. Convert one endpoint group

Repeat this step once per resource, smallest and least critical first. Do not batch several groups into one change.

1. Create internal/controller/<resource>_controller.go with a Register method.
2. Convert each handler to one of the four signatures.
3. Move error responses into ApiError values returned by the service.
4. Register with server.RegisterController("/<resource>", c).
5. Delete the old route registration for that resource.

Verify: go build ./... && go test ./..., then a response diff for every route in the group — status code, headers that matter, and body — against the recorded originals.

A5. Data access

Replace hand-written CRUD with a repository from the matching db/* module, embedding it so custom queries survive. Add the tags the backend needs (bson, GORM, dynamodbav) and GetTableName() for SQL and DynamoDB models.

Verify: repository tests, then the endpoint tests from A4, still pass.

A6. Background work and platform features

Convert tickers and cron jobs to RegisterWorker/RegisterWorkerStruct, and queue pollers to RegisterConsumer. Then add telemetry, caching or the Lambda runner if the task asks for them.

Verify: each worker logs one execution; go test ./... passes.

A7. Delete the old scaffolding

Remove the superseded router setup, manual binding, error formatting and config loading. An unused parallel implementation is the most expensive thing you can leave behind.

Verify: go build ./... && go vet ./... && go test ./..., and grep -rn "ShouldBindJSON\|gin.Default()\|os.Getenv" --include=*.go . returns only deliberate matches.

B1. Capture the contract

Extract, in this order of preference: the existing OpenAPI document, recorded request/response traffic, or the route table plus tests. Record for every endpoint: method, path, parameters, request fields with types and required-ness, response shape, every status code, and the authentication required.

Save it in the repository — docs/api-contract.md or openapi.json. It is the acceptance criterion for everything that follows.

Verify: the endpoint count matches the old service's route table exactly.

B2. Scaffold

go mod init <module>
go get -u github.com/klass-lk/ginboot

Layout: cmd/main.go, internal/controller, internal/service, internal/repository, internal/model, internal/middleware, plus ginboot.yml.

Verify: go build ./... and curl -fsS localhost:8080/healthz.

B3. Models

One Go struct per entity. Tag every field with json using the exact name the old API emits. Use pointers for fields that are nullable or whose absence differs from their zero value.

Verify: unmarshal a recorded response body into the struct, marshal it back, and diff. The diff must be empty.

B4. Services

Port the rules, not the syntax. Services take context.Context and return domain errors, and must not import ginboot types other than ApiError.

Hidden behaviour is the main risk: ORM lifecycle hooks, signals, before_save callbacks, middleware that mutates the request, and framework-implicit defaults. Enumerate them from the old source and make each one an explicit call.

Verify: ported unit tests pass.

B5. Repositories

Point the repository at the same database the old service uses. Do not copy data yet.

Verify: reads return values identical to the old service's for the same keys.

B6. Controllers, validation, auth

One controller per resource. Validation moves into binding tags; errors become ApiError values with the same status codes the old API returned; auth middleware sets user_id and role.

Verify: per endpoint, same request → same status, same body. Automate this as a diff against recorded traffic rather than checking by eye.

B7. Jobs and consumers — one owner only

Port scheduled jobs and queue consumers, and disable each one in the old service at the moment you enable it in the new one. A job running in both services is a data-corruption bug, not a migration inconvenience.

Verify: for every job, exactly one service has it enabled. State this explicitly in your report.

B8. Cutover

Move one path prefix at a time at the proxy: read-only endpoints first, then low-traffic writes, then the core write paths. Keep one proxy rule per path so a rollback is a single change.

Verify: GINBOOT_EXPORT_SWAGGER=openapi.json go run ./cmd and diff the result against the contract from B1.