Skip to content

Comprehensive README expansion across all 52 modules + samples + key code comments#22

Merged
ancongui merged 7 commits intomainfrom
docs/comprehensive-readme-expansion
May 7, 2026
Merged

Comprehensive README expansion across all 52 modules + samples + key code comments#22
ancongui merged 7 commits intomainfrom
docs/comprehensive-readme-expansion

Conversation

@ancongui
Copy link
Copy Markdown
Contributor

@ancongui ancongui commented May 7, 2026

Summary

Brings the framework's submodule documentation to the same depth, structure, and quality as the most-loved OSS frameworks. Every README in src/ and samples/ now follows the established template:

Overview → Why a separate module → Mental model (with ASCII diagram) → Quick start → Public surface tables → Configuration → Common patterns → Pitfalls and gotchas → Internals → Dependencies → Java mapping

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 caching
  • PiiMaskingService: visible prefix/suffix rationale + clamp safety
  • FireflyException: defensive-copy rationale
  • GlobalExceptionHandlerMiddleware: translation order, HasStarted bail
  • DefaultCommandBus / DefaultQueryBus: dispatch ordering and cache-lookup placement
  • EventDrivenCacheInvalidator: no-op early exit + multi-pattern invalidation

Commit breakdown

  1. Foundational + most-used platform (Kernel, Utils, Validators, Web, Cqrs, Eda) + 14 agent-written READMEs preserved across IDP/Notifications/Callbacks/Starter
  2. EventSourcing, Orchestration, Cache, Observability, Data
  3. Plugins (2) + RuleEngine (5)
  4. Idp.AzureAd, Idp.InternalDb + ECM (6: ports + 2 storage + 3 e-signature)
  5. Notifications.Resend/Firebase + Webhooks (5) + Callbacks.Sdk
  6. Client (large) + Starter.Data + BackOffice + ConfigServer
  7. Samples (6) + code why-comments (7 framework files)

Test plan

  • dotnet build FireflyFramework.sln succeeds (0 warnings, 0 errors)
  • CI workflow ci.yml runs on every push to the branch
  • Manual review of a sample of READMEs to spot-check accuracy against current source
  • CI green before merge

Andres Contreras 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.
@ancongui ancongui changed the title Substantially expand the foundational + most-used platform READMEs Comprehensive README expansion across all 52 modules + samples + key code comments May 7, 2026
@ancongui ancongui merged commit 20bae87 into main May 7, 2026
2 checks passed
@ancongui ancongui deleted the docs/comprehensive-readme-expansion branch May 7, 2026 19:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant