Repository navigation
docs(diagrams): complete the diagram set in draw.io - #60
Merged
Merged
Conversation
Three draw.io documents join the infrastructure one, one per kind of diagram: sequence diagrams with a page per sequence, architecture views (application, platform overview, namespace isolation), and flows (delivery pipeline, observability). The sequence pages are rendered from the Mermaid source, so they carry exactly the messages that were reviewed. The lifecycle sequence described a way down that no longer exists: since microservice-app-ops#122 the shutdown needs no GitOps pull request, a checksummed receipt replaces the --gitops-revision gate, and a post-destroy sweep removes what the cluster's controllers left in AWS. The Mermaid and the draw.io page now draw that. The three Mermaid diagrams on the architecture page are refreshed to the same design, the Azure recovery domain loses its "planned" label, and a diagram index lists every diagram with the date it describes. The infrastructure pages gain explicit routes for the nine connectors whose path had only been checked between waypoints. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This was referenced Sep 21, 2026
EstebanGZam
added a commit
that referenced
this pull request
Sep 21, 2026
## What changes The four draw.io documents are corrected against their rendered output. No content changes; the same diagrams now read correctly. - **Sequence diagrams.** Actors use a narrow lifeline in proportion instead of a stick figure stretched to 160 px and flattened to 46 px. Message labels wrap to the length of their own arrow, and lifelines are 220 px apart. - **Economical infrastructure.** No label sits on another: the Route 53 label, the workload connectors, and the labels that landed on the delivery lane's title and border are moved or shortened. Azure DNS moves into the network note. - **Full infrastructure.** The Transit Gateway label moves beside its icon, so the egress connectors no longer run through it. The workloads are laid out in two rows so that no connector crosses auth-api. - **Views and flows.** The platform overview is compacted, the namespace-isolation note is sized to its text, the pipeline uses solid arrows for its sequential steps, and the observability labels are shortened. ## Why The maintainer asked whether the diagrams had been checked visually, pointing at the elongated actors. They had not: microservice-app-docs#57 to #60 were checked for geometry only, and #60 says so. A geometry check cannot see where draw.io places a connector's label or how a stencil stretches to its cell. ## Tasks No task register covers documentation in this repository. This corrects the work closed under microservice-app-docs#52, which is noted there. - [x] The task register is updated in this pull request - [x] Every task ticked here was verified by locating its artifact Neither box applies literally: nothing is ticked here. ## How it is verified Every page was rendered with the draw.io CLI (`drawio --export --format png --page-index N`) and inspected: two infrastructure pages, three views, two flows, and six sequences — thirteen in all. The first pass found the defects above. After the fixes, all thirteen were re-rendered and inspected again, and none remains. The geometry check still passes on every page, and the sequence renderer still asserts that each page's message count matches its Mermaid block: ``` == Economical profile: 0 issue(s) == Application: 0 issue(s) == Full profile: 0 issue(s) == Platform overview: 0 issue(s) == Delivery pipeline: 0 issue(s) == Namespace isolation: 0 issue(s) == Observability: 0 issue(s) Service CI: 13 · Promotion: 11 · Production canary: 12 · Rollback: 5 · Profile lifecycle: 16 · Secret delivery: 7 ``` - [ ] Infrastructure changes: the documentation consulted through the required MCP servers is listed above No Terraform, tfvars, or Kubernetes manifest changes here. ## Risk and rollback None to the running system. Revert the commit. ## What this PR does not do It does not change what any diagram says. It does not commit the rendered PNGs or the generators. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5 <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
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.
What changes
The diagram set is complete, in four draw.io documents grouped by kind, all linked from a new diagram index in
docs/Architecture diagrams.md:MicroTodoSuite infrastructure.drawio(existing)MicroTodoSuite architecture views.drawio(new)MicroTodoSuite flows.drawio(new)MicroTodoSuite sequence diagrams.drawio(new)The three Mermaid diagrams on the architecture page are refreshed to the same design. The lifecycle sequence, in Mermaid and in draw.io, now draws the way down that exists today.
Why
microservice-app-docs#52 listed the diagrams still missing: the three Mermaid refreshes, the observability flow, and an index linking every diagram with the date it describes. The maintainer also asked for the rest of the set in draw.io, one document per kind, one page per diagram.
The lifecycle sequence was wrong. It showed a merged GitOps quiescence pull request and the
--gitops-revisiongate. Since microservice-app-ops#122 (2026-09-20), the shutdown needs no pull request:quiescence-receiptwrites a checksummed dry-run inventory,plan-downtakesRECEIPTandVOLUME_RECORD, and a post-destroy sweep between the workload and networking bundles removes what the controllers left in AWS. Read frommicroservice-app-ops/docs/aws-profile-lifecycle.mdonmain, lines 74 to 116.Tasks
No task register covers documentation in this repository; the work is microservice-app-docs#52, whose remaining activities this pull request delivers, and which is closed with it.
Neither box applies literally: this repository has no
tasks.md.How it is verified
Every fact was read from the repositories, not recalled:
apps/*/base/service.yamlin microservice-app-gitops — frontend 8080 with 9113 and 9114, auth-api 8000, users-api 8083, todos-api 8082, log-message-processor 9090.OTEL_EXPORTER_OTLP_ENDPOINTpoints tojaeger-collector.observability.svc:4317.loki.writepushes toloki.observability.svc:3100.WorkloadHighErrorRate,WorkloadHighLatencyandRunningImageHighOrCriticalVulnerabilities, with the Slack receiver's webhook delivered fromlex-mts-eco-sm-slackobsby External Secrets.environments/base/, plus a ResourceQuota per environment.The sequence document is rendered from
docs/Sequence diagrams.mdby a parser that fails when a page's message count differs from its Mermaid block. The counts are 13, 11, 12, 5, 16 and 7. A second check confirms that every message sits within its lifelines.The other nine pages were checked by the geometry script run in the authoring session (not committed). This run extends it to cover the whole connector path — exit point, waypoints, entry point — and to flag any connector that is neither straight nor pinned:
The extension found nine connectors on the already-merged infrastructure pages that had only been checked between waypoints. They now carry explicit routes. It also found one label on the new platform overview escaping its group, which was fixed. The draw.io MCP server read back every page of all four files. No file contains status wording (
planned,not built,as built).Nothing was rendered to an image here; no draw.io CLI is installed.
No Terraform, tfvars, or Kubernetes manifest changes here.
Risk and rollback
None to the running system. Revert the commit.
What this PR does not do
It does not commit the generators or the geometry check. The sequence draw.io pages are rendered from the Mermaid page, so a later change to a sequence needs the same change in both. That is stated under the sequences' introduction.
🤖 Generated with Claude Code