dotnet-clean-architecture

Files (7)

• SKILL.md
• cross-module-communication.md
• database-isolation.md
• implementation-playbook.md
• optional-ddd-cqrs.md
• optional-event-sourcing.md
• testing-patterns.md

SKILL.md (first lines)

# .NET Clean Architecture: Minimal API + Hexagonal + Modular

**SOURCE OF TRUTH (SoT):** Minimal API endpoints self-register via `IEndpoint`, and each module
self-registers its DI via `IModule`; both are discovered by reflection in
`GcPlatform.SharedKernel.Modularity.ModuleExtensions`. Each module is a hexagon:
**Domain** (pure logic, zero infrastructure) → **Application** (use cases, ports) ↔
**Infrastructure** (adapters, EF Core or Marten, RLS). **Presentation** composes the module
(endpoints, the `<Module>Module : IModule` registrar) and is the only layer allowed to wire
Infrastructure. Persistence is **chosen per bounded context** — EF Core CRUD and event-sourced
Marten stores are both first-class; there is no global default (ADR-0037, ADR-0048). Modules
communicate asynchronously via serialized integration events over the Wolverine message bus —
events are the **only** inter-module contract (ADR-0014). Per-module language autonomy: the same
real-world entity may be named differently **across** modules, but every module's language MUST be
English, and within a module each concept has exactly one name. Database isolation is one
PostgreSQL schema per module with `FORCE ROW LEVEL SECURITY` (RLS), a per-module GUC
`app.tenant_id`, and lightweight per-module roles (ADR-0013/0038).

**Optional additive patterns** (opt-in per module): DDD (aggregates, value objects, domain
events) and CQRS (separate read/write models). Event Sourcing (Marten event stores) is a
**first-class persistence choice per bounded context**, not an optional add-on. See
[optional-ddd-cqrs.md](optional-ddd-cqrs.md) and [optional-event-sourcing.md](optional-event-sourcing.md).

## Language & Naming (MANDATORY)

All code MUST be written in English — identifiers, comments, and documentation — regardless of
the user's language or the conversation language. French (or any other non-English) identifiers,
comments, or docs are a hard violation. This mirrors the commit-message mandate
(the `git-workflow` skill, Canonical spec, Language).

| Artifact | Rule |
|---|---|
| Identifiers (types, methods, properties, variables, parameters, enums, namespaces, test names) | English, PascalCase/camelCase per C# convention. No French, no accents, no transliteration. |
| Comments & XML docs | English, always. |
| Developer-facing strings (logs, exception messages, ProblemDetails `title`/`detail`) | English. |
| User-facing text | Never hardcoded French in the backend; end-user localization belongs to the frontend (Transloco). |
| DB objects (schemas, tables, columns) | English snake_case. |

**Module names: PascalCase + English.** A module lives directly under `backend/src/` (or under a
bounded-context folder, e.g. `backend/src/Sales/Invoices/`) as a set of projects:
`GcPlatform.<Module>.Domain`, `GcPlatform.<Module>.Application`,
`GcPlatform.<Module>.Infrastructure`, `GcPlatform.<Module>.Presentation`. The module registrar is
`<Module>Module : IModule`, discovered by reflection; the schema name is the lowercase
snake_case module name (e.g. `invoice`). `GcPlatform.Api` is the **host/composition root only**
— it holds no `Module/<ModuleName>/` tree.

**Ubiquitous language.** One canonical English term per domain concept — no synonyms, no ad-hoc
translations. Canonical terms are anchored in `docs/architecture/ubiquitous-language.md` and
aligned with the frontend module names (`invoices`, `payments`, `dunning`, `customers`,
`catalog`). Per-module language autonomy allows different names across modules for the same
real-world entity; it does NOT allow synonyms within a module, and it does NOT allow non-English
names.

## When To Activate

- Scaffolding a new .NET REST API with modular hexagonal architecture.
- Adding a new module or use case to an existing project.
- Adding an endpoint/use-case with EF Core CRUD or an event-sourced Marten store.
- Refactoring code toward ports/adapters and module isolation.
- Integrating with other modules via integration events.

## Architecture Overview

```text
backend/
├── GcPlatform.slnx
├── src/
│   ├── SharedKernel/                         # shared types ONLY — no application logic
│   │   ├── Modularity/
│   │   │   ├── IModule.cs                    # RegisterModule(IServiceCollection)
│   │   │   ├── IEndpoint.cs                  # MapEndpoint(IEndpointRouteBuilder)
│   │   │   └── ModuleExtensions.cs           # reflection discovery (modules + endpoints)
│   │   ├── Tenancy/                          # ITenantContext, AmbientTenant, TenantSessionInterceptor
│   │   └── ...
│   ├── GcPlatform.Api/                       # HOST / composition root (NOT a module tree)
│   │   ├── Program.cs                        # composes bounded contexts + endpoint discovery
│   │   ├── Infrastructure/                   # host cross-cutting wiring (auth, tenancy, DB bootstrap)
│   │   └── ...
│   ├── <Module>/                             # e.g. Identity, McpAccess, ThirdParties, Companies
│   │   ├── GcPlatform.<Module>.Domain/
│   │   │   ├── Aggregates/  (or Entities/)
│   │   │   ├── ValueObjects/
│   │   │   ├── Events/                       # domain events (past-tense records)
│   │   │   ├── Exceptions/
│   │   │   └── Model/
│   │   ├── GcPlatform.<Module>.Application/
│   │   │   ├── <UseCase>/                    # <UseCase>Command.cs, <UseCase>Handler.cs, <UseCase>Result.cs
│   │   │   └── Ports/                        # incoming + outgoing port interfaces
│   │   ├── GcPlatform.<Module>.Infrastructure/
│   │   │   ├── Persistence/                  # DbContext, Configurations/, Migrations/
│   │   │   └── Adapter/                      # outgoing-port adapters (EfCore…, Marten…)
│   │   └── GcPlatform.<Module>.Presentation/
│   │       ├── Endpoints/                    # IEndpoint implementations (+ Requests/, Responses/)
│   │       └── <Module>Module.cs             # IModule registration (composition root of the module)
│   ├── Sales/                                # bounded context made of subdomains
│   │   ├── GcPlatform.Sales.Domain/
│   │   ├── GcPlatform.Sales.Infrastructure/
│   │   ├── GcPlatform.Sales.Presentation/    # SalesModule.ConfigureServices(...)
│   │   ├── GcPlatform.Sales.Contracts/       # integration-event contracts
│   │   ├── Catalog/  Customers/  Invoices/  Payments/  Dunning/  Receivables/
│   │   └── ...                               # each subdomain: Domain + Infrastructure + Presentation
│   └── Conversation/                         # single-project module
└── tests/
    └── GcPlatform.<Module>.Tests/
        ├── Application/  Domain/  Events/  Infrastructure/
        ├── Integration/  Architecture/  Composition/
        └── ...
```

**Layering variance:** a full module (e.g. Identity) has all four projects. Some Sales subdomains
(e.g. Invoices) fold the use cases into the Domain project and ship Domain + Infrastructure +
Presentation only. Match the neighbouring subdomain in the bounded context you are extending.

## Hexagon Rules (Important)

```
Domain (pure logic)
  ↑
  ├── Depends on: NOTHING
  └── Used by: Application + Infrastructure

From fmflurry/settings-opencode, MIT.

More from fmflurry/settings-opencode