@jeffrey2423/coding-standards 1.0.0 → 2.0.0

package/standards/backend/architecture/multitenancy.md

@@ -0,0 +1,112 @@
+---
+title: Multi-Tenancy Strategy
+platform: backend
+track: distributed-architecture
+load_when: "Building a multi-tenant SaaS — tenant isolation, RLS, partitioning, and tenant routing."
+updated: 2026-06
+---
+
+# Multi-Tenancy Strategy
+
+A modern multi-tenant SaaS uses a **hybrid "bridge" model**: pooled by default, siloed selectively. This is the AWS SaaS Lens recommendation and the pattern the industry has converged on.
+
+## The model
+
+- **Pool by default** — standard tenants share one database **per microservice**, isolated by a `tenant_id` column + **Row-Level Security (RLS)**. Cheapest, simplest to operate.
+- **Silo selectively** — enterprise/regulated/high-volume tenants are promoted to a dedicated database. A **per-microservice** decision (a tenant can be siloed in Sales, pooled in Catalog).
+- **Tenant catalog (control plane)** — a small central DB mapping `tenant_id → connection string` per microservice, enabling dynamic routing.
+
+This keeps DB-per-service intact: Sales never shares a DB with Inventory; within Sales, tenants share until promoted.
+
+## Row-Level Security — the isolation guarantee
+
+Isolation is **structural** (enforced by PostgreSQL), not application-level (a forgotten `WHERE`).
+
+```sql
+ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
+ALTER TABLE orders FORCE ROW LEVEL SECURITY;            -- owner is constrained too
+CREATE POLICY tenant_isolation ON orders
+  USING      (tenant_id = current_setting('app.tenant_id')::uuid)
+  WITH CHECK (tenant_id = current_setting('app.tenant_id')::uuid);
+```
+
+### RLS rules (verified against PostgreSQL 18 docs)
+
+- **MUST** run the app under a **non-owner, non-superuser role without `BYPASSRLS`**. Table owners and superusers bypass RLS unless `FORCE ROW LEVEL SECURITY` is set — relying on the app role is cleaner.
+- **MUST** include `WITH CHECK`, or a tenant can write rows belonging to another tenant.
+- **MUST** set the tenant per unit of work with **`SET LOCAL app.tenant_id = '…'` inside an explicit transaction** so it can't leak across pooled connections.
+- **MUST NOT** grant `BYPASSRLS` to the application role, ever.
+- **SHOULD** read the GUC safely: `current_setting('app.tenant_id', true)` (missing-ok) to avoid errors when unset.
+
+### EF Core 10 / Npgsql wiring (defense in depth)
+
+- Add an EF Core **global query filter** (`HasQueryFilter(e => e.TenantId == _tenantId)`) for ergonomics **and** keep DB-side RLS as the real guarantee.
+- Set the session variable via a `DbConnectionInterceptor` / `SaveChanges` hook using **`SET LOCAL` within a transaction**.
+- **PgBouncer transaction pooling**: a plain `SET` leaks across tenants on connection reuse — `SET LOCAL` in a transaction resets at commit and is mandatory in that setup. With DbContext pooling, reset the tenant per scope.
+- Silo (DB-per-tenant) in EF Core: swap the **connection string** via an interceptor / `IDbContextFactory`; use `IModelCacheKeyFactory` if per-tenant schemas diverge.
+
+## PostgreSQL 18 features to use (released Sept 2025)
+
+- **`uuidv7()`** — timestamp-ordered UUIDs; far better index locality than v4. **Default PK type for new entities.**
+- **Asynchronous I/O** (`io_method`) — up to ~3× faster scans/vacuum.
+- **B-tree skip scan** — eases composite-index design (but still lead with `tenant_id`).
+- **Virtual generated columns** (now the default) and **`RETURNING OLD/NEW`** for audit trails.
+- **OAuth/OAUTHBEARER** auth method in `pg_hba.conf`.
+
+## Partitioning & indexing
+
+- Hash-partition high-volume tables by `tenant_id` to spread load and enable partition pruning on `WHERE tenant_id = …`.
+- **MUST** lead every composite index with `tenant_id` (e.g. `(tenant_id, created_at DESC)`); unique constraints must include the partition key.
+- Keep partition counts modest (4/8/16) — thousands degrade planning.
+
+```sql
+CREATE TABLE orders (
+  id UUID NOT NULL DEFAULT uuidv7(),
+  tenant_id UUID NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL,
+  PRIMARY KEY (tenant_id, id)
+) PARTITION BY HASH (tenant_id);
+
+CREATE INDEX ix_orders_tenant_created ON orders (tenant_id, created_at DESC);
+```
+
+## Tenant catalog (control plane)
+
+A small, separate DB — the "phone book" that answers *"where does each tenant live?"* It is **not** any microservice's DB; it's shared platform infrastructure (see [`shared-vs-owned.md`](shared-vs-owned.md)).
+
+```sql
+CREATE TABLE tenant_connections (
+  tenant_id UUID NOT NULL,
+  microservice VARCHAR(100) NOT NULL,
+  connection_string VARCHAR(500) NOT NULL,
+  is_silo BOOLEAN NOT NULL DEFAULT false,
+  PRIMARY KEY (tenant_id, microservice)
+);
+```
+
+Request flow: extract `tenant_id` from JWT → look up routing (**cache in Redis**, >99% hit) → open connection to the right DB → `SET LOCAL app.tenant_id` → RLS applies automatically.
+
+- **MUST** carry `tenant_id` in the JWT (identity), **not** the connection string (location). Location is resolved server-side; putting it in the JWT leaks infrastructure and breaks on silo promotion.
+- **SHOULD** invalidate the Redis routing cache via Pub/Sub when a tenant is moved.
+
+## Promotion pool → silo (operational, not architectural)
+
+Create the silo DB → copy the tenant's rows (logical replication for near-zero downtime) → verify → update the tenant catalog (`is_silo = true`) + invalidate cache → clean the pool. **No code change** — it's a control-plane operation.
+
+## Scaling beyond one node
+
+Reach for **Citus** (first-party in Azure Cosmos DB for PostgreSQL) only after vertical scaling + partitioning are exhausted; shard by `tenant_id` as the distribution column with colocated tables.
+
+## Anti-patterns
+
+- Application-only isolation (no RLS) → one missing `WHERE` leaks data across tenants.
+- `BYPASSRLS` on the app role → silently defeats every policy.
+- Connection string in the JWT → infra leak + stale routing after promotion.
+- Per-microservice routing tables instead of a central catalog → reintroduces distributed coordination.
+
+## Sources
+
+- PostgreSQL 18 release notes — https://www.postgresql.org/docs/18/release-18.html
+- PostgreSQL RLS — https://www.postgresql.org/docs/18/ddl-rowsecurity.html
+- AWS SaaS Lens (silo/pool/bridge) — https://docs.aws.amazon.com/wellarchitected/latest/saas-lens/silo-pool-and-bridge-models.html
+- EF Core multitenancy — https://learn.microsoft.com/en-us/ef/core/miscellaneous/multitenancy

