docs: 4 concept pages (event sourcing, hexagonal, Result, multi-tenancy)#21
Merged
docs: 4 concept pages (event sourcing, hexagonal, Result, multi-tenancy)#21
Conversation
…cy) (POM-183) Replaces the placeholders introduced by POM-180 with full content for the four foundational concepts of the framework. Each page: - Explains the "why" before the "how" - Includes an ASCII diagram of the layering or data flow - Cites real Compendium source via GitHub permalinks pinned to ca25347 - Cross-links to the relevant ADR (0001 for Result, 0002/0003 for hexagonal, 0004 for multi-tenancy, 0005 for event sourcing) - Closes with "Where to go next" pointers DocFX build verified locally: 0 errors, 2 cosmetic warnings (one is the ADR template's placeholder syntax from POM-185).
There was a problem hiding this comment.
Pull request overview
Adds full documentation content for four foundational “Concepts” pages, replacing prior placeholders and linking the concepts to the relevant ADRs and source references.
Changes:
- Documented the project’s
Result<T>/Errorapproach and common usage/anti-patterns. - Documented the repository’s hexagonal (ports & adapters) layering model with a worked example.
- Documented the multi-tenant request-boundary validation +
TenantContextpropagation model. - Documented event sourcing fundamentals (aggregates, projections, versioning/upcasting, snapshots) as used in Compendium.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| docs/concepts/result-pattern.md | Replaces placeholder with detailed Result pattern guidance and links to core types. |
| docs/concepts/hexagonal-architecture.md | Replaces placeholder with an explanation of Compendium’s hexagonal layering and examples. |
| docs/concepts/multi-tenancy.md | Replaces placeholder with multi-tenant resolution/validation/isolation guidance and middleware references. |
| docs/concepts/event-sourcing.md | Replaces placeholder with event sourcing overview tied to Compendium primitives and infrastructure. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| return Result.Success(); | ||
| ``` | ||
|
|
||
| For richer composition (`Map`, `Bind`, `Tap`, etc.) see [`Result.Extensions.cs`](https://github.com/sassy-solutions/compendium/blob/ca25347/src/Core/Compendium.Core/Results/) — but use them sparingly. Loud explicit branching is usually clearer than a chain of monadic operators. |
|
|
||
| A few mistakes to avoid: | ||
|
|
||
| - **Wrapping arbitrary exceptions in `Result.Failure`**. If an exception is genuinely unexpected (out of disk, null reference in your code), let it bubble. Catching everything to "return a clean Result" hides bugs. |
| _logger.LogWarning( | ||
| "Tenant validation failed: {Error}. Path: {Path}", | ||
| validationResult.Error.Message, | ||
| SanitizeForLog(context.Request.Path)); |
| } | ||
| ``` | ||
|
|
||
| The configurable bits (which header, which JWT claims, which paths to skip) live on [`TenantValidationMiddlewareOptions`](https://github.com/sassy-solutions/compendium/blob/ca25347/src/Adapters/Compendium.Adapters.AspNetCore/Security/TenantValidationMiddleware.cs#L226). |
| - [Hexagonal Architecture](hexagonal-architecture.md) — `TenantContext` is itself a port, with concrete implementations in adapters | ||
| - [Event Sourcing](event-sourcing.md) — events carry `AggregateId`; tenancy is enforced by the store, not by the event | ||
| - [ADR 0004](../adr/0004-multi-tenancy-strategy.md) — the decision and trade-offs | ||
| - [`samples/02-MultiTenant-WithPostgres`](https://github.com/sassy-solutions/compendium/tree/main/samples/02-MultiTenant-WithPostgres) — runnable two-tenant example |
| - [Hexagonal Architecture](hexagonal-architecture.md) — how aggregates stay decoupled from infrastructure | ||
| - [Multi-tenancy](multi-tenancy.md) — how events stay scoped to the right tenant | ||
| - [ADR 0005 — Event sourcing over state-stored](../adr/0005-event-sourcing-vs-state.md) — the decision and trade-offs | ||
| - [`samples/01-QuickStart-OrderAggregate`](https://github.com/sassy-solutions/compendium/tree/main/samples/01-QuickStart-OrderAggregate) — a runnable in-memory example |
4 tasks
Pomdapis
added a commit
that referenced
this pull request
Apr 26, 2026
## Summary PR #23 incorrectly bumped CHANGELOG to `[1.0.0-preview.2] - 2026-04-26` with the quality-sweep entries — but tag `v1.0.0-preview.2` was already cut on **2026-04-25** from a different commit set (PRs #1-7) and **already published to nuget.org** (`Compendium.Core 1.0.0-preview.2` is live). Reusing that version was a mistake. This PR reconciles the CHANGELOG with the published reality and rolls today's work into a new **preview.3**: ### `[1.0.0-preview.2] - 2026-04-25` — rewritten retroactively Now matches the auto-generated GitHub release notes for `v1.0.0-preview.2`: - **Added** — `Compendium.Adapters.Shared` (PII masking utilities, introduced in #3). - **Changed** — Dependabot bumps #4-7, OSS governance scaffolding. - **Security** — workflow `permissions:` block (#1), tenant log sanitization (#2), email removal from adapter logs / GDPR (#3). ### `[1.0.0-preview.3] - 2026-04-26` — new Everything since `v1.0.0-preview.2`: - **Added** — DocFX site (#17), 5 ADRs (#14), public ROADMAP (#15), getting-started guide (#20), 4 concept pages (#21), 8 adapter how-to guides (#22). - **Changed** — CodeQL Default Setup → `extended` query suite. - **Security** — `softprops/action-gh-release` pinned to commit SHA (#16, alert #28 closed). ## Test plan - [ ] CI green on this PR. - [ ] After merge, tag `v1.0.0-preview.3` triggers Release workflow successfully. - [ ] `Compendium.* @ 1.0.0-preview.3` published on nuget.org. - [ ] GitHub Release `v1.0.0-preview.3` created with auto-generated notes. VK: POM-186 (Code Quality sweep parent). Co-authored-by: sacha <sacha@scojhconsult.com>
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes POM-183. Replaces the placeholders from POM-180 with full content for the four foundational concept pages.
event-sourcing.mdhexagonal-architecture.mdresult-pattern.mdResult<T>,Error, anti-patterns, structured error typesmulti-tenancy.mdQuality choices
ca25347(the latest commit on main when this PR was opened) — no invented APIs.Validation
DocFX build verified locally: 0 errors. The 2 remaining warnings are pre-existing (template placeholder syntax in POM-185's ADR template).
Test plan
docfx build docs/docfx.jsonsucceeds locally/main/concepts/<page>.htmlafter merge