Users module

User-facing HTTP APIs live under /api/user. They demonstrate pagination, JWT-protected mutations, and DTO-driven validation separate from persistence structs.

Route summary

Method	Path	Auth	Description
`GET`	`/api/user`	Public in default template	Paginated list of users for admin-style screens.
`GET`	`/api/user/me`	JWT	Returns the authenticated user’s profile.
`PUT`	`/api/user/:id`	JWT	Updates allowed fields; `:id` should match token subject in real apps — verify in your fork.
`DELETE`	`/api/user/:id`	JWT	Deletes user row (consider soft-delete for production).

Hardening tip: tie user_id from JWT to the :id route parameter so users cannot modify each other’s accounts unless they are admins.

Pagination (`GET /api/user`)

The list endpoint uses types under modules/user/internal/app/queries together with the shared pagination library referenced in go.mod.

Extending filters

When you add query parameters:

Extend the filter struct with fields and binding tags where appropriate.
Implement ApplyFilters on *gorm.DB inside the filter type.
Document accepted query keys in your public API reference.

Keep default sort predictable — the template sets a conservative default sort field.

DTOs and validation

Public structs live in modules/user/dto. They carry:

JSON / form field names.
binding: tags for Gin’s validator.
Message constants for uniform API responses.

Custom rules live in internal/presentation/validation when struct tags are not enough.

Relationship to auth

The auth module imports user DTOs and the user repository interface for register/login flows. That is why those packages sit outside internal — Go’s import rules forbid modules/auth importing modules/user/internal/....

When you add fields to registration:

Update user DTO + validation.
Update auth controller binding structs if it embeds user requests.
Update auth service mapping into entity creation.

Testing ideas

Table-driven tests for validation helpers.
Integration tests with SQLite or disposable Postgres for repository methods.
HTTP tests using httptest against Gin with a stubbed DB — heavier but valuable before releases.

Common extensions

Need	Approach
Avatars	Multipart upload endpoint + object storage URL on `users`.
Roles / permissions	Separate tables; middleware checks claims or DB membership.
Audit trail	Insert-only `audit_log` table updated from services.

Keep controllers free of policy that belongs in services so you can reuse rules from CLI jobs later.