package/standards/backend/architecture/public-api-facade.md

@@ -0,0 +1,112 @@
+---
+title: Public API Facade
+platform: backend
+track: distributed-architecture
+load_when: "Exposing the platform to external consumers — gateway, contracts, webhooks, auth, versioning."
+updated: 2026-06
+---
+
+# Public API Facade
+
+The public layer of a platform. **Contracts are the product**: OpenAPI for sync, AsyncAPI for events. Their versioning discipline is what makes a platform (vs an app) — third parties depend on them.
+
+## Pieces
+
+- **API Gateway** — single entry point for inbound HTTP (`api.org.com`).
+- **Microservices** — each owns its OpenAPI + AsyncAPI, exposed via the gateway.
+- **Webhook Dispatcher** — delivers events to external subscribers.
+- **Identity Provider** — issues JWTs.
+- **Developer Portal** — aggregated docs, sandbox, credential & subscription management.
+
+## Two channels
+
+| | REST API | Webhooks |
+|---|---|---|
+| Direction | consumer → platform | platform → consumer |
+| Model | synchronous | asynchronous |
+| Contract | **OpenAPI 3.1** | **AsyncAPI 3.0** |
+| Versioning | `/v1/`, `/v2/` | `EventV1`, `EventV2` |
+| Auth | JWT (`Authorization`) | HMAC signature |
+| Idempotency | `Idempotency-Key` | `eventId` |
+
+## API Gateway
+
+Creates the illusion of one platform over many services: routing by path, central JWT auth, rate limiting, observability, version routing, single public URL.
+
+- **2026 default for .NET: YARP 2.x** (first-class reverse proxy). Use Kong/Envoy for polyglot estates; Azure APIM / AWS API Gateway when you need a managed portal/quotas.
+- **MUST** authenticate at the gateway; downstream services trust that a request that arrived is authenticated.
+
+## OpenAPI (.NET 10)
+
+- **MUST** use the built-in `Microsoft.AspNetCore.OpenApi` (`AddOpenApi()`), which emits **OpenAPI 3.1** by default at `/openapi/{document}.json`. Swashbuckle is no longer in the default templates.
+- **MUST** serve a docs UI with **Scalar** (`app.MapScalarApiReference()`) — **Development only**.
+- **SHOULD** lint the spec with **Spectral** in CI and generate client SDKs from it at build time (`IOpenApiDocumentProvider`).
+- Each microservice owns its OpenAPI; the portal aggregates them (like Stripe/Twilio/Shopify: monolithic docs outside, N independent APIs inside).
+
+## Errors — Problem Details (RFC 9457)
+
+All endpoints return errors as `application/problem+json` per **RFC 9457** (which obsoletes RFC 7807). .NET's `Results.Problem`/`ProblemDetails` aligns.
+
+```json
+{
+  "type": "https://api.org.com/errors/sku-duplicate",
+  "title": "Duplicate SKU",
+  "status": 409,
+  "detail": "A product with SKU 'ABC123' already exists in this tenant",
+  "instance": "/api/v1/catalog/products",
+  "traceId": "…"
+}
+```
+
+## Versioning & deprecation
+
+- **MUST NOT** make breaking changes within a published version. Breaking change ⇒ new version; both coexist during deprecation (typically 6–12 months).
+- **Non-breaking (same version):** add optional fields, new endpoints, new enum values (carefully), better error messages.
+- **Breaking (new version):** remove/rename fields, change types, make an optional field required, change semantics, remove endpoints.
+- **MUST** design consumers as **tolerant readers** (ignore unknown fields, tolerate missing optionals).
+- **SHOULD** signal end-of-life with the `Deprecation` (RFC 9745) and `Sunset` (RFC 8594) headers + a public changelog.
+
+## Authentication (OAuth 2.1)
+
+- Machine-to-machine integrators use the **`client_credentials`** grant; prefer **`private_key_jwt`** over shared secrets.
+- JWT carries **identity** (`sub`, `tenant_id`, `scope`), short TTL, asymmetric keys (RS/ES) with JWKS rotation, validated `aud`/`iss`/`exp`.
+- The `tenant_id` claim scopes the integrator to its tenant — it cannot push data to another.
+- **SHOULD** use sender-constrained tokens (**DPoP**, RFC 9449) or **mTLS** (RFC 8705) on high-value APIs.
+
+Scopes are per API + action: `catalog:read`, `catalog:write`, `sales:write`, …
+
+## Webhooks (Standard Webhooks)
+
+Follow the **Standard Webhooks** baseline:
+
+- **MUST** sign every payload with **HMAC-SHA256**; send `webhook-id`, `webhook-timestamp`, `webhook-signature` headers; support versioned signatures for key rotation.
+- **MUST** deliver at-least-once with exponential-backoff retries (e.g. 1m, 5m, 15m, 1h, 6h, 24h) then dead-letter + notify.
+- **MUST** treat consumers as idempotent (dedupe on `eventId`); ack fast with 2xx.
+- **MUST** reject on signature mismatch or stale timestamp (replay protection).
+
+AsyncAPI 3.0 documents the event contracts; the broker stays internal (see [`event-driven.md`](event-driven.md)).
+
+## Your own UI uses the public API
+
+The platform's own UI/PWA **MUST** consume the **same** public contracts as external integrators — **no private APIs**. This forces contract quality, guarantees parity, removes duplication, and surfaces problems via dogfooding (Stripe/Twilio/Shopify do this).
+
+## Standard headers
+
+| Header | Purpose |
+|---|---|
+| `Authorization: Bearer <JWT>` | auth |
+| `Idempotency-Key: <uuid>` | idempotent POSTs |
+| `X-Correlation-Id: <uuid>` | distributed tracing |
+| `webhook-signature` | webhook HMAC (Standard Webhooks) |
+
+## Adding a microservice doesn't break consumers
+
+New context ⇒ create the service + its OpenAPI, add a gateway route, publish docs (+ AsyncAPI if it emits events). Existing services and integrators are unaffected. That non-disruption is the mark of a well-designed facade.
+
+## Sources
+
+- .NET 10 OpenAPI — https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/aspnetcore-openapi?view=aspnetcore-10.0
+- Problem Details RFC 9457 — https://www.rfc-editor.org/rfc/rfc9457
+- Standard Webhooks — https://www.standardwebhooks.com/
+- Sunset header RFC 8594 — https://www.rfc-editor.org/rfc/rfc8594
+- YARP — https://microsoft.github.io/reverse-proxy/

