autojanet/skills/understand/frameworks/gin.md

Gin (Go) Framework Addendum

Injected into file-analyzer and architecture-analyzer prompts when Gin is detected. Do NOT use as a standalone prompt — always appended to the base prompt template.

Gin Project Structure

When analyzing a Gin project, apply these additional conventions on top of the base analysis rules.

Canonical File Roles

File / Pattern	Role	Tags
main.go	Application entry point — initializes the Gin engine, registers routes, starts the server	entry-point, config
cmd/*.go, cmd/**/*.go	CLI entry points — multiple binaries in a multi-command project	entry-point, config
handlers/*.go, handler/*.go	HTTP handlers — process requests with gin.Context	api-handler
controllers/*.go, controller/*.go	Controllers — alternative naming for HTTP handlers	api-handler
routes/*.go, router/*.go	Route definitions — register endpoints and route groups	routing, config
models/*.go, model/*.go	Data models — struct definitions mapped to database tables	data-model
middleware/*.go	Middleware functions — authentication, logging, CORS, rate limiting	middleware
services/*.go, service/*.go	Business logic — domain operations decoupled from HTTP layer	service
repository/*.go, repo/*.go	Data access layer — database queries and persistence logic	data-model, service
config/*.go, config.go	Application configuration — environment loading, struct-based config	config
dto/*.go	Data transfer objects — request and response structs	type-definition
utils/*.go, pkg/*.go	Shared utility packages	utility
*_test.go	Unit and integration tests	test

Edge Patterns to Look For

Route group registration — When r.Group("/api") creates a route group and registers handlers, create configures edges from the route definition file to each handler. Route groups organize endpoints by prefix and shared middleware.

Handler-to-service calls — When a handler function calls a service method, create depends_on edges from the handler to the service. This represents the separation between HTTP handling and business logic.

Service-to-repository calls — When a service calls a repository method for data access, create depends_on edges from the service to the repository. This represents the data access abstraction.

Middleware chaining — When r.Use(middleware) or a route group applies middleware, create middleware edges from the router or group to the middleware function. Middleware executes in registration order.

Architectural Layers for Gin

Assign nodes to these layers when detected:

Layer ID	Layer Name	What Goes Here
layer:api	API Layer	handlers/, controllers/, HTTP handler functions
layer:data	Data Layer	models/, repository/, database access, migrations
layer:service	Service Layer	services/, business logic
layer:middleware	Middleware Layer	middleware/, authentication, logging, rate limiting
layer:config	Config Layer	main.go, routes/, config/, environment setup
layer:utility	Utility Layer	utils/, pkg/, shared helper packages
layer:test	Test Layer	*_test.go, test fixtures, test helpers

Notable Patterns to Capture in languageLesson

• Handler functions with gin.Context: Every Gin handler receives a *gin.Context parameter — it provides request parsing (c.Bind, c.Param, c.Query), response writing (c.JSON, c.HTML), and control flow (c.Abort, c.Next)
• Middleware chain with c.Next(): Middleware calls c.Next() to pass control to the next handler in the chain — code before c.Next() runs pre-handler, code after runs post-handler
• Route grouping for modular APIs: r.Group("/v1") creates modular sub-routers that can have their own middleware stack — enables versioning and access control at the group level
• Dependency injection via constructors (no framework DI): Go has no DI framework — dependencies are passed as constructor parameters (e.g., NewUserHandler(userService)) and stored as struct fields
• Interface-driven design for testability: Services and repositories are defined as interfaces — handlers depend on the interface, enabling mock implementations in tests
• Error handling with gin.Error: Gin collects errors via c.Error(err) — middleware can inspect c.Errors after handler execution to implement centralized error logging and response formatting