|
| 1 | +# Copilot Instructions for EventFlow |
| 2 | + |
| 3 | +These guidelines govern contributions within the EventFlow code base hosted at https://github.com/eventflow/EventFlow/. Follow them whenever collaborating in this repository to stay aligned with the project’s expectations. |
| 4 | + |
| 5 | +## Architecture snapshot |
| 6 | +- EventFlow is a CQRS+ES framework; the core runtime lives in `Source/EventFlow` and exposes aggregates, commands, queries, read stores, sagas, jobs, and snapshots. |
| 7 | +- Command flow: clients call `CommandBus` (`Source/EventFlow/CommandBus.cs`) which resolves handlers, invokes aggregates deriving from `AggregateRoot<TAggregate, TIdentity>`, and emits events that pipe through subscribers and read-store dispatchers. |
| 8 | +- Aggregates load and persist via `IAggregateStore`/`IEventStore`; defaults use the in-memory persistence registered in `EventFlowOptions`, while integration packages under `Source/EventFlow.*` swap in specific stores. |
| 9 | +- Read models implement `IReadModel` plus `IAmReadModelFor<...>`; dispatch logic sits in `ReadStores` and uses metadata to map events to view updates. |
| 10 | +- Sagas and jobs live under `Source/EventFlow/Sagas` and `Source/EventFlow/Jobs`, coordinating cross-aggregate workflows and deferred execution. |
| 11 | +- Documentation that explains the concepts is checked in under `Documentation/`; updates should travel with code changes. |
| 12 | + |
| 13 | +## Extension & configuration guide |
| 14 | +- Dependency injection starts with `services.AddEventFlow(o => { ... })` (`Source/EventFlow/Extensions/ServiceCollectionExtensions.cs`); chain option methods to register events, commands, read models, snapshots, sagas, and custom services. |
| 15 | +- Use the fluent helpers in `EventFlowOptions` (`Source/EventFlow/EventFlowOptions.cs`) such as `.AddEvents`, `.AddCommands`, `.UseInMemoryReadStoreFor<TReadModel>()`, `.ConfigureOptimisticConcurrencyRetry(...)`, or `.UseEventPersistence<T>()` to pivot storage/backends. |
| 16 | +- Strongly typed IDs must derive from `Identity<T>` (`Source/EventFlow/Core/Identity.cs`); create new IDs via `ExampleId.New` or `Identity<T>.With(Guid)` to honor prefix validation. |
| 17 | +- When adding domain objects, follow the naming pattern `ThingyAggregate` + `ThingyId` + `ThingyEvent`; see `EventFlow.TestHelpers/Aggregates/Thingy*` for canonical examples including event emit/apply patterns. |
| 18 | +- Integration modules (MongoDB, MsSql, PostgreSql, Redis, SQLite, etc.) expose option extensions in their `Extensions/` folder; replicate those patterns when introducing new infrastructure. |
| 19 | +- Prefer using `EventFlow.TestHelpers` base classes and fixtures when authoring tests so categories, logging, and deterministic IDs behave consistently. |
| 20 | + |
| 21 | +## Build, test, and verification |
| 22 | +- The solution is organized under `EventFlow.sln`; build with `dotnet build EventFlow.sln` (warnings are treated as errors via `Source/Directory.Build.props`). |
| 23 | +- Unit tests target `netcoreapp3.1`, `net6.0`, and `net8.0`; run fast feedback with `dotnet test EventFlow.sln --filter "Category!=integration"` and rely on `EventFlow.TestHelpers.Categories` constants when tagging new suites. |
| 24 | +- Integration tests span external services (MongoDB, PostgreSQL, SQL Server, RabbitMQ, Elasticsearch, EventStore); start containers with `docker-compose up` before executing the corresponding `*.Tests` projects or include the `integration` category filter. |
| 25 | +- Source generators and analyzers live in `Source/EventFlow.SourceGenerators` and `Source/EventFlow.CodeStyle`; ensure the .NET SDK version supports C# 12 and keep analyzer warnings clean. |
| 26 | +- Documentation builds use MkDocs (`requirements.txt`); run `pip install -r requirements.txt` followed by `mkdocs serve` when verifying doc updates. |
| 27 | + |
| 28 | +## Coding conventions & review tips |
| 29 | +- Favor async APIs and accept `CancellationToken` parameters throughout—the core dispatchers expect cooperative cancellation (see `CommandBus.PublishAsync` and `AggregateStore` methods). |
| 30 | +- New events should inherit `AggregateEvent<TAggregate, TIdentity>`, carry immutable data, and rely on aggregate `Apply` methods to mutate state; never mutate state directly inside command handlers. |
| 31 | +- Subscribers and read stores should request dependencies via constructor injection and avoid static singletons; look at `Source/EventFlow/Subscribers` for the expected interface contracts. |
| 32 | +- When wiring new persistence, register required DI services before calling `.UseEventPersistence<T>()` to avoid the `RemoveAll<IEventPersistence>()` guard removing your registration. |
| 33 | +- Keep public APIs binary compatible where possible; breaking changes require updates in `Documentation/` and `RELEASE_NOTES.md`. |
| 34 | +- Mirror existing namespace layout (`EventFlow.{Feature}`) and group files into folders matching their conceptual role to keep source generators and discovery heuristics effective. |
| 35 | + |
| 36 | +## Operational safeguards |
| 37 | +- Avoid invoking GitHub management tools that mutate remote state (issues, pull requests, repositories, projects, workflows, labels, security alerts, notifications, etc.) unless the user has granted explicit permission in the current conversation. |
| 38 | +- Never run mutating `git` commands (commit, push, merge, rebase, reset, clean, etc.) without explicit user authorization; limit `git` usage to read-only inspection by default. |
| 39 | +- If permission is unclear, pause and ask the user before attempting any action that could alter repository or GitHub state. |
0 commit comments