package/standards/backend/architecture/shared-vs-owned.md

@@ -0,0 +1,62 @@
+---
+title: Shared vs Owned Components
+platform: backend
+track: distributed-architecture
+load_when: "Deciding whether a new component belongs to a microservice or is shared platform infrastructure."
+updated: 2026-06
+---
+
+# Shared vs Owned Components
+
+A platform has two kinds of components. Confusing them blurs ownership and makes operations harder.
+
+> **The rule:** each microservice owns its **data** and **domain logic**. **Transport, coordination, and identity** are shared platform infrastructure.
+
+When you see a component, ask:
+- Stores **business domain data**? → owned by a microservice.
+- Runs **business logic**? → owned by a microservice.
+- Only **transports** things between services? → shared.
+- Only **coordinates** access/identity across services? → shared.
+
+## Owned by each microservice
+
+Its transactional database (including enterprise silo DBs); its tables (aggregates, `outbox_messages`, `processed_messages`, projections); its code (the 5 projects); its HTTP endpoints; its event consumers; its **queues and exchanges within** the shared broker; its CI/CD pipeline; its emitted telemetry.
+
+> The broker **cluster** is shared, but each service owns its queues/exchanges inside it — like a shared office building where each company has its own offices.
+
+## Shared platform infrastructure
+
+| Component | Why shared |
+|---|---|
+| **Broker** (RabbitMQ/Kafka) | exists so producers/consumers meet without knowing each other |
+| **API Gateway** | unifies the entry point; one place for auth/rate-limit |
+| **Webhook Dispatcher** | connects internal events to external subscribers |
+| **Identity Provider** | identity must be single platform-wide (SSO) |
+| **Tenant Catalog** | tenant routing must be consistent platform-wide |
+| **Redis (cross-cutting cache)** | caches transversal data (tenant routing, IdP keys) |
+| **Observability stack** | value is correlating all services in one place |
+| **DB engine (infra)** | the *engine* can be shared; the *logical DB* is owned |
+| **Orchestration cluster** (K8s) | shared by nature |
+
+These exist once, operated by the platform team; every service uses them, none "owns" them.
+
+## Deciding for a new component
+
+1. Stores/processes **domain data** of one context? → **owned**.
+2. Cross-cutting transport/coordination/identity? → **shared**.
+3. Needs **consistent state across services**? → **shared**.
+4. Each service would evolve it differently? → **owned**.
+5. Would N copies be redundant/harmful? → **shared**.
+
+Examples: push notifications → shared (transport); PDF generation → likely shared; payment processing → probably an owned `Payments` microservice (it has domain logic); full-text search → owned if one context needs it, shared (with separate indices) if many.
+
+## Why it matters
+
+Clear ownership (who fixes what), boundary discipline (domain teams don't touch shared infra; the platform team doesn't write business logic), clean scaling decisions (per-service vs cluster), a clean cost model (shared = fixed/amortized; owned = scales with services), and fast team onboarding.
+
+## Anti-patterns
+
+- Shared DB between microservices → distributed monolith.
+- A service with its own broker/IdP → breaks the purpose of shared coordination/identity.
+- Private cache for transversal data → invalidation becomes impossible.
+- Domain data living in "shared infrastructure" → it's a mis-named microservice.

