40 lines
3.1 KiB
Markdown
40 lines
3.1 KiB
Markdown
# Backend Agent Operating Contract
|
|
|
|
## Phase gate
|
|
|
|
This repository is in specification mode. Do not create `go.mod`, application packages, migrations, containers, or executable code until the relevant capability spec is approved.
|
|
|
|
For every Go-related task, always invoke and follow the `golang-how-to` skill, then the secondary Go skills it routes to. Before creating the Go project layout, ask the user to approve the architecture style and dependency-injection approach in that order.
|
|
|
|
## Product invariants
|
|
|
|
- The backend is the authority for authentication, authorization, tenant isolation, metric definitions, and data provenance.
|
|
- Every merchant-scoped query derives merchant identity from the authenticated server-side session; never trust a client-supplied merchant identifier as authorization.
|
|
- Cross-merchant results are minimum-cohort, anonymized aggregates only.
|
|
- Use integer minor currency units or an explicitly documented fixed-precision representation; never floating point for money.
|
|
- Preserve source timestamps and document their timezone assumptions. Normalize operational timestamps consistently.
|
|
- Raw imports are immutable inputs; corrections are new import versions, not silent mutation.
|
|
- `adjusted_fee` is obfuscated and may be used only for relative analysis.
|
|
|
|
## Go baseline after approval
|
|
|
|
- Keep `main` packages thin under `cmd/`; business code lives under `internal/`.
|
|
- Wire dependencies manually with explicit constructors at the composition root. Do not introduce a DI container or code generator unless a later ADR documents measured wiring/lifecycle complexity.
|
|
- Use explicit constructors; avoid `init()` side effects and mutable globals.
|
|
- Configuration comes from validated environment variables. Logs go to stdout as structured records without credentials, card keys, or sensitive payloads.
|
|
- Propagate `context.Context`; bound external calls, queues, batches, and database pools.
|
|
- Use parameterized queries and transactions with explicit boundaries. Stream/bulk-load the multi-million-row input instead of holding it in memory.
|
|
- Passwords use an approved adaptive hash (Argon2id or bcrypt per the approved auth spec); sessions use secure, HttpOnly cookies and server-side revocation.
|
|
- Required verification includes unit/integration tests, race detection where applicable, `go vet`, `golangci-lint`, `govulncheck`, and migration/import tests.
|
|
|
|
## Git and documentation
|
|
|
|
- Use atomic Conventional/Commitizen commits.
|
|
- Track specs, ERD/schema definitions, migrations, importer code, validation rules, manifests/templates, and runbooks.
|
|
- Ignore raw CSV archives, database volumes/dumps, credentials, and generated runtime data.
|
|
- Changes to a metric, API, schema, authorization rule, or AI data boundary require the corresponding spec/ADR update.
|
|
|
|
## AI boundary (post-MVP)
|
|
|
|
AvalAI is accessed only from the backend using a server-held API key. Prefer the simplest bounded LLM call/workflow that satisfies the approved use case. Send minimized, sanitized aggregates with explicit budgets/timeouts; persist trace metadata and deterministic inputs, not unnecessary sensitive prompts. AI output is advisory and must cite underlying deterministic metrics.
|