Skip to content

docs: the READMEs' architecture figure, drawn from the source (#58) - #330

Merged
angeloINTJ merged 5 commits into
mainfrom
docs/architecture-svg
Nov 7, 2026
Merged

angeloINTJ merged 5 commits into
mainfrom
docs/architecture-svg

Conversation

@angeloINTJ

Copy link
Copy Markdown
Owner

Closes #58.

The three READMEs showed an ASCII sketch of the firmware. This replaces it with an SVG figure, in the READMEs' three languages and the Ângulo's two themes, drawn from the source by a new tool and checked in CI.

Why it is drawn by code

The sketch had drifted from the code, and the issue itself carried the drift: it quoted the sketch at lines that had moved, with a DHT22 on I2C and a Bluetooth console on BLE, and the sketch put TouchPriority on Core 1, which only Core 0 reads. A hand-drawn SVG would drift the same way. tools/readme_diagram.py draws the figure from the sources at the commit, with the builder and the readers of tools/manual_diagramas.py, which draws the manual's 28 diagrams the same way, and the gates job runs its --check.

What the figure says, and where each claim comes from

Claim Read from
Core 0 runs everything but the display in one loop, feeds the watchdog, and is the only core that writes the flash; its loop runs LogManager's watch over Core 1 src/main.cpp (loop( )), src/AppManager_Loop.cpp (checkCrossCoreHealth( )), docs/CONCURRENCY.md (the model, invariant 1)
Core 1 runs only DisplayManager::loopCore1( ), reads the touch there, and a flash write pauses it src/DisplayManager.cpp (core1Entry( ), the touch read), docs/CONCURRENCY.md
The state crosses as a snapshot under a mutex; the panel's events come back through a lock-free ring of 16 that Core 0 drains src/DisplayManager.h (_stateMutex, UI_EV_RING), src/DisplayManager.cpp (pullSnapshot( )), src/AppManager_Events.cpp
For 5 s after a touch, Core 0 holds the log's and the history's writes back (TouchPriority) TOUCH_PRIORITY_MS in src/AppManager.h, AppManager::isUserInteracting( ), the provider in src/AppManager_Boot.cpp, src/LogManager.cpp, src/StorageManager.cpp
The managers and their roles every src/*Manager.h; each role is pinned to a phrase of the header's @brief
Pico W, Pico 2 W, the Wire's Pico; 16 slots, 11 on the Wire; the panel each published image draws; the buzzer on all but the Air; Bluetooth on the alpha and the Air; MQTT, TLS, /metrics and syslog on every image drawn tools/generated/profiles.ini, platformio.ini, src/simut_config.h, src/ui/UiCaps.h, src/net/NetCaps.h, tools/release_manifest.py
The sensors' buses, the panel's 320×240 and SPI0, the LCD, the buzzer's GP22, classic Bluetooth each driver's @brief, src/display/*.h, src/BluetoothManager.h (SerialBT)
The network's peers: HTTP(S) or MQTT(S) telemetry and the alarm line, MQTT Discovery, GET /metrics, RFC 5424 over UDP, NTP the manual's readers in tools/manual_diagramas.py, src/NetworkManager.h

Each claim is a pattern the code has to keep. When one is gone, the tool exits 2 naming the file and the pattern, and draws nothing.

Where it departs from the issue

  • Colours. The issue asked for one colour per block (blue, green, gray, orange). The Ângulo, which came after the issue, keeps colour for action: the figure uses the tokens of docs/assets/angulo.css and the rules of the manual's diagrams, six token roles per theme and nothing else.
  • Content. The figure follows the code, not the issue's list: TouchPriority is drawn as the rule Core 0 keeps, the console's Bluetooth is classic SPP, the DHT22 has its own single-wire protocol, and the Wire has 11 slots. Themes and i18n are not drawn as Core 1 components: Core 0 loads the language pack (invariant 1), and Core 1 only draws. What Core 0 checks of each panel event is not drawn either: docs/AUTHORIZATION.md holds that, with the events left ungated and four saves registered as deviations, and no short line in a figure says it without hiding those.
  • Size. 832 px wide, under the issue's 1200: GitHub's README column is 838 px in 1280, 1440 and 1920 px windows (measured 2026-11-07, Chrome, signed out), so the 13 px text shows at 13 px.
  • Themes. Each README shows a light and a dark file through <picture>, as it shows the wordmark; GitHub wraps it in <themed-picture>, so the figure follows GitHub's theme, not the operating system's. Each file also carries the manual's frame as its background, so it reads when opened alone.

Also in this PR

  • tools/manual_diagramas.py: Svg takes its canvas width from the class, so the README's figure can draw at 832 px. Refactor: the 28 manual SVG are sha256-equal to the committed ones, and test_manual_diagramas.py passes its 884 controls.
  • src/simut_config.h: the inline comment of SIMUT_BLUETOOTH said BLE; the console is classic SPP, as the section's header says. Comment only.
  • The changelogs, tools/README.md (235 scripts), docs/images/README.md, AGENTS.md §7 and CLAUDE.md.

Tests

  • The refactor. The 28 manual SVG drawn after the change are sha256-equal to the committed ones; manual_diagramas.py --check finds nothing and test_manual_diagramas.py passes its 884 controls.
  • The figure. readme_diagram.py --check: 0 findings, under Python 3.14 and 3.11 (CI's).
  • The controls. test_readme_diagram.py: 342 controls, 0 failed, 5.4 s (3.14) and 5.7 s (3.11). They bite: with the README reader returning nothing, 44 fail; with the image comparison returning nothing, 18; with the premises switched off, 11.
  • The other gates. check_angulo.py, check_readme_numbers.py and scan_secrets.sh pass. The last one first failed this branch: it read TOKENS = 'docs/assets/angulo.css' as a literal credential, and the constant is FOLHA_ANGULO now.
  • Local CI gates. ci_gates_local.py --quick, in a depth-1 clone of cc4e42b: 83 steps. This branch fails the same 10 steps as origin/main does on this machine, nine Ângulo host tests and the feature model, all for the missing pio and Adafruit GFX of a fresh worktree; the two new steps pass.
  • Review. A separate reviewer, in two passes, found nine issues, all fixed:
    • three sentences in the figure that were false or missing a qualifier: the permission of each event, "while a finger is on the glass" (the code holds the writes for 5 s after a touch), and "every manager" in the alt text;
    • six missing premises or checks: the buzzer on the Wire, LogManager's watch over Core 1, the touch read, syslog on every image, the README's width, and the images index.
  • github.com. The three READMEs of this branch were checked in Chrome at 1280 px, signed out, in the light and the dark scheme. Each <picture> picks its language's file for the theme (architecture{,.pt-BR,.es-ES}.svg in light, architecture-dark… in dark), shown at 832 px, 1:1, on #ffffff and #0d1117.

Not verified

  • No firmware image was rebuilt for the comment-only change in src/simut_config.h.
  • The text's width is estimated with DejaVu Sans metrics, as for the manual's diagrams, which is about as wide as a system font gets. The figure was looked at in Chrome on Linux, here and on github.com, and not on macOS, Windows, Firefox or Safari.
  • Claim coverage is by review. Each claim has a premise, and the reviewer checked the ones above by mutation, but no machine-kept list holds every drawn claim to a pattern.
  • The native suites, the sanitizers and the fuzzer were not run locally: the only change under src/ is a comment. CI runs them.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Uy7K2qG2dULk2EBnwkCyZS

Ângelo Moisés Alves and others added 5 commits November 7, 2026 15:52
Svg wrote the manual's 720 px in two places, the right bound a text may
reach and the viewBox. Both read self.largura now, a class attribute that
is LARGURA, so a subclass can draw at another width: tools/readme_diagram.py,
which draws the README's architecture figure at 832 px.

Refactor, behaviour unchanged: the 28 SVG that manual_diagramas.py --write
draws are sha256-equal to the committed ones, --check finds nothing (Python
3.14 and 3.11), and tools/test_manual_diagramas.py passes its 884 controls.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Uy7K2qG2dULk2EBnwkCyZS
The three READMEs showed an ASCII sketch of the firmware. It had drifted
from the code: it put TouchPriority on Core 1, which only Core 0's
LogManager, StorageManager and WebManager read, and the issue that asked
for an SVG quoted it with moved lines, a DHT22 on I2C and a Bluetooth
console on BLE (the console is classic SPP, SerialBT).

tools/readme_diagram.py draws the figure from the sources at the commit,
with the builder and the readers of tools/manual_diagramas.py, and writes
six files: docs/images/architecture{,-dark}{,.pt-BR,.es-ES}.svg, one per
README language and Ângulo theme. Each README shows its pair through
<picture> and prefers-color-scheme, as it shows the wordmark (GitHub wraps
it in <themed-picture>, so it follows GitHub's theme), at the drawing's
width, with an alt text and a paragraph that keeps the split between the
cores in searchable text.

What it reads, and stops on when the code moves:
- every src/*Manager.h, each declaring its class; the role the figure
  gives a manager is prose pinned to a phrase of the header's @brief, and
  a manager without a role, or a role without its manager, stops the draw;
- the two cores: main.cpp's loop( ) feeds the watchdog and runs
  app.loop( ), whose loop calls LogManager's checkCrossCoreHealth( );
  Core 1 is launched on core1Entry( ), runs loopCore1( ) and reads the
  touch there; docs/CONCURRENCY.md still says Core 0 runs everything but
  the display, Core 1 never touches the flash and a flash write stalls it;
- between them: the snapshot under _stateMutex; the lock-free ring of
  UI_EV_RING (16) events that Core 0 drains; and the log and history
  writes Core 0 holds for TOUCH_PRIORITY_MS (5 s) after a touch, through
  AppManager::isUserInteracting( ), which TouchPriority reads. What Core 0
  checks of each event is not drawn: docs/AUTHORIZATION.md holds that,
  with the events left ungated and four saves registered as deviations,
  and no short line in a figure says it without hiding those;
- the boards and images from the build profiles (Pico W, Pico 2 W, the
  Wire's plain Pico and ENC28J60; 16 slots on every published image and 11
  on the Wire; the panel each published image draws; the buzzer on every
  image but the Air; MQTT, TLS, /metrics and syslog on every image drawn), the
  sensor buses from each driver's @brief, the panel's 320x240 and SPI0,
  the network's peers from the manual's readers (two telemetry transports,
  MQTT Discovery, GET /metrics, RFC 5424 over UDP) and NTP.
The path of the Ângulo's stylesheet is FOLHA_ANGULO: named TOKENS, a quoted
string assigned to it read as a literal credential to scan_secrets.sh.

The colours are the Ângulo's: the values come from docs/assets/angulo.css
and the rules of the dg-* classes from the manual's CSS in
tools/build_manual.py, written into each SVG's <style> with the theme's
values, since an SVG behind <img> cannot see the page's CSS. Each file
carries the manual's frame (.moldura-svg: the surface, a 1 px line, the
card's corner) as its background, so it reads when opened alone and every
text sits on a background of the Ângulo's table of combinations. Six token
roles per theme, nothing else. The issue asked for four colours, one per
block; the Ângulo, which postdates it, keeps colour for action.

832 px wide: GitHub's README column is 838 px in 1280, 1440 and 1920 px
windows (measured 2026-11-07, Chrome, signed out), so the 13 px text is
shown at 13 px; --check holds each README's <img> to that width. --check
redraws the six and reads the three READMEs: 0 findings on this tree
(Python 3.14 and 3.11); check_angulo.py, check_readme_numbers.py and
scan_secrets.sh pass.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Uy7K2qG2dULk2EBnwkCyZS
tools/test_readme_diagram.py puts one fault at a time into a scratch copy
of the six figures, the three READMEs or the sources the figure reads,
never into the tree, and requires exactly the findings that fault is
about: one character of each file, a file that is not UTF-8 and each file
deleted give one finding; in the READMEs, the <picture> removed, a
<source> or the <img> on another file, the alt empty or gone, the <img>
narrower than the drawing or without its width, the section renamed and a
box-drawing character in the section give one each, and the same
character in another section none; in the sources, the slots, the ring
and the touch's window changed change all six drawings and what they say,
a token colour changes its theme's three files and not the others, a
manager without a role, a role without its manager and each of the 11
@brief reworded stop the draw, and each of the 127 patterns the tool
reads, mangled, and each of the 45 files it reads, deleted, exit 2 naming
it. The line breaker keeps code whole; two draws, and two --write with
different hash seeds, give the same bytes.

342 controls, 0 failed, 5.4 s (Python 3.14; 5.7 s under 3.11, CI's).
The controls bite: with the README reader returning nothing, 44 fail;
with the image comparison returning nothing, 18; with the premises
switched off, 11. The tree's figures, READMEs and tokens are the same
bytes after a run as before it.

The gates job runs readme_diagram.py --check and this file after the
manual's diagrams. Locally (ci_gates_local.py --quick in a depth-1
clone), the branch fails the same ten steps as origin/main, all for this
machine's missing pio and libraries, and passes the two new ones.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Uy7K2qG2dULk2EBnwkCyZS
The console behind SIMUT_BLUETOOTH is classic Bluetooth over SPP
(SerialBT, RFCOMM), as the section's own header and BluetoothManager say;
the comment on the #define said "Bluetooth BLE CLI". Comment only, same
line count; no image rebuilt for it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Uy7K2qG2dULk2EBnwkCyZS
… indexes and AGENTS.md

CHANGELOG and CHANGELOG.pt-BR say what the figure shows, how it stays
true and the BLE comment; tools/README.md lists readme_diagram.py and its
controls under "Called by CI" (235 scripts, 94 there; CLAUDE.md quotes the
total); docs/images/README.md names the six files and their tool, and
says that the brand, the figure and the manual's diagrams are drawn by
code rather than that every file in the folder is a capture; AGENTS.md
section 7 adds the figure to the copies of the tokens and what to do when
one changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Uy7K2qG2dULk2EBnwkCyZS
@github-actions github-actions Bot added documentation Improvements or additions to documentation ci Continuous integration and automation tools Build tools, scripts, and developer tooling code Firmware source changes (src/, WebUI.h) labels Nov 7, 2026
@angeloINTJ
angeloINTJ merged commit 1c25e39 into main Nov 7, 2026
15 checks passed
@angeloINTJ
angeloINTJ deleted the docs/architecture-svg branch November 7, 2026 19:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci Continuous integration and automation code Firmware source changes (src/, WebUI.h) documentation Improvements or additions to documentation tools Build tools, scripts, and developer tooling

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Create an SVG architecture diagram for the README

1 participant