Skip to content

docs(docs): redraw the as-built views at v0.2.0 - #170

Merged
bibi45c merged 1 commit into
mainfrom
docs/78-as-built-v0.2.0
Nov 9, 2026
Merged

bibi45c merged 1 commit into
mainfrom
docs/78-as-built-v0.2.0

Conversation

@bibi45c

@bibi45c bibi45c commented Nov 9, 2026

Copy link
Copy Markdown
Owner

Summary

docs/diagrams/as-built.md was last drawn at ea0f9b5 (16 October). It did not show the console, plan limits with Redis (#157), held-reservation recovery (#154, #155), the plans, console_users and wallet_adjustments tables, or the cloud configuration used on 18 and 19 October. This PR redraws the page from the code at v0.2.0 (1d259c1).

It is a docs-only change: no code, chart, workflow or rule file changes. Sections:

  1. Logical view: adds the console, the rate limiter and Redis, and the metering recover job.
  2. Domain design (new): domain events → subdomains → five bounded contexts → three services; the context map; an aggregate diagram with the invariants the database enforces.
  3. Local stack: Redis is now used (limits are on by default in compose); adds the console and Prometheus.
  4. Cloud: the cfg-D configuration of the 18 and 19 October runs, with a deployment table; Redis and the recovery CronJob as optional, kind-only parts; repository defaults against cfg-D.
  5. Persistence: ER diagrams for access (8 tables) and accounting (4 tables); the Redis key layout; concurrency notes.
  6. Use case "bill one streamed call": a class diagram with the design patterns found in the code, the sequence (now with the limit step), the reservation state diagram with the recovery path, and the charge rule.
  7. Use case "admit one call" (new): a class diagram and a sequence with every refusal path (401, 403, 429, 503, 402).
  8. Delivery pipeline (new): the six workflows, Dependabot, and the operator-run delivery.
  9. Deviations: rows updated for Redis, recovery, console key management, cfg-D, and the Should and Could items.

These diagrams are also the source for the final report's architecture figures.

Linked issues

Closes #78

Delivery

complete

Acceptance phase

pre-merge. The owner reviewed the content, through a section-by-section Chinese translation, before this PR was opened.

Verification

Check Environment Head / base Result
Render every mermaid block (14) with mermaid.render mermaid 11.4.1 (jsDelivr ESM), Chromium in the Claude desktop browser pane, Windows 11 9034e85 / main at 1d259c1, up to date, no uncommitted inputs 14 of 14 rendered, no error
Relative links and in-page anchors of as-built.md Python 3.14.0 script same 0 broken links, 0 broken anchors
python -m unittest discover -s tools/repo/tests Python 3.14.0, Windows 11 same 53 tests OK
Facts against the code read at 1d259c1; each section lists the files it was checked against same —

CI on this PR is the remaining check.

Risk and recovery

Docs only. Recovery: revert the PR. The anchor #4-physical-view-cloud, linked from docs/diagrams/index.html, is unchanged; the deviations section moved from 7 to 9, and nothing in the repository links its old anchor.

Known limitations

  • docs/diagrams/index.html still describes the 12 October plan, with 5b updated to 17 October (it says, for example, that the chart has no Redis). It is labelled as that snapshot and is not changed here.
  • The cloud view describes runs before plan limits and recovery existed; those two parts are marked kind-only, because they never ran on EKS.
  • The cfg-D values come from the evidence bundles of 17 and 18 October (release assets evidence-day2 and evidence-day3), not from a values file in the repository.

Posted by an agent.

Brings docs/diagrams/as-built.md from ea0f9b5 (16 Oct) to v0.2.0: the console,
plan limits with Redis, held-reservation recovery, the access plans and console
tables, the accounting adjustments table, and the cfg-D cloud configuration. Adds a
domain derivation with aggregates, class diagrams for two use cases (billing one
streamed call, admitting one call), the Redis key layout and the delivery pipeline.

Refs #78
@bibi45c
bibi45c marked this pull request as ready for review November 9, 2026 04:44
@bibi45c
bibi45c merged commit b537f1f into main Nov 9, 2026
23 checks passed
@bibi45c
bibi45c deleted the docs/78-as-built-v0.2.0 branch November 9, 2026 04:47
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.

[task][docs] Draw the as-built architecture views and one use-case design

1 participant