package/standards/{backend-standards.md → backend/backend-standards.md}

@@ -1,6 +1,13 @@
+---
+title: Backend Development Standards
+platform: backend
+load_when: "Any backend/.NET implementation — endpoints, handlers, EF Core, validation, testing."
+updated: 2026-06
+---
+
 # Backend Development Standards
 
-> **Note**: For architecture patterns and principles (Clean Architecture, DDD, folder structure), see [architecture-patterns.md](./architecture-patterns.md)
+> **Note**: For architecture principles (Clean Architecture, DDD), see [`../core/clean-architecture-ddd.md`](../core/clean-architecture-ddd.md). For microservice structure and the distributed-architecture docs, see [`architecture/microservice-anatomy.md`](architecture/microservice-anatomy.md).
 
 ## Technology Stack Standards
 

package/standards/{database-conventions.md → backend/database-conventions.md}

@@ -1,3 +1,10 @@
+---
+title: PostgreSQL Database Conventions
+platform: backend
+load_when: "Designing schema or EF Core mappings — naming, keys, indexes, snake_case."
+updated: 2026-06
+---
+
 # PostgreSQL Database Conventions
 
 ## 1. PostgreSQL Database Conventions

package/standards/backend/technology-stack.md

@@ -0,0 +1,73 @@
+---
+title: Backend Technology Stack
+platform: backend
+load_when: "Any backend/.NET work — the approved stack, ORM strategy, and 2026 library notes."
+updated: 2026-06
+---
+
+# Backend Technology Stack
+
+The approved .NET toolchain. Use these by default; deviations need a stated reason.
+
+| Category | Technology | Version | Notes |
+|---|---|---|---|
+| Runtime | .NET | 10 (LTS, support to Nov 2028) | C# 14 |
+| API style | Minimal API | — | endpoint grouping, `TypedResults` |
+| Primary ORM | Entity Framework Core | 10 | CRUD, aggregates, tracking, migrations |
+| Performance ORM | linq2db | latest | hot-path queries without tracking |
+| Runtime filters | System.Linq.Dynamic.Core | latest | string-based dynamic filters (sanitize!) |
+| Composable predicates | LinqKit | latest | type-safe predicate composition over EF Core |
+| Database | PostgreSQL | 18+ (mandatory) | `uuidv7()` PKs, RLS, partitioning |
+| Validation | FluentValidation | latest | format/structural validation |
+| API docs | OpenAPI (built-in `Microsoft.AspNetCore.OpenApi`) + **Scalar** | — | 3.1 by default; Scalar UI dev-only; **not** Swagger |
+| Orchestration (local + deploy) | .NET Aspire | 13 | service discovery, telemetry, integrations |
+| Gateway | YARP | 2.x | first-class .NET reverse proxy |
+| Testing | xUnit + Testcontainers | latest | EF InMemory for pure unit only |
+| Resilience | Microsoft.Extensions.Resilience (Polly v8) | latest | retries, timeouts, circuit breakers |
+| Observability | OpenTelemetry | latest | traces/metrics/logs (Aspire wires it) |
+| Mediation & messaging | Wolverine | latest | MIT; CQRS mediation + message bus + Outbox |
+| PDF | PdfSharp / MigraDoc | 6+ | MIT; documents (invoices, reports) |
+
+## Open-source-only policy
+
+This stack is **100% open source under permissive licenses**. Every dependency MUST be **MIT, Apache-2.0, BSD, ISC or the PostgreSQL License**.
+
+- **MUST NOT** introduce source-available / revenue-gated libraries — notably **MediatR, AutoMapper, MassTransit** (commercial since 2025–2026) and **QuestPDF** (free only under a revenue cap; never for public-sector or publicly-traded companies).
+- **MUST NOT** introduce network-copyleft (AGPL — e.g. **iText**) or commercial PDF/reporting SDKs (**Syncfusion, Aspose, IronPDF**).
+- **MUST** verify a dependency's license before adding it. For **open-core** projects (e.g. Wolverine/Marten), confirm you use the **MIT core**, not a commercial add-on.
+- Old MIT versions of the now-commercial libraries are archived/unmaintained — don't pin to them for new work.
+
+### Approved OSS replacements
+
+| Instead of (non-OSS) | Use (OSS) | License |
+|---|---|---|
+| MediatR | **Wolverine** (mediation + bus + Outbox) or the `Mediator` source-generator | MIT |
+| MassTransit | **Wolverine** | MIT |
+| AutoMapper | **Mapperly** (source-generated) or hand-written mapping | Apache-2.0 |
+| QuestPDF | **PdfSharp / MigraDoc**, or **PuppeteerSharp / Playwright** for HTML→PDF | MIT |
+
+## Multi-ORM strategy — when to use each
+
+### EF Core 10 — primary
+Use for: standard CRUD, DDD aggregates with tracking and domain events, simple-to-moderate queries, navigation properties, anything in the aggregate lifecycle.
+
+### linq2db — performance
+Use for: highly optimized read queries, complex projections/joins EF can't translate well, analytics/dashboards/reports, high-volume endpoints, tracking-free reads.
+Do **not** use for: full DDD aggregates with tracking/events, or trivial filters.
+
+### System.Linq.Dynamic.Core — runtime filters
+Use for: API-driven dynamic filters/sorts (`?filter=Age > 30 AND Country == "CO"`), configurable grids, data explorers.
+Do **not** use when: filters are fixed in code, you need strict security without sanitization, or you need maximum performance (use LinqKit/linq2db).
+
+### LinqKit — composable predicates
+Use for: composable business-rule predicates with type safety, combining multiple conditions in one `Where()`, reusable repository queries that still translate through EF Core.
+Do **not** use when: filters are trivial, text-based dynamic (use Dynamic.Core), or need max performance (use linq2db).
+
+## Rules
+
+- **MUST** use `DateTimeOffset` for timestamps, never `DateTime`.
+- **MUST** use `Guid` (UUID, prefer `uuidv7()` server-side) primary keys for all entities.
+- **MUST** document the API with built-in OpenAPI; serve Scalar UI in Development only.
+- **MUST** run integration tests against real PostgreSQL via Testcontainers.
+- **SHOULD** orchestrate the local dev environment with .NET Aspire.
+- **SHOULD** put resilience policies on every outbound HTTP call.

