name: backend-delivery description: Implements backend features and bug fixes in this Go project, maintains router-based backend API documentation with request/response JSON contracts, updates Postman collections, and validates changes with build and test commands.

Backend Delivery Skill

Purpose

Use this skill for backend tasks in backend/ that require end-to-end delivery:

• Implement or fix backend code.
• Update docs for behavior and usage.
• Create or update Postman API documentation.
• Run build/tests to validate before reporting completion.

Scope

• Language/runtime: Go (module in backend/).
• Typical areas: pkg/, main.go, configs/, migrations/.
• Output artifacts:
  • Code changes in backend files.
  • Documentation updates in router/function-based structure (preferred under docs/backend-api/).
  • Postman files under docs/postman/:
    • goportal.postman_collection.json
    • goportal.postman_environment.json (optional)

Backend Folder Structure Conventions

Use these conventions by default unless the user explicitly requests otherwise:

• pkg/models/: GORM model structs (User, Relationship, etc.).
• migrations/: SQL migrations managed by goose.
• pkg/repositories/ + pkg/repositories/impl/: persistence interfaces and implementations.
• pkg/services/ + pkg/services/impl/: business logic interfaces and implementations.
• pkg/controllers/: HTTP handlers/controllers.
• pkg/serializers/: API request/response payload contracts.
• pkg/apperr/: centralized app error codes/messages and HTTP mapping.
• pkg/scripts/: migration/seed orchestration logic.
• pkg/seeders/: seed data logic (bootstrap/default records).

When adding a new backend domain model:

1. Add/extend GORM struct in pkg/models/.
2. Add a new SQL migration in migrations/ to create required table/indexes.
3. Wire repository/service/controller changes as needed.

When changing an existing model schema:

1. Update the struct in pkg/models/.
2. Add a new migration for schema evolution (ALTER/transform/copy-rename strategy).
3. Do not rewrite already-applied migration files unless explicitly requested.

Seeder guideline:

• Add or update files in pkg/seeders/ when new model fields or default data are required.
• Keep seeding idempotent (safe to run multiple times without creating duplicates).

Default Workflow

Copy this checklist and keep it updated while working:

Backend Delivery Progress
- [ ] 1) Understand request and inspect impacted backend modules
- [ ] 2) Implement code changes
- [ ] 3) Add/update migrations when schema changes
- [ ] 4) Update backend docs by router/function with JSON input/output contracts
- [ ] 5) Create/update Postman collection examples
- [ ] 6) Run backend validation (fmt/build/test)
- [ ] 7) Summarize changes, test evidence, and follow-ups

Implementation Rules

1. Keep changes minimal and focused on the requested behavior.
2. Follow existing project conventions (naming, structure, error handling).
3. If DB schema changes, add a new migration file; do not rewrite old migration history unless explicitly requested.
4. Keep API response formats consistent with existing serializers/contracts.
5. If auth/claims/user ID types change, update all affected layers (model, repo, service, controller, middleware, serializers, token utilities).
6. For business/domain errors, use pkg/apperr instead of ad-hoc raw errors in controllers/services.
7. Standardize error flow: create/wrap with apperr.E(...), map to response via existing serializer/error mapping.

Documentation Rules

When behavior, API, config, or migration flow changes, update docs in the same task:

• Update run instructions if commands changed.
• Document any new env/config requirements.
• Add API request/response examples for changed endpoints.
• Keep docs concise and action-oriented.

Router/Function-Based API Documentation (Required)

For every new/changed endpoint, document it by router domain and function intent (for example: users, social, auth). The goal is that frontend can implement directly from docs without reading backend code.

Preferred folder layout (do not keep all routes in one file/folder):

• docs/backend-api/README.md (index page)
• docs/backend-api/<router>/README.md (router overview)
• docs/backend-api/<router>/<feature>.md (one file per feature/endpoint group)

Example:

• docs/backend-api/users/profile.md
• docs/backend-api/users/search.md
• docs/backend-api/social/follow.md
• docs/backend-api/social/block.md

If the project has no docs/backend-api/ yet, create it and migrate new docs there. Root README.md can keep only high-level links.

Each endpoint doc must include:

1. Method + path (for example POST /api/v1/users).
2. Purpose/behavior in 1-2 lines.
3. Auth requirement (public or Bearer token).
4. Request headers (if required).
5. Path params/query params/body schema.
6. JSON request example.
7. Success response JSON example(s).
8. Error response JSON example(s) mapped to app/domain errors.
9. Notes for frontend (validation rules, nullable fields, pagination/cursor semantics, id format).

Use this template for every route:

### <ROUTER>: <FEATURE NAME>

- Method: `<HTTP_METHOD>`
- Path: `<PATH>`
- Auth: `<public|Bearer token>`
- Description: <short behavior>

#### Request

- Headers:
  - `Content-Type: application/json`
  - `Authorization: Bearer {{token}}` (if protected)
- Path params:
  - `<name>`: `<type>` - <description>
- Query params:
  - `<name>`: `<type>` - <description>
- Body JSON:

```json
{
  "fieldA": "value",
  "fieldB": 123
}
```

#### Success Response

- Status: `<200|201|...>`

```json
{
  "data": {},
  "message": "success"
}
```

#### Error Responses

- Status: `<400|401|403|404|409|500>`
- Meaning: `<when this error happens>`

```json
{
  "error": {
    "code": "ERR_CODE",
    "message": "human readable message"
  }
}
```

#### Frontend Notes

- <validation rules / edge cases / optional fields / pagination behavior>

Documentation quality rules:

• Keep field names exactly aligned with serializer/request struct JSON tags.
• Mark optional/nullable fields explicitly.
• If response envelope differs by router, show exact envelope shape used by that router.
• Provide at least one realistic success example and one realistic failure example per endpoint.
• For list endpoints, include pagination query + response metadata examples.
• When an endpoint changes, update docs in the same commit/task (no deferred docs).
• Keep each router in its own folder and each major feature in its own markdown file (avoid one giant API doc file).

Postman Documentation Rules

When endpoints are created or changed:

1. Ensure docs/postman/ exists.
2. Create or update goportal.postman_collection.json with:
   • Request method and URL ({{base_url}}/...)
   • Required headers
   • Request body example (if needed)
   • Example success/error responses in descriptions
3. Add or update environment file with at least:
   • base_url (for example: http://localhost:8080)
   • token (empty by default for authenticated routes)
4. Keep collection names and folder grouping aligned with route domains (auth, users, etc.).
5. Ensure examples in Postman match the same request/response contracts documented in router-based docs.
6. If the collection becomes large, split maintenance sources by router (for example, one exported collection per domain) and keep one merged collection for delivery.

Validation Commands (Backend)

Run from backend/ unless the task explicitly says otherwise:

go fmt ./...
go build ./...
go test ./...
go run . -config configs/config.yaml -migrate

Migration execution is part of default backend validation. Always attempt migration run and report result.

If seed behavior changed:

go run . -config configs/config.yaml -migrate -seed

Final Response Format

Report results in this order:

1. What was changed (code + migrations + docs + Postman).
2. Validation commands executed and outcomes.
3. Any known limitations or follow-up actions.