sxchnge/backend/AGENTS.md

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 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/shared/errors.
• 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/shared/errors 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. This organization reference belongs only in the public provider adapter configuration. Local customers have no organizations, tenant IDs, membership, roles or policy engine. Do not copy platform scaffolding to satisfy unused dependencies; remove those dependencies from the selected components. 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 consumed public wire contracts inside the owning adapter, separate from local DTOs and models. Do not copy unused API snapshots. 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.

Go module structure

backend/ groups independent Go modules; it is not itself a Go module. product/ is the customer-facing executable and owns its main.go and go.mod. shared/ is a library module for reusable infrastructure and has no entry point. Backoffice belongs in its own executable module (backoffice/) when implemented, with its own entry point and configuration, not inside the product executable. Keep feature models, storage, services and transport together inside their owning module. Shared infrastructure must not import a product or backoffice module.