docs(readme): rewrite for Trellis V3 / .NET 10 + replace stale PNG diagrams with Mermaid - #33
Merged
Merged
Conversation
…agrams with Mermaid
The README was still referencing .NET 7, EF Core, and the predecessor
FunctionalDDD library, and the three readme-assets/*.png Clean Architecture
diagrams were generic stock images that did not reflect what this codebase
demonstrates. Both have been replaced.
The new README is structured for two audiences: developers evaluating
Trellis V3, and developers using BuberDinner as a reference for "how do I do
X in this stack". It includes:
- 1-paragraph hook + "What it demonstrates" bullet list
- Current stack table + Trellis package table
- 3-step Quickstart (dotnet build / test / run)
- Tour table of the 7 merged showcase PRs with link-out to each
Docs/PR*.md walkthrough
- Inline Mermaid architecture diagram showing the actual layers and
how Trellis V3 plugs into each
- Inline Mermaid aggregate-relationships diagram (User, Host, Menu,
Dinner, Reservation, MenuReview) with their FK relationships and
cross-aggregate gates
- API surface table summarizing each endpoint family
- Cross-cutting patterns table linking to the right walkthrough for
each pattern (ETag, idempotency, state machines, leak-shielded 404s,
command-boundary validation, ServiceDefaults)
- "Where to look for common tasks" pointer table
- Project layout outline
- .http replay note
- Credits & history (preserves the link to the original YouTube
tutorial series that the project began as)
The three readme-assets PNGs are removed via git rm. Mermaid renders
natively on GitHub so no replacement image files are needed.
Onion diagram ------------- Added readme-assets/clean-architecture-onion.svg - an inline SVG showing the classic Clean Architecture onion (Domain at the centre, Application around it, Api and Infrastructure on the outside) with a dashed equator splitting the outer ring into the Api half and the Infrastructure half, and a "depends on" arrow pointing inward on the right edge to make the dependency rule visible. The SVG is a hand-written ~5KB file with no external dependencies; GitHub renders it inline through the standard image-link syntax. It complements the existing Mermaid runtime-flow diagram without replacing it. Code-review fixes (from PR #33 review) -------------------------------------- 1. API version disambiguation (Medium) The "API surface at a glance" section previously said the controllers are "under the versioned 2022-12-21 controller set". That date is the source- tree folder name, not the wire version. Every controller in that folder declares [ApiVersion("2022-10-01")], so the api-version query parameter the client must send is 2022-10-01. Reworded to state both explicitly and call out the required query-string value. 2. Trellis.Authorization vs Trellis.Http.Abstractions (Low) The Trellis packages table listed Trellis.Authorization but that package has no direct PackageReference in any .csproj - it's pulled in transitively via Trellis.Mediator. Meanwhile Trellis.Http.Abstractions IS a direct dependency of the Application project but was missing from the table. Added a row for Trellis.Http.Abstractions and qualified the Trellis.Authorization entry with "(pulled in transitively via Trellis.Mediator)". 3. replay-http.py reference (Low) The .http replay paragraph referenced a "local session-state helper named replay-http.py" that does not live in the repo (it's a session artifact). Removed the dangling reference; kept the substantive guidance that `dotnet test` is the durable verification because the integration suite exercises the same endpoints end-to-end.
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
1 participant
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.
Why
The README was severely outdated:
EF Core— codebase is on .NET 10 with in-memory repos by defaultreadme-assets/that didn't reflect what BuberDinner actually demonstratesWhat changed
README.mdfully rewritten for two audiences (Trellis V3 evaluators + reference-implementation hunters):Docs/PR*.mdwalkthrough.httpreplay noteStale PNGs removed via
git rm(readme-assets/clean-architecture-{diagram,diagram-2,detailed}.png). Mermaid renders natively on GitHub so no replacement image files are needed.Verification
Api/src/2022-12-21/Controllers/MenusController.cs,Application/src/MenuReviews/Commands/SubmitMenuReviewCommandHandler.cs)/authentication/registerand/authentication/login(matches[Route("[controller]")]onAuthenticationController)