# Acme Payments
#
# ─────────────────────────────────────────────────────────────────────────────
#  TRIO FILE 1 of 3 — AGENTS.md (CANONICAL)
#  QRefAI AI Coding Field Guide, Part 5 (Q5.x) · the thin-adapter pattern
#
#  This is a FILLED-IN worked example (not a blank template) so you can see what
#  the two adapters point AT. The rule of the trio:
#     • AGENTS.md           = single source of truth (this file). All real content.
#     • CLAUDE.md           = thin wrapper: @imports this, adds Claude-only overrides.
#     • copilot-instructions = thin wrapper: dense first-4K restatement of the
#                              must-enforce-in-review rules, then "see AGENTS.md".
#  You maintain content HERE; the adapters stay tiny and rarely change.
# ─────────────────────────────────────────────────────────────────────────────

## Overview
Backend service for card authorization and settlement. Part of the Acme polyrepo
platform; upstream of the ledger service, downstream of the API gateway.

## Tech Stack
- Go 1.23
- PostgreSQL 16
- gRPC 1.62
- Deployed to EKS

## Setup Commands
- Build: `make build`
- Test:  `make test`        # must pass before any commit
- Lint:  `make lint`        # CI-enforced
- Run:   `make run-local`

## Code Style
- Errors are wrapped with context, never returned bare:

      if err != nil {
          return fmt.Errorf("charge %s: %w", chargeID, err)
      }

- External calls go through `internal/clients/`; never inline an http.Client.

## Testing
- Table-driven tests; one `_test.go` per package.
- Integration tests behind the `integration` build tag (`make test-int`).
- New behavior requires a test; PRs without tests are rejected in review.

## Architecture Notes
- `internal/domain/`    — business logic, no I/O
- `internal/transport/` — gRPC handlers, thin
- `internal/store/`     — DB access; all SQL lives here
- Data flow: transport → domain → store; never skip a layer.

## PR & Commit Guidelines
- Conventional Commits; squash-merge only.
- PRs require one human approval + green CI.
- New public endpoints require an entry in `docs/api-changelog.md`.

## Security Considerations
- No secrets, tokens, or credentials in source — ever.
- All money is int64 minor units; never floats.
- PII handling per the `pii-handling` skill; audit logging per `regulatory-logging`.
- Never write code that deletes from the `audit_events` or ledger tables.