Add CLAUDE.md with project guidance (#1)#555
Open
guillaumebadin wants to merge 76 commits intohnaderi:mainfrom
Open
Add CLAUDE.md with project guidance (#1)#555guillaumebadin wants to merge 76 commits intohnaderi:mainfrom
guillaumebadin wants to merge 76 commits intohnaderi:mainfrom
Conversation
* Add CLAUDE.md with project guidance Provides development setup, build commands, project structure, and module documentation for working with the Edomata codebase. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com> * Enrich tutorials for non-expert developers Add beginner-friendly explanations throughout all 5 tutorials: - 0_getting_started: Problem statement, architecture diagram, aggregate and pure function explanations, Edomaton vs Stomaton decision guide - 1-1_eventsourcing: Event sourcing intro, Decision analogy, Scala syntax notes, ValidatedNec and fold explanations, testing benefits - 1-2_cqrs: CQRS intro, state diagrams, EitherNec vs Decision comparison, Stomaton vs Edomaton decision matrix - 2_backends: Backend concept, program/interpreter pattern, persistence tables explained, outbox and idempotency, minimal setup example - 3_processes: Process intro, outbox pattern diagram, stream explanation, process manager and saga patterns with examples Each technical term now includes real-world analogies and practical context for developers unfamiliar with Scala, event sourcing, DDD, or CQRS concepts. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Convert ASCII diagrams to Mermaid in tutorials Replace ASCII art diagrams with Mermaid for better rendering: - 0_getting_started: Layer architecture flowchart - 1-2_cqrs: Traditional vs CQRS comparison, order state diagram - 2_backends: Pure/backend architecture, database ER diagram - 3_processes: System architecture, outbox sequence diagram, saga flow Mermaid diagrams render properly in GitHub, documentation sites, and most modern markdown viewers. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> --------- Co-authored-by: GitHub Actions Bot <actions@github.com> Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Adds fork-aware ticket workflow instructions so Claude Code automatically detects fork vs root repo and targets PRs accordingly. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
docs: add contribution workflow to CLAUDE.md
Adds context7.json so Edomata can be indexed on Context7, enabling AI coding assistants (Claude Code, Cursor, Copilot) to look up Edomata documentation directly. Fixes hnaderi#573 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add PGNaming sealed trait with Schema and Prefixed variants, allowing
tables to use a name prefix (e.g. auth_journal) instead of a dedicated
PostgreSQL schema (e.g. "auth".journal). This is useful for projects
using Flyway migrations in a single schema.
API: PGNamespace.prefixed("auth") or PGNaming.prefixed("auth")
Fixes hnaderi#574
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add SkunkPrefixedPersistenceSuite and SkunkPrefixedCQRSSuite - Add DoobiePrefixedPersistenceSuite and DoobiePrefixedCQRSSuite - Document table prefix mode in skunk.md, doobie.md, and backends tutorial Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add PGSchema utility to generate DDL SQL strings for migration files (eventsourcing and cqrs variants with configurable payload types) - Add skipSetup parameter to all driver .from() methods to disable automatic schema/table creation at startup - Add 10 unit tests for PGSchema DDL generation - Document Flyway workflow in skunk.md and doobie.md Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add comprehensive AI agent documentation covering: - Table naming strategies (Schema vs Prefixed) - DDL extraction with PGSchema for Flyway workflows - skipSetup parameter for disabling automatic DDL - Guide for adding new tables with proper naming flow Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- CLAUDE.md: SBT 1.12.1 -> 1.12.8, Doobie RC11 -> RC12, docker credentials test/test -> postgres/postgres - tutorials/2_backends.md: replace non-existent SkunkBackend API with actual Backend.builder().use(SkunkDriver(...)) pattern, fix connection credentials Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add a pre-PR documentation audit process to CLAUDE.md that AI agents must run before opening any PR. Includes a detailed audit prompt that checks CLAUDE.md, backend docs, tutorials, and features against actual source code (versions, API signatures, file paths, code examples). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
examples/ is a root-level directory, not under modules/. Found by documentation audit agent. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add language requirement: all commits, PRs, comments, docs, and branch names must be in English for this international open-source library. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
docs: add Context7 documentation indexing
docs: add expert-flow.ai to adopters
feat: table prefix mode, DDL extraction, and Flyway support
…ards Introduces edomata-saas, a cross-platform module providing generic multi-tenant CRUD abstractions. Services extending the SaaS base traits get automatic tenant isolation and role-based authorization before any business logic runs, for both event-sourcing and CQRS approaches. Key features: - SaaSDomainDSL / SaaSCQRSDomainDSL with guardedRouter (auto-guarded) and unsafeUnguardedRouter (explicit bypass for super-admin) - CrudState[A] enum with tenant+owner tracking - TenantScopedQuery / UnsafeCrossTenantQuery for read-side enforcement - Selective re-exports in package.scala to prevent raw DSL usage - 15 unit tests for guard logic - Documentation page (docs/tutorials/4_saas.md) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Full Todo CQRS example showing: domain types, SaaS service with guardedRouter, SkunkHandler for SQL read-model projection, TenantScopedQuery for tenant-scoped reads, admin bypass with unsafeUnguardedRouter, and backend wiring - Integration tests exercising guardedRouter through the Stomaton pipeline: tenant mismatch rejection, missing roles rejection, Create bypass, unsafe bypass, and notification emission - 9 new tests (24 total for the saas module) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
New test suites: - SaaSDomainDSLSuite: 24 tests covering the event-sourcing guarded DSL (guardedRouter, unsafeUnguardedRouter, guarded, unsafeUnguarded, caller/command/entityState/aggregateId accessors, pure, unit, reject, decide, publish, validate, notifications, Deleted state handling) - TenantAwareReaderSuite: 8 tests covering read-side abstractions (TenantScopedQuery factory and tenant filtering, UnsafeCrossTenantQuery, TenantAwareReader trait implementation) - SaaSServiceSuite: 20 tests covering service traits, CQRS DSL methods, event-sourced service, CrudState patterns, types, and package re-exports (domain field, set, modifyS, decideS, eval, DomainModel transitions, TenantId/UserId round-trips, SaaSCommand covariance, CrudAction enum, CommandMessage/Decision/MessageMetadata re-exports) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace hardcoded CallerIdentity with generic Auth type parameter throughout the SaaS module. Authorization logic is now defined by implementing the AuthPolicy[Auth] trait, which provides: - tenantId(auth): extract tenant from any auth context - authorize(auth, action): custom authorization check CallerIdentity remains as a default implementation, with RoleBasedPolicy for role-based access control. Changes: - Add AuthPolicy[Auth] trait and RoleBasedPolicy class - SaaSCommand[C] -> SaaSCommand[Auth, C] - DSLs, services, readers all parameterized by Auth - SaaSGuard.checkRoles -> SaaSGuard.checkAuthorization (delegates to policy) - caller accessor -> auth accessor - rolesFor param removed from DSL/Service constructors (moved to AuthPolicy) - Tests updated + custom AuthPolicy test (ApiKeyAuth example) - 77 tests pass Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Rewrite documentation to reflect the generic auth refactor: - Add AuthPolicy typeclass section with full API - Add Custom Auth Types section with JwtClaims, ApiKeyAuth examples - Update all code samples: SaaSCommand[Auth, C], auth accessor, RoleBasedPolicy, TenantScopedQuery with Auth type param - Rename "Role check" to "Authorization check" throughout - Update overview to emphasize pluggable authorization Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
feat: add multi-tenant SaaS CRUD module
…ions Add a complete Product Catalog example demonstrating: - Custom AuthPolicy (ApiKeyContext with scopes, not CallerIdentity) - Typed rejections (ProductRejection enum, not String) - Product lifecycle state machine (Draft → Published → Archived → Deleted) - SQL DDL for CQRS backend tables and custom read-model projection - Flyway migration workflow with skipSetup Include 27 pure domain unit tests covering CRUD lifecycle, state machine validation, scope-based authorization, multi-tenant isolation, admin bypass, notification emission, and price validation. Update SaaS tutorial with full Product Catalog section including generated SQL examples, custom auth patterns, and test snippets. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add tenant-aware database tables to the SaaS module, enabling Row-Level Security, tenant-scoped indexes, and SQL-level audit queries. Changes: - Add TenantExtractor typeclass to extract tenant/owner from CrudState - Add SaaSPGSchema for DDL generation with tenant_id, owner_id columns, tenant indexes, and optional RLS policies - Create saas-skunk module with SaaSSkunkCQRSDriver that persists tenant_id/owner_id as first-class columns in states and outbox tables - Update ProductCatalogExample to use SaaS-aware driver - Add 13 new tests (TenantExtractor + SaaSPGSchema DDL validation) Test coverage: 93.7% statements, 100% branches on saas module. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
feat: add SaaS multi-tenant CQRS example + tenant-aware backend
Add Flyway-like event migration support that automatically tracks and applies pending migrations on startup. Migrations transform journal payloads in-place with compile-time exhaustivity checking via Scala 3 sealed enum pattern matching. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
feat: add automatic event journal migration system
mimaPreviousArtifacts is overridden by sbt-typelevel. Use the typelevel-specific tlMimaPreviousVersions := Set.empty instead. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
docs: add GitHub Packages installation instructions
The e2e test module still referenced the old dev.hnaderi package namespace after the organization migration to dev.bsg. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
fix: rename e2e package from dev.hnaderi to dev.bsg
Update base URL and navigation links from edomata.ir to beyond-scale-group.github.io/edomata/ for GitHub Pages deployment. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
docs: publish site on GitHub Pages
Replace the Typelevel sbt-typelevel-site (Laika/Helium) with Docusaurus 3 for a modern documentation experience with dark mode, better search, and a distinctive visual identity. - Remove EdomataSitePlugin.scala and sbt-typelevel-site dependency - Configure mdoc to output to website/docs/ for Docusaurus consumption - Add Docusaurus project with custom purple theme, landing page with hero section, feature cards, and ecosystem links - Migrate all 16 doc files with Docusaurus frontmatter and fixed links - Update CI workflow: sbt docs/mdoc → npm run build → GitHub Pages The mdoc compilation step still validates all Scala code examples, ensuring documentation accuracy at build time. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
mdoc copies source files to website/docs/, so the source filenames must already match Docusaurus conventions. This fixes the duplicate doc ID error in CI. - Rename tutorial files (remove numeric prefixes, use hyphens) - Add Docusaurus frontmatter to source docs - Convert @:api() syntax and fix internal links in source - Remove Laika directory.conf files (use sidebar_position instead) - Add website/docs/ to .gitignore (generated by mdoc) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
feat: migrate docs site to Docusaurus
…#28) Show copy-paste SBT snippets with latest version (0.12.5) for JVM, Scala.js, and Scala Native. Fix stale documentation links in README. Co-authored-by: GitHub Actions Bot <actions@github.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The publish-ghp workflow failed on all 3 attempts due to two root causes: 1. publishTo was set at ThisBuild scope, but sbt-typelevel's TypelevelSonatypePlugin overrides it at project scope. Artifacts were sent to central.sonatype.com instead of maven.pkg.github.com. Fix: move publishTo into ghpPublishSettings applied at project scope via the module() function. 2. publish-ghp.sbt contained a duplicate publishTo/credentials block (also at ThisBuild scope) that was equally ineffective. Fix: remove duplicates, keep only gpgWarnOnFailure. Additional fixes: - Update cachix/install-nix-action v17 → v31 (Node.js 20 deprecated) - Fix README: GitHub Packages requires auth even for public repos Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
fix: resolve GitHub Packages publish pipeline failures
Co-authored-by: Scala Steward <scala-steward@beyond-scale-group.com>
* Update sbt-scalafmt to 2.5.6 * fix: add scala-xml dependency scheme to resolve plugin eviction conflict Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Scala Steward <scala-steward@beyond-scale-group.com> Co-authored-by: GitHub Actions Bot <actions@github.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The default GITHUB_TOKEN cannot trigger downstream workflows (GitHub prevents cascading to avoid infinite loops). Use SCALA_STEWARD_TOKEN PAT so the tag push triggers the publish-ghp workflow. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
fix: use PAT in auto-tag to trigger publish workflow
sbt-gpg sets gpgWarnOnFailure := false at project scope, beating our ThisBuild override. Same pattern as the publishTo fix — must override at project scope via ghpPublishSettings. Without this, publish fails with: "GPG reported an error. Artifacts won't be signed." on all modules. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
fix: disable GPG signing at project scope for GitHub Packages
* Update sbt-typelevel, ... to 0.8.5 * fix: add scala-xml dependency scheme to resolve plugin eviction conflict Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Scala Steward <scala-steward@beyond-scale-group.com> Co-authored-by: GitHub Actions Bot <actions@github.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
These non-library projects were aggregated into rootJVM and attempted to publish, failing on GPG signing since they don't receive ghpPublishSettings (they're not cross-projects using module()). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
fix: skip publishing for docs and unidocs projects
* Update scala3-compiler, scala3-library, ... to 3.3.7 * Regenerate GitHub Actions workflow Executed command: sbt githubWorkflowGenerate * Revert "Regenerate GitHub Actions workflow" This reverts commit 0222418. * fix: remove unused imports and symbols for Scala 3.3.7 compatibility Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: resolve remaining unused symbol errors for Scala 3.3.7 - Suppress unused implicit `StateModelTC[S]` warning in CommandHandler.run - Suppress unused implicit `Location` warning in DomainSuite extension - Replace unused parameter `i` with `_` in StomatonConstructorSuite Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * style: fix scalafmt formatting in DomainSuite Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: resolve all remaining unused symbol errors for Scala 3.3.7 - Fix DomainSuite.scala: remove space in @nowarn annotation to fix syntax error - Add @nowarn("msg=unused") to SaaSCQRSDomainDSL.unsafeUnguarded - Add @nowarn("msg=unused") to SaaSDomainDSL.unsafeUnguarded - Add @nowarn("msg=unused") to SaaSEventSourcedService and SaaSCQRSService classes - Add @nowarn("msg=unused") to TenantScopedQuery.apply and UnsafeCrossTenantQuery.apply - Replace unused parameter `n` with `_` in SkunkRepository.scala Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: prevent scalafmt from breaking nowarn annotation in DomainSuite Scalafmt 3.10.7 adds a space before the parenthesis in @scala.annotation.nowarn("msg=unused"), which Scala 3.3.7 treats as a syntax error. Wrapping with format:off/on keeps the annotation intact. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: suppress Scala 3.3.7 unused warnings via -Wconf instead of per-site annotations Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Scala Steward <scala-steward@beyond-scale-group.com> Co-authored-by: GitHub Actions Bot <actions@github.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The Typelevel and Scala Steward badges used markdown image syntax inside an HTML block, causing them to render as raw text on GitHub. Co-authored-by: GitHub Actions Bot <actions@github.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Update sbt-scalajs, scalajs-library_2.13, ... to 1.21.0 (hnaderi#582) * Update sbt, scripted-plugin to 1.12.9 (hnaderi#586) * docs: add Java-friendly API implementation plan Proposes a new `edomata-java-api` JVM-only module that bridges Edomata's Scala 3 types to Java-idiomatic classes using CompletableFuture, Java collections, and builder patterns. Covers all 16 modules across 3 phases. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * feat: add Java-friendly API module (edomata-java-api) Implements Phase 1 of the Java API plan: a JVM-only bridge module that wraps Edomata's Scala 3 types into Java-idiomatic classes. - Core types: JDecision, JEither, JDomainModel, JCommandHandler, JAppResult - Backend: JBackend + JBackendBuilder wrapping Doobie event sourcing - Codecs: JCodec bridging to BackendCodec.JsonB - DDL: JPGSchema for Flyway/Liquibase migration generation - Runtime: EdomataRuntime (AutoCloseable IORuntime wrapper) - Readers: JJournalReader, JOutboxReader (FS2 streams to CompletableFuture) - Tests: 49 Scala unit tests + 17-assertion Java integration test - Docs: comprehensive usage guide at docs/backends/java-api.md - Fix: useReadableConsoleGit for git worktree compatibility All 56 tests pass. No new dependencies required. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: add public read token for GitHub Packages - Update README with Maven/Gradle/SBT install instructions including read-only token placeholder for GitHub Packages authentication - Update java-api.md with complete Maven/Gradle/SBT setup - Inject PACKAGES_READ_TOKEN via mdocVariables in build.sbt - Pass token from GitHub repo variable in CI site build - Add java-api module to README modules table and docs index Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: add public read-only token for GitHub Packages Token has read:packages scope only — safe to publish. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Hossein Naderi <hossein-naderi@hotmail.com> Co-authored-by: Scala Steward <43047562+scala-steward@users.noreply.github.com> Co-authored-by: GitHub Actions Bot <actions@github.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* "Claude PR Assistant workflow" * "Claude Code Review workflow"
* "Update Claude PR Assistant workflow" * "Update Claude Code Review workflow"
* feat: migrate publishing from GitHub Packages to Maven Central Switch artifact group ID from dev.bsg to io.github.beyond-scale-group and publish to Maven Central (Sonatype) instead of GitHub Packages. This removes the need for consumers to configure resolvers, credentials, or authentication tokens. - Change organization to io.github.beyond-scale-group - Enable sbt-typelevel Sonatype publishing (tlCiReleaseBranches, tlSonatypeUseLegacyHost) - Remove GitHub Packages publish config (publish-ghp.sbt, ghpPublishSettings) - Replace publish workflow with Maven Central via tlRelease - Update all docs, README, and website with new group ID - Remove dead read-only PAT token from README Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: use sonatypeCredentialHost instead of tlSonatypeUseLegacyHost tlSonatypeUseLegacyHost does not exist in sbt-typelevel 0.8.x. Use sonatypeCredentialHost := "s01.oss.sonatype.org" instead. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: remove sonatypeCredentialHost (not available in sbt-typelevel 0.8.x) sbt-typelevel 0.8.x dropped sbt-sonatype in favor of sbt 1.11 builtins. Sonatype Central is the default target, no host override needed. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: scalafmt formatting for java-api module Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: skip --release javac flag on JDK 8 The --release flag was introduced in JDK 9. On JDK 8, javac fails with 'invalid flag: --release'. Skip the flag when running on JDK 8 since the java-api module targets JDK 11+ anyway. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: GitHub Actions Bot <actions@github.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: GitHub Actions Bot <actions@github.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Parallel matrix jobs caused Sonatype deployment collisions — cross-compiled modules were uploaded by multiple deployments simultaneously. Tests still run in parallel, but publish runs as a single job. Co-authored-by: GitHub Actions Bot <actions@github.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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
2 participants
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.
Provides development setup, build commands, project structure, and module documentation for working with the Edomata codebase.
Add beginner-friendly explanations throughout all 5 tutorials:
Each technical term now includes real-world analogies and practical context for developers unfamiliar with Scala, event sourcing, DDD, or CQRS concepts.
Replace ASCII art diagrams with Mermaid for better rendering:
Mermaid diagrams render properly in GitHub, documentation sites, and most modern markdown viewers.