Skip to content

docs(diagrams): fix what the rendered pages showed - #61

Merged
EstebanGZam merged 1 commit into
mainfrom
docs/diagram-visual-fixes
Sep 21, 2026
Merged

EstebanGZam merged 1 commit into
mainfrom
docs/diagram-visual-fixes

Conversation

@EstebanGZam

Copy link
Copy Markdown
Contributor

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.

  • The task register is updated in this pull request
  • 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

The diagrams had been checked for geometry only: overlapping boxes and
connectors crossing them. Rendered with the draw.io CLI, the thirteen pages
showed defects that check cannot see, because it does not know where draw.io
places a connector's label or how a stencil stretches.

- Sequences: every actor was stretched to its lifeline's 160 px width and
  flattened to 46 px; actors now use a 30 px lifeline in proportion, and
  message labels wrap to their own arrow's length instead of 36 characters.
- Economical infrastructure: the alias-records label sat on the Route 53
  label, two labels were squeezed between workload boxes, and three labels
  landed on lane titles or borders.
- Full infrastructure: the egress connectors ran through the Transit Gateway
  label, and the frontend route and the todos connector crossed auth-api.
- Views and flows: tighter labels, a compact platform overview, a controls
  note sized to its text, and solid arrows for the sequential pipeline.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@EstebanGZam
EstebanGZam merged commit 8030446 into main Sep 21, 2026
1 check passed
@EstebanGZam
EstebanGZam deleted the docs/diagram-visual-fixes branch September 21, 2026 22:05
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