package/standards/core/ai-collaboration.md

@@ -0,0 +1,64 @@
+---
+title: AI Collaboration Standard
+platform: all
+load_when: "Always. How AI coding agents should consume and apply this standards library."
+updated: 2026-06
+---
+
+# AI Collaboration Standard
+
+This library is designed to be read by **AI coding agents** (Claude Code, Cursor, Copilot, etc.) as much as by humans. This document defines how an agent loads, prioritizes, and applies these standards.
+
+## How to read this library
+
+1. **Start at the index.** The installed `coding-standards/INDEX.md` lists only the standards active in *this* project, each with a one-line "load when" trigger. Read it first.
+2. **Load on demand.** Don't load every file. Pull the standard that matches the task (e.g. UI work → `web/_base/frontend-standards.md`; an event handler → `backend/architecture/event-driven.md`). Each file's front-matter has a `load_when` hint.
+3. **Respect precedence.** When rules appear to conflict: a more specific platform/track doc overrides a general one, and `MUST` overrides `SHOULD`. Surface the conflict to the user rather than guessing.
+
+## How rules are written (and how to obey them)
+
+This library uses RFC 2119 keywords. Treat them literally:
+
+- **MUST / MUST NOT** — hard constraint. Never violate without explicit user approval.
+- **SHOULD / SHOULD NOT** — strong default. Deviate only with a stated reason.
+- **MAY** — discretionary.
+
+Rules are imperative bullets, often paired with **DO / DON'T** examples. Pattern-match to the examples — they encode the intent more precisely than prose.
+
+## Agent guardrails
+
+- **MUST NOT** introduce a dependency, framework, or pattern that contradicts the project's active standards. If the task seems to require one, ask first.
+- **MUST** follow the [language rule](coding-conventions.md): code/comments/logs in English, user-facing text in Spanish.
+- **MUST** write tests per [`testing-strategy.md`](testing-strategy.md) and never claim untested code is tested.
+- **MUST** place code where the architecture dictates (see [`clean-architecture-ddd.md`](clean-architecture-ddd.md)) instead of inventing new top-level structure.
+- **MUST** verify that any file, symbol, version, or flag named in a standard still exists in the codebase before acting on it — standards can drift from code.
+- **SHOULD** prefer the smallest change that satisfies the request; do not add speculative abstractions or modules.
+- **SHOULD** cite the standard and section that drove a decision when explaining your work (e.g. "per `event-driven.md` → Idempotency").
+
+## Keeping standards agent-friendly (for authors)
+
+When editing or adding a standard:
+
+- **MUST** give every file YAML front-matter: `title`, `platform`/`track`, `load_when`, `updated`.
+- **MUST** state rules as imperative MUST/SHOULD bullets, not narrative paragraphs.
+- **SHOULD** include at least one DO/DON'T or good/bad code pair per non-trivial rule.
+- **SHOULD** keep each file focused on one topic and reasonably short — agents pay tokens for everything they load.
+- **SHOULD NOT** hardcode volatile facts (exact patch versions, file lists) the agent can read from source; date-stamp instead and review.
+- **MUST NOT** duplicate a rule across files — link to the single source of truth.
+
+## Relationship to AGENTS.md / CLAUDE.md
+
+The cross-vendor convention in 2026 is a root **`AGENTS.md`** as the single instruction file, with tool-specific files (`CLAUDE.md`, `.github/copilot-instructions.md`, `.cursor/rules/`) acting as thin pointers to it. A project using this library SHOULD add a root `AGENTS.md` whose body points the agent to `coding-standards/INDEX.md` as the standards source of truth.
+
+```md
+<!-- AGENTS.md -->
+# Project agent instructions
+Coding standards live in `coding-standards/`. Read `coding-standards/INDEX.md`
+first and load standards on demand per their `load_when` triggers.
+```
+
+## References
+
+- AGENTS.md convention — https://agents.md
+- Anthropic — Claude Code best practices — https://www.anthropic.com/engineering/claude-code-best-practices
+- RFC 2119 (requirement keywords) — https://www.rfc-editor.org/rfc/rfc2119

