Documentation overhaul: Arc#2276
Merged
Merged
Conversation
Add Why Arc, the MediatR/MVC bridge, Vertical slices, Troubleshooting, and backend/frontend getting-started; rewrite the landing; fix broken relative links and non-descriptive link text. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Replace the link list with an aspire.dev-style Overview: a TopicHero banner plus Start here and Explore card grids. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Open each with the intent (what a command/query is and why), show the canonical record + Handle() example, and add decision tables for the implementation styles and request/response vs observable — instead of a bare topics list. Surface the full-stack type-safety payoff at the end. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Replace the topics-table stub with a walk-through: the plumbing Arc removes, how proxy generation ties C# to React, a full-stack tabbed command example, an observable-query example, and hooks-vs-MVVM guidance. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Open with what the backend is for and a diagram of how a command/query record becomes an endpoint, proxy, and event/read-model — then group the topics into start-here, integrations, and cross-cutting instead of one flat table. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Give the React, Core, and MVVM index pages an intro that says what each layer is and when to reach for it, and group their links by purpose — instead of opening on a bare topics table. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Open with what the integration does (commands append events, projections build read models, read models inject back into Handle()) plus a diagram, group the links into essentials vs rules/compliance, and drop a copy-paste 'duplicate row' defect from the old table. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…rview" This reverts commit da79c0a.
Reshape the backend "your first command and query" and the React frontend getting-started into the project's guided-tour voice, matching the Chronicle get-started exemplar. Authored as .mdx with Steps and Asides. Both share one thread — the RegisterAuthor/AllAuthors author slice — so backend and frontend read as one continuous story. Adds a vertical-slice diagram on the backend page and a full-stack type-safety diagram (C# -> generated proxy -> React) on the frontend page, each with a section explaining what the framework does for you under the hood. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
A threaded five-chapter tutorial builds one library app end to end — a full-stack slice, validation and business rules, related slices via a children projection, real-time queries and reactors, and authorization — each chapter problem-driven and ending where the next begins. Alongside it, a task-oriented scenario catalog (validate, return results, react, query across slices, run from React, test) for quick how-to lookups. Mirrors the Marten/Wolverine content form: a threaded learn-by-building tutorial plus standalone recipes, filling Arc's two biggest content gaps. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add a guide for using Arc without event sourcing (commands and queries over MongoDB or EF Core with a live model-bound query), an Understanding-the-proxy-boundary explanation of full-stack type safety, and reframe why-arc plus the overview so Chronicle reads as one of three persistence options rather than a requirement. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Explain the three access questions — who the user is (IProvideIdentityDetails enrichment + authorize at ingress, one identity payload reused on the typed frontend), what they can do ([Authorize]/[Roles]/[AllowAnonymous] on model-bound commands and queries), and whose data they see (multi-tenant resolvers, context, and per-tenant isolation) — linking down to the detailed reference. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Lead the authorization reference with model-bound [Command] records and [ReadModel] query methods (matching the vertical-slice convention used everywhere else), add a note that this is the default, and frame the lower-level ICommandHandler examples as the option you rarely need. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Correct the startup: AddCratisArc on the builder (UseCratisArc does not exist on WebApplicationBuilder or IHostBuilder) and UseCratisArc on the built app. Verified against Arc source and Studio Program.cs. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Rewrite to real APIs: ArcApplication.CreateBuilder (not ArcApplicationBuilder.CreateBuilder); app.UseCratisArc() with no args (listen URL comes from ArcOptions.Hosting.ApplicationUrl); model-bound [Command]+Handle() and [ReadModel] static queries (the ICommand/ICommandHandler/IQuery/IQueryHandler marker interfaces do not exist); and AddCratisArc on the host builder with configSectionPath as a named arg. Verified against Arc source. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The note claimed the generic ICommandHandler/IQueryHandler classes were supported; they don't exist. Reframe to point at where the attributes go. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Replace the fabricated ICommandHandler<T>/IQueryHandler + context.User + CommandResult.Forbidden in the deeper sections (Working with Claims, Custom Authorization Logic, Policy-Based, Best Practices, Testing) with the verified model-bound pattern: inject IHttpContextAccessor and read HttpContext.User claims, return Result<ValidationResult,T> with ValidationResult.Error for in-handler guards, and test via CommandScenario<T> with ShouldNotBeAuthorized. Verified against Studio's SetupOrganization.Handle and CommandResultShouldExtensions. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The `()` in the unquoted `|.use() hook|` edge label broke Mermaid's parser, so the full-stack flow diagram failed to render. Quote the label. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Make the Arc tutorial Chronicle-free by default — Arc's real selling point is the typed full-stack loop over a plain database, not event sourcing. Rewrite the intro and the first slice to the direct-document model (command writes, read model is a document, live query via Observe), with MongoDB as the verified worked path and EF Core in synced tabs. Add a closing, optional "Add event sourcing" chapter that shows adopting Chronicle is a write-side-only change — queries, proxies, and the React are untouched — and hands off to the Chronicle tutorial and the Cratis Stack tour for the combination. First part of the migration: chapters 2–5 (validation, relationships, real-time, authorization) still teach the event-sourced model and get the same treatment next. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Finish the document-model rewrite. Validation: keep the ConceptValidator, move uniqueness to a CommandValidator with a MustAsync DB check (no event, no DCB). Relationships: a Book collection with a foreign key + a filtered live query (Observe(filter)) instead of a [ChildrenFrom] projection. Real-time: keep the observable-query payoff, drop the reactor (it moved to chapter 6, where events exist). Authorization: document-model command/query examples + a recap of the database app, forwarding to the optional ES chapter. MongoDB verified; EF Core in synced tabs (verified against the Arc EntityFrameworkCore source — DbSet.Observe, WithEntityFrameworkCore). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The tutorial's prerequisite (your-first-command) and the frontend pages still taught command→event→projection. Rewrite your-first-command to the document model (command writes, read model, live query) with a note that EF Core and Chronicle are options, and fix the event-sourcing prose/example leaks in the frontend overview and getting-started. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The documentation-authoring rules (tour voice, structure & formatting, the cross-repo edit->sync->verify workflow, rendering/QA, correct examples) and skills (edit/add/qa docs) live canonically in the Documentation repo's .ai/ and are shared to every repo. Copied here manually ahead of the propagation-on-merge so docs work has the guidance now. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
`StubIdentityProvider` does not exist in Arc source, and `IIdentityProvider` plays no part in command authorization (it has no `roles` constructor). Arc decides authorization from the current principal read off the HTTP context. Replace the example with the real pattern — register an IHttpContextAccessor carrying a ClaimsPrincipal whose roles you control — verified against the Studio CommandScenario specs. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Snippet-correctness audit against current Arc source. All fixes verified: - Bootstrap: ArcApplication.CreateBuilder (not ArcApplicationBuilder), app.UseCratisArc() no-arg, builder.AddCratisArc() (not UseCratisArc on a builder), invariant-culture set on the right host type. - Commands/queries: model-bound [Command]/Handle() (no ICommandHandler<T> or [Query] attr, no mediator.Send), MultipleUnhandledTupleValues (no Exception suffix), QueryResult.Unauthorized 1-arg, IInterceptReadModel returns the model, current user via IHttpContextAccessor (no IUserAccessor), IHttpRequestContext methods have no Async suffix, ClientPrincipal header names + claim.typ/val. - Observables: collection.Observe()/ObserveSingle() (no ObserveAsQueryable, no new ClientObservable<T>()/OnError/ClientDisconnected). - MongoDB/EF: WithDatabaseResolver, resolver Resolve(), UseCratisMongoDB, IEntityTypeConfiguration, conversions take DatabaseType. - Frontend imports: @cratis/arc.react(.mvvm) packages, useDialog. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The old frontend/react/storybook.md was a DocFX storybook-plugin stub that rendered empty on the new site. Replace it with a .mdx page that embeds the static Arc React storybook via <StorybookEmbed storybook="/storybook-arc" />, and point the toc entry at the .mdx. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…nfig
`storybook build` failed resolving `@cratis/arc/messaging` (imported by
ArcContext): the viteFinal alias map covered every @cratis/arc subpath except
messaging, so the base @cratis/arc alias mangled it into `.../Arc/index.ts/
messaging` ("Not a directory"). Add the messaging subpath alias alongside the
others. The static storybook now builds cleanly (manager + preview + 4 stories).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Standardize onboarding so each canonical getting-started opens with an explicit Prerequisites section before the steps (backend + frontend). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add eventmodeling diagrams to the tutorial intro and the add-event-sourcing chapter, framing each slice as a domain flow alongside the typed proxy boundary (the reactor block appears only once events are stored). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…racy Move cratis-package, react-to-an-event and add-event-sourcing into backend/chronicle with a new index/toc, and apply reference and wording corrections across backend, frontend, tutorial and scenario pages. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Verified against Arc/Source: QueryResult uses validationResults (plural); ValidationResult exposes members, not property; Paging is imported from @cratis/arc/queries; DialogButtons from @cratis/arc.react/dialogs; IdentityProviderContext has no Token; read-model load uses IReadModels.GetInstanceById; CommandContext property is Type (not CommandType) and its record signature includes AllowedSeverity. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Regex literals in proxy-generation/validation.md had a spurious 'index.md' suffix appended (e.g. /^\d+$/index.md), and react.mvvm/tsyringe.md had a stray backtick instead of a closing quote in the Bindings import. Both broke on paste. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Verified against current main (cratis/Arc): QueryResult is non-generic (assign its Data) — there is no QueryResult<T>; the generated OpenAPI sort parameter is 'sortby' (lowercase); Arc DbContext registration helpers take Action<IServiceProvider, DbContextOptionsBuilder> and AddReadModelDbContextsWithConnectionStringFromAssemblies takes the connection string first. Also removed stray 'index.md' suffixes the converter had appended inside three code snippets. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
NuGet packages for this PR, e.g. Cratis.Arc: |
|
NuGet packages for this PR, e.g. Cratis.Arc: |
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.
Merge the Arc docs-overhaul branch for the new Astro documentation site. Merge product documentation PRs before the Documentation site PR. Verification: Documentation/web npm run check built 710 pages with 0 errors and 0 broken internal links. Sensitive-info scan found no real secrets; only documentation placeholders/dev examples.