mirror of https://github.com/Sea-Haven-Industries/shoc-backend.git synced 2026-09-30 10:43:13 +00:00

Alexandre Brandizzi 833fb816ee

chore(governance): enforce backend architecture and quality gates (#31 )

* docs(governance): add canonical governance docs, unified quality-gate script, and CI parity

- ARCHITECTURE_AND_CODE_QUALITY.md: canonical layering, EF allowlist,
  transaction/commit convention, cancellation, migrations, error disclosure,
  Big-O/perf, ADR exceptions (supersedes BACKEND_ARCHITECTURE.md)
- QUALITY_GATES.md: gate inventory + pass/fail/skip semantics; local==CI
- REVIEW_AND_PR_FRAMEWORK.md: exact-head review, board-backed regression
  inventory, security/perf evidence, ADR exceptions, no godfile theater
- AGENTS.md: repo-specific delta + precedence pointers
- scripts/governance-check.sh: unified G1 restore + G2 ArchitectureTests +
  G3 changed-file format (portable bash)
- .github/workflows/architecture-quality.yml: call the same local script
- ArchitectureTests.cs: add business-service interface-dependency invariant

* fix(governance): make backend gate complete

* fix(ci): enforce governance on every pull request

2026-07-24 17:41:10 -03:00

3 KiB

Raw Blame History

AGENTS.md — SeaHaven backend (repo-specific delta)

This file is the repo-specific delta for the Seahaven backend. It layers on top of the operator/workspace agent baseline and does not repeat it. This file may add stricter backend rules but may never weaken the workspace baseline.

Canonical governance documents (precedence)

ARCHITECTURE_AND_CODE_QUALITY.md — what the rules mean (canonical; supersedes the older BACKEND_ARCHITECTURE.md, which is retained only as historical reference).
QUALITY_GATES.md — how rules are enforced (commands + CI mapping).
REVIEW_AND_PR_FRAMEWORK.md — who reviews, in what order, with what evidence.

When these conflict with each other, the one that owns the topic wins (meaning → architecture doc; execution → quality gates; process → review framework). When unsure, ask; do not silently pick.

Architecture in one line

Controller -> I{Feature}Service -> I{Feature}DataService -> ApplicationDbContext

Controllers depend on I{Feature}Service only — never DbContext/EF/concrete services/data services.
Business services depend on feature-specific data/query/command interfaces — never DbContext, never IConfiguration, never a generic repository.
Data services own EF; EF/DbContext lives only on the documented infrastructure allowlist (data services, ApplicationDbContext, migrations, Identity/composition, transactions inside data services).
One commit convention: SaveChangesAsync(CancellationToken) inside the owning data service is the atomic boundary; explicit transactions stay inside data services.
Tenant scope is server-derived; authorization is enforced at service entry.
No HTTP response leaks exception/stack/SQL/credential/crypto detail; secrets are never logged.

Full detail: ARCHITECTURE_AND_CODE_QUALITY.md.

Running the complete gate (local == CI)

bash scripts/governance-check.sh

The command restores, verifies architecture and changed-file formatting, builds Release, and runs the full test suite. CI (architecture-quality workflow) calls the same script. See QUALITY_GATES.md.

Hard rules (deviation needs an ADR; no wildcard suppressions)

EF allowlist, dependency direction, no client exception disclosure, server-derived tenant scope, one commit convention, cancellation forwarding (verified, not just signed).
Suppress a single diagnostic with a cited ADR only — never global sweeps.
See ARCHITECTURE_AND_CODE_QUALITY.md §10 for the ADR exception process.

Do not touch without explicit instruction

Product behavior, database migrations, secrets, dependency versions, and files unrelated to the current task.
The .ai-config-kit-sidecar-write-scope marker file is a transient authorization artifact — never commit it.

Reporting

State every changed file with a one-line summary. Report each gate as pass / fail / skipped / not-run with evidence; never infer a pass from silence.

3 KiB Raw Blame History