package/standards/core/clean-architecture-ddd.md

@@ -0,0 +1,69 @@
+---
+title: Clean Architecture & Domain-Driven Design
+platform: all
+load_when: "Always. The architectural foundation every other standard assumes."
+updated: 2026-06
+---
+
+# Clean Architecture & Domain-Driven Design
+
+This is the architectural foundation shared by **every** platform in this library (backend, web, mobile). Platform docs build on these rules; they never contradict them.
+
+## The dependency rule
+
+Dependencies point **inward**, toward the domain. Inner layers know nothing about outer layers.
+
+```
+Presentation  →  Application  →  Domain  ←  Infrastructure
+   (UI/API)       (use cases)    (rules)     (DB, HTTP, SDKs)
+```
+
+- **Domain** depends on **nothing**. No framework, no ORM, no HTTP, no UI library. Pure language constructs, testable in isolation.
+- **Application** depends only on Domain. Orchestrates use cases; declares interfaces it needs.
+- **Infrastructure** depends on Application + Domain — it *implements* the interfaces Application declares (dependency inversion).
+- **Presentation** depends on Application. Translates external input (HTTP request, UI event) into use-case calls.
+
+> **The litmus test:** you must be able to swap the database, message broker, HTTP framework or UI library by touching **only Infrastructure/Presentation**. If a domain change is forced by a tech change, the dependency rule is broken.
+
+## Layer responsibilities
+
+| Layer | Owns | MUST NOT |
+|---|---|---|
+| **Domain** | Entities, value objects, aggregates, domain events, invariants, domain services | Reference any framework or I/O |
+| **Application** | Use cases (commands/queries), DTOs, port interfaces, orchestration | Contain business rules or touch I/O directly |
+| **Infrastructure** | Repository impls, ORM mappings, API clients, external SDKs | Contain business rules |
+| **Presentation** | Endpoints/components, routing, (de)serialization, auth checks | Contain business rules or access data directly |
+
+## DDD building blocks
+
+- **Aggregate** — a cluster of objects treated as one unit, with a **root** that guards invariants. Loaded and persisted atomically. References other aggregates **by ID**, never by direct object reference.
+- **Entity** — has identity that persists across changes.
+- **Value Object** — immutable, defined by its attributes (`Money`, `Email`, `Sku`). Validates on construction.
+- **Domain Event** — an immutable fact, named in the past tense (`OrderConfirmed`), emitted by an aggregate when something business-relevant happens.
+- **Domain Service** — a domain operation that doesn't belong to a single entity.
+- **Repository** — one per aggregate root; loads/saves the whole aggregate; exposes use-case methods, not raw query builders.
+
+## Core rules
+
+- **MUST** keep business rules in the Domain. Validators check **format**; the domain enforces **rules**.
+
+  | Format (validator) | Rule (domain) |
+  |---|---|
+  | "SKU is required, max 50 chars" | "an order with no lines cannot be confirmed" |
+  | "email has valid shape" | "a cancelled order cannot be confirmed again" |
+
+- **MUST** expose behavior, not setters. Aggregates have methods (`confirm()`, `cancel()`), not public mutable state.
+- **MUST** organize code by **business module / domain / feature**, not by technical layer at the top level.
+- **MUST** keep aggregates small. If an aggregate has dozens of sub-entities, it is probably several aggregates linked by ID.
+- **SHOULD** protect the domain from external models with an **Anticorruption Layer** when consuming another context's data.
+- **SHOULD NOT** build anemic models (only getters/setters + a CRUD service). If the domain has no behavior, it is a table with an API on top, not a domain.
+
+## Why this matters for AI-assisted development
+
+A consistent, layered structure lets an AI agent (and a human) predict **where** code goes without re-reading the whole repo: a rule → Domain; an orchestration → Application; a DB detail → Infrastructure; an endpoint/screen → Presentation. The structure is the map.
+
+## Platform specifics
+
+- Backend layering & microservice anatomy → [`backend/architecture/microservice-anatomy.md`](../backend/architecture/microservice-anatomy.md)
+- Web layering & folders → [`web/_base/frontend-architecture.md`](../web/_base/frontend-architecture.md)
+- Mobile layering → `mobile/<framework>/` standards

