@jeffrey2423/coding-standards 1.0.0 → 2.0.0

package/README.md

@@ -1,204 +1,125 @@
 # Coding Standards & Architecture Guide
 
-Centralized repository of coding standards, architectural patterns, and technical conventions for building enterprise-scale applications. Enforces **Clean Architecture**, **Domain-Driven Design (DDD)**, and **microservices patterns** across all platforms.
+Modern, **AI-ready** coding standards, architectural patterns and technical conventions for building enterprise-scale, greenfield applications. Enforces **Clean Architecture**, **Domain-Driven Design (DDD)** and modern **microservices / microfrontends** patterns across backend, web and mobile.
+
+Designed to be consumed by **AI coding agents** (Claude Code, Cursor, Copilot) as much as by humans: every document carries `load_when` front-matter, and the installer generates an `INDEX.md` telling the agent exactly which standards are active.
 
 ## Quick Start
 
-Copy all coding standards into any project:
+Pick exactly the standards your project needs — interactively:
 
 ```bash
 npx @jeffrey2423/coding-standards
 ```
 
-This creates a `coding-standards/` folder with all standard documents.
-
-## Table of Contents
-
-- [Technology Stack](#technology-stack)
-- [Architecture Overview](#architecture-overview)
-- [Standards by Platform](#standards-by-platform)
-- [Database Conventions](#database-conventions)
-- [Design System & UX](#design-system--ux)
-- [Key Principles](#key-principles)
-- [Document Index](#document-index)
-
-## Technology Stack
-
-### Frontend (Web)
-
-| Category | Technology | Version |
-|----------|-----------|---------|
-| Bundler | Vite | 7+ |
-| Framework | React | 18+ |
-| Language | TypeScript | 5+ (strict mode) |
-| Routing | TanStack Router | 1+ (file-based) |
-| Client State | Zustand | 5+ |
-| Server State | TanStack Query | 5+ |
-| UI Components | shadcn/ui + Radix UI | Latest |
-| Styling | TailwindCSS | v4 |
-| Forms | React Hook Form + Zod | Latest |
-| Testing | Vitest + React Testing Library + MSW | Latest |
-
-### Backend
-
-| Category | Technology | Version |
-|----------|-----------|---------|
-| Runtime | .NET | 10 |
-| Language | C# | Latest (Minimal API) |
-| Primary ORM | Entity Framework Core | 10 |
-| Performance ORM | linq2db | Latest |
-| Database | PostgreSQL | 18+ (mandatory) |
-| Validation | FluentValidation | Latest |
-| Testing | xUnit | Latest |
-| API Docs | Scalar | Latest (NOT Swagger) |
-
-### Mobile
-
-| Platform | Framework | State | Navigation | Styling |
-|----------|-----------|-------|------------|---------|
-| Flutter | Flutter SDK | Riverpod 3+ | GoRouter 14+ | Material Design 3 |
-| React Native | Expo SDK 53+ | Zustand | Expo Router 4+ | NativeWind 4+ (Tailwind) |
-
-### Microfrontends
-
-| Pattern | Usage |
-|---------|-------|
-| **Single-SPA** | **DEFAULT** for all business modules |
-| Module Federation | ONLY for explicitly shared/transversal modules |
-
-## Architecture Overview
-
-All platforms follow **Clean Architecture + DDD** with strict layer separation:
-
 ```
-Domain Layer          → Entities, Value Objects, Aggregates, Domain Events
-    ↑
-Application Layer     → Commands, Queries, Handlers, DTOs, Validators
-    ↑
-Infrastructure Layer  → Repositories, ORM, External Services, API Clients
-    ↑
-Presentation Layer    → UI Components, Routes, Pages, Endpoints
+? What are you building?        ◉ Backend / API (.NET)   ◉ Frontend Web   ◯ Mobile
+? Web architecture:             ● Microfrontends (Module Federation)
+? Backend — distributed arch:   ◉ Multi-tenancy  ◉ Event-driven  ◉ Public API facade ...
+✓ Copied 14 files to coding-standards/
+✓ Generated coding-standards/INDEX.md
 ```
 
-### Frontend Folder Structure
+Or non-interactively (great for CI and AI agents):
 
+```bash
+npx @jeffrey2423/coding-standards --backend --web=microfrontends      # selective
+npx @jeffrey2423/coding-standards --mobile=flutter,react-native --yes # mobile only
+npx @jeffrey2423/coding-standards --all                               # everything
+npx @jeffrey2423/coding-standards --help
 ```
-src/
-├── routes/              # TanStack Router (route definitions only)
-├── modules/             # Business logic (Module/Domain/Feature)
-│   └── sales/           #   MODULE
-│       └── quotes/      #     DOMAIN
-│           └── cart/    #       FEATURE (domain/application/infrastructure/presentation)
-├── shared/              # Reusable components, hooks, types
-├── app/                 # Global config, providers, stores
-├── infrastructure/      # External services (API, storage, PWA)
-├── assets/              # Static resources
-└── styles/              # Global styles
-```
-
-### Backend Project Structure (per Microservice)
-
-```
-Service.Domain/          # Entities, Value Objects, Domain Events
-Service.Application/     # Use Cases, DTOs, Validators, Interfaces
-Service.Infrastructure/  # EF Core, Repositories, External Services
-Service.API/             # Minimal API Endpoints
-Service.Tests/           # xUnit Tests
-```
-
-## Standards by Platform
-
-### Frontend Standards
-
-- **Language Rule**: ALL user-visible text in **Spanish**, code/logs/comments in English
-- TanStack Router with file-based routing conventions (`_` pathless layouts, `$` dynamic params)
-- State split: Zustand (global client) / TanStack Query (server) / useState (local)
-- Component naming: PascalCase files, kebab-case `data-testid`
-- WCAG 2.1 AA accessibility compliance
-- Testing: Unit (use cases) → Integration (features) → Component (RTL) → E2E (critical paths)
-
-### Backend Standards
-
-- **Critical**: Always use `DateTimeOffset` for timestamps (NEVER `DateTime`)
-- Minimal API pattern with endpoint grouping
-- Multi-ORM strategy: EF Core (CRUD) / linq2db (performance) / DynamicLinq (runtime filters)
-- UUID (Guid) primary keys for all entities
-- Database per Microservice pattern
-- TDD with xUnit, InMemory for unit tests, TestContainers for integration
 
-### Mobile Standards
+Only the selected standards are copied into `coding-standards/`, plus an `INDEX.md` that lists them with load triggers and precedence rules.
 
-Both Flutter and React Native follow Clean Architecture + DDD + Feature-First organization with platform-specific tooling.
+### Updating
 
-## Database Conventions
+Re-run the installer any time — it's idempotent. It tracks the files it created in `coding-standards/.standards-manifest.json` and, on each run, removes its previously-installed files (and any leftovers from the flat **v1** layout) before writing the new selection, then prunes empty folders. Your own files in `coding-standards/` are never touched. So upgrading v1 → v2, or changing your selection, leaves no stale or contradictory standards behind.
 
-**PostgreSQL** is the mandatory database engine. Key conventions:
+## How it works
 
-| Element | C# Convention | PostgreSQL Convention | Example |
-|---------|--------------|----------------------|---------|
-| Tables | PascalCase | snake_case | `OrderItems` → `order_items` |
-| Columns | PascalCase | snake_case | `CreatedAt` → `created_at` |
-| Foreign Keys | `{Entity}ID` | `{entity}_id` | `WarehouseID` → `warehouse_id` |
-| Primary Keys | `Guid` | `uuid` | `DEFAULT uuidv7()` |
-| Indexes | - | `ix_{table}_{cols}` | `ix_orders_created_at` |
-| Unique | - | `uk_{table}_{cols}` | `uk_users_email` |
-| Projections | `{PREFIX}_{Entity}Prj` | `{prefix}_{table}_prj` | `AUTH_UserPrj` → `auth_users_prj` |
+Standards are organized into **independent packs** selected at install time:
 
-EF Core handles automatic snake_case conversion via `SnakeCaseNamingConvention` — no manual `[Column]` or `[Table]` attributes needed.
+| Pack | Selection | What you get |
+|---|---|---|
+| **core** | always | Clean Architecture + DDD, coding conventions, testing strategy, AI collaboration |
+| **backend** | `--backend` | .NET standards, tech stack, DB conventions + opt-in architecture docs |
+| **web** | `--web=<track>` | shared web standards + **one** track: `spa` · `single-spa` · `microfrontends` |
+| **mobile** | `--mobile=<fw,...>` | `flutter` and/or `react-native` |
 
-## Design System & UX
+**Single-SPA and Module Federation microfrontends are separate, mutually-exclusive tracks** — pick by need, no forced default.
 
-### Colors
+## Repository structure
 
-| Role | Value | Usage |
-|------|-------|-------|
-| Primary | `#0E79FD` | Brand blue, main actions |
-| Secondary | `#000000` | Brand elements only (NOT backgrounds) |
-| Tertiary | `#154CA9` | Dark blue accents |
-| Neutrals | Tailwind `slate` scale | Backgrounds, borders, text |
-
-### Typography
-
-- **Font**: Inter (Light 300, Regular 400, Bold 700)
-- **Scale**: Tailwind typography utilities (h1–h6, body, interactive)
-
-### Performance Targets
-
-| Metric | Target |
-|--------|--------|
-| Initial Bundle | < 500KB gzipped |
-| First Contentful Paint | < 1.5s |
-| Largest Contentful Paint | < 2.5s |
-| Cumulative Layout Shift | < 0.1 |
+```
+standards/
+├── core/                       # always installed
+│   ├── clean-architecture-ddd.md
+│   ├── coding-conventions.md
+│   ├── testing-strategy.md
+│   └── ai-collaboration.md
+├── backend/
+│   ├── backend-standards.md
+│   ├── technology-stack.md
+│   ├── database-conventions.md
+│   └── architecture/           # opt-in distributed-architecture docs
+│       ├── microservice-anatomy.md
+│       ├── multitenancy.md
+│       ├── event-driven.md
+│       ├── public-api-facade.md
+│       └── shared-vs-owned.md
+├── web/
+│   ├── _base/                  # frontend architecture, stack, design system
+│   ├── spa/                    #   ── pick one web track ──
+│   ├── single-spa/
+│   └── microfrontends/
+└── mobile/
+    ├── flutter/
+    └── react-native/
+```
 
-### Icons & Loading
+## Technology stack (2026)
 
-- Primary icons: **Heroicons**
-- Secondary icons: Font Awesome 6.5+
-- Loading states: `react-loading-skeleton` v3.4.0
+### Backend
+.NET 10 (LTS) · C# 14 Minimal API · EF Core 10 (+ linq2db / Dynamic.Core / LinqKit) · **PostgreSQL 18** (`uuidv7()`, RLS) · FluentValidation · built-in OpenAPI 3.1 + **Scalar** · **.NET Aspire 13** · **YARP** · **Wolverine** · xUnit + Testcontainers · OpenTelemetry · PdfSharp/MigraDoc.
 
-## Key Principles
+> **100% open source** — permissive licenses only (MIT / Apache-2.0 / BSD / PostgreSQL). The now-commercial **MediatR / MassTransit / AutoMapper** and the revenue-gated **QuestPDF** are **excluded** and replaced by **Wolverine**, **Mapperly** and **PdfSharp/MigraDoc**. See `backend/technology-stack.md`.
 
-1. **Clean Architecture** — Strict layer separation with dependency inversion across all platforms
-2. **Domain-Driven Design** — Business logic organized by bounded contexts drives architecture
-3. **Test-Driven Development** — Tests alongside implementation, >80% coverage required
-4. **Type Safety** — TypeScript strict mode (frontend), C# (backend), Dart (Flutter)
-5. **Database per Microservice** — Complete data isolation between services
-6. **UUID Primary Keys** — All entities use UUIDs for distributed system compatibility
-7. **Spanish UI / English Code** — User-facing content in Spanish, codebase in English
-8. **Single-SPA Default** — Microfrontends use Single-SPA; Module Federation only for explicit sharing
-9. **Accessibility First** — WCAG 2.1 AA, 4.5:1 contrast, 44px touch targets, keyboard navigation
+### Web
+Vite 7 · React 19 · TypeScript strict · TanStack Router + Query · Zustand 5 · shadcn/ui + Radix · TailwindCSS v4 · React Hook Form + Zod · Vitest + RTL + MSW. Microfrontends via **Module Federation 2.0** (`@module-federation/enhanced`, dynamic license-gated remotes) or **Single-SPA**.
 
-## Document Index
+### Mobile
+Flutter (Riverpod 3 · GoRouter · Material 3) · React Native (Expo SDK 53+ · Zustand · Expo Router · NativeWind 4).
+
+## Architecture highlights
+
+- **Clean Architecture + DDD** everywhere; strict inward dependency rule.
+- **Multi-tenancy**: hybrid bridge model — pooled + PostgreSQL RLS by default, selective silo, central tenant catalog.
+- **Event-driven**: transactional Outbox, idempotent consumers, sagas with compensation, correlation IDs.
+- **Public API facade**: contracts as product — OpenAPI 3.1 + AsyncAPI 3.0, Standard Webhooks (HMAC), OAuth 2.1, Problem Details (RFC 9457), rigorous versioning. Your own UI uses the public API — no private APIs.
+- **Microfrontends**: products as router layouts, capabilities as remote MFEs, enabled per license without redeploy.
+
+## Key principles
+
+1. **Clean Architecture** — strict layer separation with dependency inversion.
+2. **Domain-Driven Design** — bounded contexts drive the architecture.
+3. **Test-Driven Development** — tests alongside implementation, ≥80% on domain/application.
+4. **Type safety** — TypeScript strict, C#, sound Dart null safety.
+5. **Database per microservice** — complete data isolation.
+6. **UUID (uuidv7) primary keys** — distributed-system friendly.
+7. **Spanish UI / English code** — user-facing text in Spanish, codebase in English.
+8. **Contracts are the product** — public, versioned, backward-compatible.
+9. **Accessibility first** — WCAG 2.1 AA.
+10. **AI-ready** — every standard is loadable on demand via `INDEX.md` and `load_when` front-matter.
+11. **Open source only** — every dependency uses a permissive OSS license; no commercial or revenue-gated libraries.
+
+## Using with AI agents
+
+Add a root `AGENTS.md` pointing your agent at the installed index:
+
+```md
+# Project agent instructions
+Coding standards live in `coding-standards/`. Read `coding-standards/INDEX.md`
+first, then load standards on demand per their `load_when` triggers.
+```
 
-| Document | Description |
-|----------|-------------|
-| [technology-stack.md](standards/technology-stack.md) | Complete technology stack with versions and rationale |
-| [architecture-patterns.md](standards/architecture-patterns.md) | Frontend and backend architectural patterns |
-| [backend-standards.md](standards/backend-standards.md) | .NET backend development standards and conventions |
-| [frontend-standards.md](standards/frontend-standards.md) | React/TypeScript frontend standards and folder structure |
-| [database-conventions.md](standards/database-conventions.md) | PostgreSQL naming conventions and EF Core mapping |
-| [vite-config-standard.md](standards/vite-config-standard.md) | Microfrontend configuration (Single-SPA & Module Federation) |
-| [technical-preferences-ux.md](standards/technical-preferences-ux.md) | Design system, colors, typography, UX guidelines |
-| [mobile-flutter-standards.md](standards/mobile-flutter-standards.md) | Flutter mobile development standards |
-| [mobile-react-native-standards.md](standards/mobile-react-native-standards.md) | React Native mobile development standards |
+See `core/ai-collaboration.md` for the full agent protocol.