# Backend Agent Guidelines

These instructions extend the repository-wide rules in the root `AGENTS.md`
and apply whenever a task adds or modifies backend code, including Go and
protobuf files under `backend/`.

Before completing the task, review the entire backend diff produced by the
current task, fix every in-scope issue found, and then perform the required
validation. Use the
[`$review-backend-change`](../.agents/skills/review-backend-change/SKILL.md)
skill to perform this completion workflow.

## Reuse existing definitions

- Search the repository before introducing a protobuf message, enum, Go struct,
  interface, or shared domain type.
- Reuse or extend the canonical existing definition when its semantics match.
  Do not create parallel representations or conversion layers for the same
  concept without a clear architectural reason.
- Avoid naming stutter in packages, types, fields, parameters, and access paths.
  Each nested name should add meaning instead of repeating its parent context.
  For example, prefer a concise path such as `payment.Details.ID` over
  `payment.Payment.PaymentID`.

## Use the project error model

- Do not introduce `fmt.Errorf` or `errors.New`. Use the constructors and
  wrapping helpers in `backend/pkg/merrors`.
- Preserve the underlying cause when adding context by using an appropriate
  `merrors` wrapping helper.
- When no suitable project error exists, add the smallest generally useful
  definition or helper to `backend/pkg/merrors` instead of creating an ad hoc error
  elsewhere.

## Keep modules cohesive and names concise

- Review touched files for excessive size, mixed responsibilities, duplicated
  logic, and poor separation of concerns.
- Refactor oversized contributions into focused, cohesive files or packages.
  Do not split code mechanically; organize it along clear domain or
  architectural boundaries.
- Avoid repeating directory or package context in child directory and file
  names. For example, prefer `payment/widget.dart` over
  `payment/payment_widget.dart`.

## Review implementation quality

- Review the current task's backend contribution for correctness, readability,
  maintainability, testability, and consistency with the surrounding
  architecture.
- Keep public APIs and module boundaries small and intentional. Remove
  unnecessary indirection, duplication, dead code, and speculative abstractions.
- Add or update tests for changed behavior, edge cases, and failure paths.
- Fix all findings caused by the current task before reporting completion.

## Review logging

- Ensure the contribution has sufficient structured logging at meaningful
  operational and domain boundaries. Include useful identifiers and context,
  but never log credentials, secrets, or sensitive payment data.
- Follow the repository's logging style and use levels consistently:
  - `Debug`: fine-grained runtime execution tracking useful during debugging.
  - `Info`: important payment-domain events, module-boundary operations,
    effective module configuration, and noteworthy but expected deviations from
    the usual path.
  - `Warn`: runtime errors and unexpected conditions from which the service can
    continue or which are returned to a caller.
  - `Error`: unrecoverable failures that cause, or imminently lead to, service
    or component termination.
- Avoid logging the same error repeatedly at multiple layers. Log it where the
  layer has enough context to make the event actionable.

## Required validation

- From the repository root, run `make test` and `make lint-backend`, plus every
  applicable command from the root `AGENTS.md` change-scoped security
  requirements, after all review fixes are complete.
- All commands must succeed before the task is reported as complete. Fix
  failures introduced by the current task; do not silently skip, suppress, or
  weaken checks.
- Report the commands run and their outcomes in the final response. If an
  external or environmental blocker prevents a command from running, report
  the exact command, failure, and blocker explicitly; do not claim successful
  validation.

## SXCHNGE provider boundary

SXCHNGE owns auth, sessions and customer management. SXCHNGE is one organization
inside Sendico. Copied BFF components are locally owned and may diverge.
Use only Sendico's public HTTP API for platform operations. Never import sibling
Sendico modules or access its database, internal gRPC APIs, discovery or message
bus. Keep the pinned public wire contract separate from local DTOs and models.
Resolve the configured provider organization and customer resource ownership on
the server. Never treat all customers as the backend integration principal.
Use the copied structured logger, injected at operational boundaries.