package/standards/core/coding-conventions.md

@@ -0,0 +1,66 @@
+---
+title: Coding Conventions
+platform: all
+load_when: "Always. Cross-cutting naming, language, and git conventions."
+updated: 2026-06
+---
+
+# Coding Conventions
+
+Cross-cutting conventions that apply to every platform. Platform docs may add specifics but never contradict these.
+
+## Language rule
+
+- **MUST** write all **code, identifiers, comments, logs, commit messages and technical docs in English**.
+- **MUST** write all **user-visible text in Spanish** (UI labels, validation messages shown to users, emails). Use i18n/l10n resources — never hardcode user-facing strings in components.
+- **Rationale:** English code keeps the codebase universally maintainable; Spanish UI serves the product's users.
+
+## Naming
+
+| Element | Convention | Example |
+|---|---|---|
+| C# types / methods | PascalCase | `OrderService`, `ConfirmOrder` |
+| C# locals / params | camelCase | `orderId` |
+| TS/JS components | PascalCase file & symbol | `OrderCard.tsx` |
+| TS/JS variables / functions | camelCase | `useOrderCart` |
+| TS/JS constants | UPPER_SNAKE_CASE | `MAX_RETRIES` |
+| Dart classes | PascalCase | `OrderRepository` |
+| `data-testid` | kebab-case | `order-card-submit` |
+| Files (non-component) | kebab-case | `api-client.ts` |
+| Folders | kebab-case | `use-cases/` |
+
+Database naming (snake_case, FKs, PKs) is defined in [`backend/database-conventions.md`](../backend/database-conventions.md).
+
+## Type safety
+
+- **MUST** enable TypeScript `strict` mode (web/React Native) — no implicit `any`.
+- **MUST** use nullable reference types and treat warnings as errors where the team config allows (C#).
+- **MUST** use sound null safety (Dart).
+- **SHOULD** model illegal states as unrepresentable (discriminated unions, value objects) rather than runtime checks.
+
+## Git & commits
+
+- **MUST** use Conventional Commits: `type(scope): summary` (`feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `perf`).
+- **MUST NOT** commit secrets, `.env` files, or generated artifacts. Honor `.gitignore`.
+- **SHOULD** keep commits small and scoped to one logical change.
+- **SHOULD** branch off the default branch for any non-trivial change; never force-push shared branches.
+
+## Comments
+
+- **MUST** explain *why*, not *what*. The code already says what it does.
+- **MUST NOT** leave commented-out code in commits.
+- **SHOULD** match the comment density of surrounding code.
+
+## Dependency licensing (open-source only)
+
+- **MUST** use only dependencies under **permissive OSS licenses**: MIT, Apache-2.0, BSD, ISC, PostgreSQL License.
+- **MUST NOT** introduce **source-available / revenue-gated** libraries (e.g. MediatR, AutoMapper, MassTransit, QuestPDF), **network-copyleft** licenses (AGPL, e.g. iText), or **commercial SDKs** (Syncfusion, Aspose, IronPDF).
+- **MUST** verify a dependency's license **before** adding it. For **open-core** projects, confirm the piece you use is the OSS core, not a commercial add-on.
+- **SHOULD** prefer a well-maintained OSS option over a feature-richer non-OSS one. Per-platform approved replacements live in each track's technology-stack doc.
+
+## Security baseline
+
+- **MUST** validate and sanitize all external input at the boundary.
+- **MUST** keep secrets in configuration/secret managers, never in source.
+- **MUST** use parameterized queries / ORM — never string-concatenated SQL.
+- **SHOULD** apply least privilege everywhere (DB roles, API scopes, tokens).

package/standards/core/testing-strategy.md

@@ -0,0 +1,46 @@
+---
+title: Testing Strategy
+platform: all
+load_when: "Always. Defines test types, the pyramid, and coverage expectations."
+updated: 2026-06
+---
+
+# Testing Strategy
+
+Test-Driven Development is the default: write tests **before or alongside** implementation. A task is not done until its tests exist and pass 100%.
+
+## The pyramid
+
+```
+        ╱ E2E ╲          few — critical user journeys only
+      ╱ Integration ╲    some — features, repos, API contracts
+    ╱   Unit tests    ╲  many — use cases, domain rules, components
+```
+
+- **MUST** cover every domain invariant and business rule with a unit test, including the violation case.
+- **MUST** cover every use case (command/query handler) with a unit test.
+- **MUST** keep ≥ 80% line coverage on Domain + Application layers.
+- **SHOULD** test features end-to-end at the integration level (real DB via containers where applicable).
+- **SHOULD** reserve E2E for critical paths (login, checkout, the few flows that must never break).
+
+## By platform
+
+| Platform | Unit | Component / Integration | Mocking |
+|---|---|---|---|
+| Backend (.NET) | xUnit | Integration tests with **Testcontainers** (real PostgreSQL); EF Core InMemory only for fast pure-unit cases | substitute ports/interfaces |
+| Web (React) | Vitest | React Testing Library | **MSW** for API mocking |
+| Flutter | `flutter_test` | widget + integration tests | `mocktail` |
+| React Native | Jest / Vitest | RN Testing Library | MSW |
+
+## Rules
+
+- **MUST NOT** claim a test exists or passes unless it actually does. Never fabricate test results.
+- **MUST** make tests deterministic — no reliance on wall-clock time, network, or ordering. Inject clocks and randomness.
+- **MUST** run the full suite after each task; never proceed on a red suite.
+- **SHOULD** name tests by behavior: `Confirm_WithNoLines_Throws`.
+- **SHOULD** prefer real implementations over mocks for value objects and pure domain logic; mock only at architectural boundaries (ports).
+- **SHOULD** add a regression test for every bug fixed.
+
+## What good coverage looks like
+
+Coverage percentage is a floor, not a goal. A meaningful suite proves: every business rule holds, every invariant rejects illegal input, and every critical user journey works against real infrastructure.

package/standards/{mobile-flutter-standards.md → mobile/flutter/flutter-standards.md}

@@ -1,6 +1,14 @@
+---
+title: Flutter Development Standards
+platform: mobile
+track: flutter
+load_when: "Building a Flutter app — Riverpod, GoRouter, Clean Architecture, Material 3."
+updated: 2026-06
+---
+
 # Mobile Flutter Development Standards
 
-> **Note**: For shared architectural principles (Clean Architecture, DDD, design philosophy), refer to [architecture-patterns.md](./architecture-patterns.md). For design system (colors, typography, UX), refer to [technical-preferences-ux.md](./technical-preferences-ux.md).
+> **Note**: For shared architectural principles (Clean Architecture, DDD), refer to [`../../core/clean-architecture-ddd.md`](../../core/clean-architecture-ddd.md). For design system (colors, typography, UX), refer to [`../../web/_base/design-system-ux.md`](../../web/_base/design-system-ux.md).
 
 ---