Conversation
added 7 commits
May 7, 2026 20:43
First pass of a deep, didactic README expansion across the framework. This PR rewrites the six READMEs that drive the most consumer adoption and ships them as the template for the rest of the codebase to follow: | Project | Before | After | Δ | |---|---|---|---| | FireflyFramework.Kernel | 65 | 333 | +268 | | FireflyFramework.Utils | 112 | 380 | +268 | | FireflyFramework.Validators | 113 | 349 | +236 | | FireflyFramework.Web | 159 | 505 | +346 | | FireflyFramework.Cqrs | 162 | 488 | +326 | | FireflyFramework.Eda | 191 | 483 | +292 | Total: 802 → 2538 lines (+1736 new lines of documentation). Every README now follows a consistent template: * **Overview** — what the module is, what problem it solves, where it sits in the framework architecture, why it exists as its own module rather than being merged into another. * **Why a separate <module> project?** — the design rationale callers usually want before adopting. * **Mental model** — ASCII diagrams of the abstractions and how the pieces fit together. * **Quick start** — short runnable snippet showing the canonical wire-up and call site. * **Public surface** — exhaustive type-by-type reference grouped by category, with example code where the surface is non-obvious. * **Configuration** — every Firefly:* option with its default and effect, in a table, plus a worked appsettings.json example. * **Common patterns** — 3-5 worked recipes for the most common scenarios. * **Pitfalls and gotchas** — surprising behaviour, common mistakes, documented upstream limitations. Includes "bad → good" snippet pairs where they help. * **Internals (for the curious)** — how the module works under the hood; design rationale for the non-obvious choices. * **Dependencies** — project + package references with a one-liner per dep on why it's there. * **Java mapping** — table mapping .NET types to their Java originals so migrators can navigate quickly. Every claim is grounded in the actual source — every type name, method signature, configuration key, and code snippet was verified against the corresponding .cs files. No fabricated APIs. Build remains clean (0 errors / 0 warnings); 346 / 346 tests still passing. No source code changed in this PR. Follow-up commits will roll the same template across the remaining 46 src/* projects.
Each grew to a full didactic guide (~400-700 lines) following the established template: overview, why a separate module, mental model ASCII, quick start, public surface table, configuration, common patterns, pitfalls, internals, dependencies, Java mapping. Notable additions: - Orchestration: full saga DAG/workflow signal/TCC two-phase execution traces, compensation policy presets, recovery+cleanup composition with the scheduler, REST control plane routes. - Cache: primary/fallback failover model, prefix-eviction guarantees, SETNX-style PutIfAbsent lock pattern. - Observability: end-to-end OTLP-collector diagram, low-cardinality tag set table, MdcConstants log-context contract, sampling and Kubernetes probe gotchas. - Data: filter DSL semantics matrix (string LIKE, IEnumerable IN, null sentinels), [FilterableId] opt-in rationale, EF Core 10 ExecuteDeleteAsync caveat.
Plugins.Api / Plugins.Core: full lifecycle SPI explanation, state machine, [Plugin] attribute discovery, McMaster-based assembly isolation, hot-reload patterns, parameterless ctor pitfall. RuleEngine.Interfaces / Models / Core / Web / Sdk: complete five-tier walkthrough — DSL operator matrices, AST node hierarchy, visitor pattern with worked example, REST endpoint table, typed HttpClient resilience composition, batch evaluation pattern.
Idp.AzureAd / Idp.InternalDb: full operation coverage tables, NotSupportedException rationale (no RFC 7662 endpoint, no session listing API), pluggable storage SPI (user repo / revocation store / role catalog), JWT signing-key rotation strategy, BCrypt workFactor guidance. Ecm (port tier): hexagonal mental-model diagram, [EcmAdapter] attribute walk-through, AdapterRegistry/Selector resolution algorithm, multi-tenant prefix patterns. Ecm.Storage.Aws / Azure: cloud-specific auth chains (IAM role vs DefaultAzureCredential), MinIO + Azurite local-dev paths, byte-range streaming through ASP.NET, soft-delete & snapshot guidance. Ecm.ESignature.DocuSign / AdobeSign / Logalty: provider auth flows (JWT-grant RSA, OAuth2 refresh, OAuth2 client_credentials), envelope lifecycle quirks (Logalty immutability, DocuSign demo-vs-prod URL trap, AdobeSign region pod selection).
Notifications.Resend / Firebase: provider-specific auth (bearer token vs ADC), domain-verification gotchas, FCM token-not-registered handling, multi-platform routing (FCM-as-APNs proxy). Webhooks five-tier walkthrough: - Interfaces: WebhookEventDto / WebhookResponseDto contract, status-value semantics matrix. - Core: full pipeline diagram (validate → rate-limit → enrich → dispatch → DLQ), token-bucket rate-limiter, dead-letter redrive. - Processor: signature validators (Stripe / GitHub / Twilio / generic HMAC), constant-time comparison, idempotency window guidance. - Web: ingestion controller routes, response-code mapping (REJECTED is 200, RATE_LIMITED is 429), forwarded-headers gotcha. - Sdk: edge-to-pipeline forwarding, header-forwarding handler pattern. Callbacks.Sdk: full-replace update semantics, secret rotation roundtrip, FailureCount read-only-over-wire detail.
Client (large module): full mental-model diagram of the per-request pipeline (dedup → discovery → load-balance → resilience → auth), auth scheme matrix, resilience options table, four service discovery clients, four load-balancer strategies, OAuth2 token cache, deduplication, chaos handler, GraphQL helper. Starter.Data: ETL/batch fit, Polly v8 ResiliencePipelineBuilder patterns, EF Core 10 ExecuteUpdate caveat, cursor-pagination loop for high-volume tables. BackOffice: header-driven impersonation context, full BackofficeContext helper matrix, custom resolver pattern with security-centre lookup, audit filter pattern, fail-closed rationale. ConfigServer: Spring-Cloud-Config-native protocol, lookup-precedence algorithm (4 levels x 4 extensions), Kubernetes ConfigMap mounting, Steeltoe + Spring Cloud Config consumer wiring.
samples (6 files): hexagonal layout walk-through, full contract/persistence/business/host tier explanations, idempotency + query-cache demo flow, project-graph diagram, production-checklist for swapping in EF Core / OAuth / brokers. Code comments (7 files) — added at non-obvious decision points where the WHY behind a choice would not be derivable from the code: - IdempotencyMiddleware: why cache key includes path, why we swap Response.Body for a MemoryStream, why only 2xx is cached. - PiiMaskingService: why we keep prefix/suffix visible (human troubleshooting) and clamp to input length. - FireflyException: why the context dictionary is defensively copied (caller mutation leakage rationale). - GlobalExceptionHandlerMiddleware: translation order rationale, HasStarted log-and-bail explanation. - DefaultCommandBus: validation-then-auth ordering rationale, why reflection-based dispatch is the right call. - DefaultQueryBus: why the cache lookup runs before dispatch, why the default(TResult) check guards null-cache hits. - EventDrivenCacheInvalidator: why the no-op early exit matters, why one event can invalidate multiple patterns.
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
Brings the framework's submodule documentation to the same depth, structure, and quality as the most-loved OSS frameworks. Every README in
src/andsamples/now follows the established template:Scope
52 src/ READMEs* — every module across foundational / platform / adapter / starter tiers — expanded from short reference cards to didactic guides averaging 300-700 lines.
6 samples/ READMEs — five-project hexagonal layout walk-through, idempotency + query-cache demo flow, production checklist for swapping in EF Core / OAuth / real brokers.
Code why-comments — selective additions at non-obvious decision points in the most-used framework files (Kernel/Web/Cqrs):
IdempotencyMiddleware: cache-key path inclusion, body-swap rationale, 2xx-only cachingPiiMaskingService: visible prefix/suffix rationale + clamp safetyFireflyException: defensive-copy rationaleGlobalExceptionHandlerMiddleware: translation order, HasStarted bailDefaultCommandBus/DefaultQueryBus: dispatch ordering and cache-lookup placementEventDrivenCacheInvalidator: no-op early exit + multi-pattern invalidationCommit breakdown
Test plan
dotnet build FireflyFramework.slnsucceeds (0 warnings, 0 errors)ci.ymlruns on every push to the branch