docs: align architecture diagrams with current ADRs

[phuongnse]

Summary

This PR improves architecture diagrams and documentation workflow guardrails, adds a root README entrypoint, hardens ignore rules, and removes redundant doc indirection.

Included changes

• System-level diagram refinements (system-context, container, module-overview) for semantics, readability, and non-overlapping connector routing.
• Shared visual review process:
  • Added docs/playbooks/visual-artifact-checklist.md.
  • Wired it into CLAUDE.md, docs/README.md, and docs/playbooks/wireframes.md.
  • Removed redundant per-folder checklist/readme indirection in docs/diagrams/.
• Added root README.md as project landing page (overview + quick links + local quick start).
• Ignore rules hardening:
  • .gitignore: ignore .env.* with !.env.example keep rule.
  • .claudeignore: aligned env ignore patterns.
  • .dockerignore: clarified intent for excluded paths.
• Cleanup:
  • deleted docs/diagrams/README.md as redundant with global docs navigation + shared visual checklist.

Linked spec

• docs/ARCHITECTURE.md
• docs/TECH_STACK.md
• docs/PROGRESS.md
• CLAUDE.md
• docs/playbooks/local-dev.md
• docs/PRODUCT_VISION.md

Requirements & rules followed

• Spec → code — changes match use-case file ACs (or gaps documented in > **Implementation status** callouts; deferred items have **Deferred (PR #N follow-up):** lines)
• Gate 0 — AC map complete; use-case/domain docs identified (when shipping code)
• Gate 1 — dotnet build + dotnet test (full Axis.sln) + dotnet format --verify-no-changes and/or npm run ci + npm run test ran green for paths touched (N/A: docs/visual/ignore-only changes)
• Gate 2 — docs updated in same PR (use-case callout, domain README, PROGRESS.md, TECH_STACK / patterns as triggered); ./scripts/check-doc-drift.sh ran green locally (N/A: no src/, tests/, or docs/use-cases/ AC content changes)
• Gate 3 — retrospective done; patterns.md / use-case file / TECH_STACK.md / CLAUDE.md updated if a new durable rule emerged
• Workarounds — this PR neither introduces nor resolves a P0/P1 violation OR docs/WORKAROUNDS.md was updated in the same commit and the violation site has a // WORKAROUND: see docs/WORKAROUNDS.md#<slug> comment
• No new TODO / FIXME / NotImplementedException / placeholder / stub under src/, tests/, frontend/src/

  

Summary by CodeRabbit

• Documentation

  • Updated architecture diagrams to reflect revised messaging infrastructure (Kafka, RabbitMQ, gRPC).
  • Added platform overview README with quick-start development instructions.
  • Added visual artifact checklist for diagram review and validation.

• Chores

  • Updated environment file handling and build configurations.
  • Reorganized diagram generation workflow and directory structure.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1d32f78b-70fb-445a-b0b8-9269e6639e5f

📥 Commits

Reviewing files that changed from the base of the PR and between f01fa00 and 02e0f9d.

⛔ Files ignored due to path filters (2)

• docs/diagrams/module-overview.svg is excluded by !**/*.svg
• docs/diagrams/system-context.svg is excluded by !**/*.svg

📒 Files selected for processing (12)

• .claudeignore
• .dockerignore
• .gitignore
• CLAUDE.md
• README.md
• docs/README.md
• docs/diagrams/generate-diagrams.mjs
• docs/diagrams/module-overview.excalidraw
• docs/diagrams/system-context.excalidraw
• docs/playbooks/visual-artifact-checklist.md
• docs/playbooks/wireframes.md
• docs/scripts/generate-diagrams.ps1

✅ Files skipped from review due to trivial changes (10)

• .claudeignore
• .dockerignore
• docs/scripts/generate-diagrams.ps1
• .gitignore
• docs/README.md
• docs/playbooks/wireframes.md
• docs/playbooks/visual-artifact-checklist.md
• README.md
• CLAUDE.md
• docs/diagrams/module-overview.excalidraw

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/diagrams/generate-diagrams.mjs

---

📝 Walkthrough

Walkthrough

Updated architecture documentation and governance requiring visual-artifact checklist validation before commit. Regenerated three Excalidraw diagrams (system context, container, module overview) to depict messaging infrastructure shift from Wolverine to Kafka + Schema Registry (events), RabbitMQ (commands/jobs), and gRPC (sync RPC), with strict modulith boundaries and per-module databases. Enhanced development workflow with environment file handling, project-level README with quick-start, and new playbook checklist.

Changes

Architecture Diagrams and Governance

Layer / File(s)	Summary
Configuration: environment files and Docker context .claudeignore, .dockerignore, .gitignore	Environment variables are consistently ignored (.env.* pattern) while explicitly allowing .env.example for source control; Docker build context is optimized to exclude large directories pending future build-stage evaluation.
Documentation governance: visual-artifact requirements and README CLAUDE.md, README.md, docs/README.md, docs/playbooks/visual-artifact-checklist.md, docs/playbooks/wireframes.md	New visual-artifact governance in CLAUDE.md requires checklist validation and SVG regeneration when diagrams/wireframes change. New playbook visual-artifact-checklist.md provides semantic/geometry/layout checks and SVG update flow. Project-level README.md introduces Axis platform, quick links, and Docker Compose quick-start. Wireframes playbook and docs index updated to reference new checklist.
Diagram generation script: infrastructure and output routing docs/diagrams/generate-diagrams.mjs, docs/scripts/generate-diagrams.ps1	Script header updated to document Kafka/RabbitMQ/gRPC messaging model replacing Wolverine. architectureDir and useCaseDir(domain, useCase) helpers added to route use-case diagrams to per-domain/per-use-case subdirectories. PowerShell script updated to scan docs/diagrams/ instead of docs/architecture/diagrams/.
System context diagram: platform-level actors and infrastructure docs/diagrams/generate-diagrams.mjs, docs/diagrams/system-context.excalidraw	System Context diagram generation refactored to show Axis platform with ASP.NET Core 8 Modulith (strict boundaries), Kafka + Schema Registry (Events/Snapshots, Avro+CloudEvents), RabbitMQ (Commands/Jobs/Saga), and gRPC Contracts (Sync RPC). Updated actor labels, web-application SPA block, API Server/Module Services representation, external integrations (APIs, Workflow HTTP steps, Webhooks), and connector arrows. Numerous element IDs/seeds/coordinates regenerated across all diagram regions.
Container diagram: modules, brokers, and runtime infrastructure docs/diagrams/generate-diagrams.mjs, docs/diagrams/container.excalidraw	Container diagram generation refactored to data-driven module rendering with per-module PostgreSQL databases (Identity, DataModeling, WorkflowBuilder, WorkflowEngine, FormBuilder), messaging lanes (Kafka, RabbitMQ, gRPC), authentication band (OpenIddict+SignalR), operations infrastructure (Redis, Vault, Grafana), and external services (S3, Email). Updated Excalidraw JSON with element ID/seed updates, geometry adjustments for header, modules, infrastructure columns, and legend.
Module overview diagram: cross-module communication patterns docs/diagrams/generate-diagrams.mjs, docs/diagrams/module-overview.excalidraw	Module Overview diagram generation refactored to depict explicit cross-module communication channels: Kafka (events/snapshots), RabbitMQ (commands/jobs/saga), gRPC (sync RPC escape hatch). Updated Shared Kernel labels, replaced Wolverine lane with Kafka/RabbitMQ/gRPC boxes, refreshed example event/command badges, modified legend, and applied extensive Excalidraw element updates and geometry adjustments throughout layout.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• phuongnse/axis#59: Standardizes architecture patterns and documents the modulith strict service-boundary model (Kafka+Schema Registry/Avro+CloudEvents and gRPC contracts) that this PR's diagram regeneration reflects.
• phuongnse/axis#30: Restructures CLAUDE.md into modular playbooks; this PR extends governance by adding visual-artifact-specific regeneration and checklist requirements.
• phuongnse/axis#43: Modifies the diagram generator and regenerates the same architecture Excalidraw diagrams; this PR's updates represent the continuation or parallel refinement of diagram rendering and output routing.

Poem

🐰 Behold, the diagrams now flow with grace,
Kafka hops where Wolverine had its place,
From Modulith towers to gRPC contracts tight,
RabbitMQ commands and events in the light,
A checklist to keep all our pictures just right!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 60.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: align architecture diagrams with current ADRs' directly and accurately reflects the main objective of the PR, which is to update and refine system architecture diagrams to align with current architectural decision records.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/update-diagrams-architecture-963b

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/diagrams/system-context.excalidraw (1)

1-1955: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Regenerate and commit matching .svg outputs for updated Excalidraw sources.

This PR updates .excalidraw sources but does not include regenerated .svg artifacts in the reviewed changes. Please regenerate and commit the corresponding SVG diagrams in the same PR.

As per coding guidelines docs/**/*.excalidraw: Regenerate .svg diagrams in same PR when .excalidraw source files change.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/diagrams/system-context.excalidraw` around lines 1 - 1955, The PR
updated the Excalidraw source docs/diagrams/system-context.excalidraw but did
not include the regenerated SVG artifacts; regenerate the corresponding .svg
exports for that Excalidraw file (and any other docs/**/*.excalidraw changed in
this PR) using Excalidraw (or your export script/CI tool), add the resulting
.svg files to the commit, and push/update the PR so the .excalidraw sources and
their matching .svg outputs are included together.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@docs/diagrams/system-context.excalidraw`:
- Around line 1-1955: The PR updated the Excalidraw source
docs/diagrams/system-context.excalidraw but did not include the regenerated SVG
artifacts; regenerate the corresponding .svg exports for that Excalidraw file
(and any other docs/**/*.excalidraw changed in this PR) using Excalidraw (or
your export script/CI tool), add the resulting .svg files to the commit, and
push/update the PR so the .excalidraw sources and their matching .svg outputs
are included together.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 396c5316-17b7-4ee0-bed2-151f25daaf03

📥 Commits

Reviewing files that changed from the base of the PR and between b4a11c6 and f01fa00.

⛔ Files ignored due to path filters (3)

• docs/diagrams/container.svg is excluded by !**/*.svg
• docs/diagrams/module-overview.svg is excluded by !**/*.svg
• docs/diagrams/system-context.svg is excluded by !**/*.svg

📒 Files selected for processing (5)

• docs/diagrams/README.md
• docs/diagrams/container.excalidraw
• docs/diagrams/generate-diagrams.mjs
• docs/diagrams/module-overview.excalidraw
• docs/diagrams/system-context.excalidraw

[coderabbitai]

Actionable comments posted: 0