docs: add runtime architecture diagram to README by YiWang24 · Pull Request #133 · YiAgent/openbot

YiWang24 · 2026-08-20T05:01:28Z

What

Adds a generated SVG architecture diagram to the ## Architecture section of the README, above the existing text flow.

The diagram traces the actual runtime path, read off the code rather than the prose:

GitHub webhook
  -> ① POST /webhook/github (HMAC verify, parse -> UnifiedEvent, 202)
  -> ② ingest_webhook (dedup, router, run state machine, check run)
  -> ③ Redis Stream (TaskSpec v3, consumer group, XAUTOCLAIM, DLQ)
  -> ④ worker: LLM classifier + 10-gate preflight chain
  -> ⑤ workflow handler -> DeepAgents runtime
  -> ⑥ GitHub write-back

with .openbot/config.yaml, the sandbox, Redis, Postgres, the LiteLLM router, and the evals/ facade attached to the stages they actually touch. The two dashed containers mark the web and worker process boundary, so it is visible that the queue is what separates "must answer inside GitHub's delivery deadline" from "everything expensive".

Doc correction included

The ASCII flow next to the diagram listed preflight middleware before TaskSpec v3 / Redis Stream. That is the older decide_and_enqueue design and no longer matches the code:

openbot/application/use_cases/ingest_webhook.py has no preflight call at all — step 5a enqueues immediately with classifier_output=None, with a comment explaining that the classifier's 10 s timeout does not fit inside GitHub's 10 s webhook delivery deadline.
openbot/infrastructure/queue/worker.py::_execute_task_spec runs load_for_repo, then classify_for_dispatch, then run_preflight(ctx, build_preflight_chain()), and only then execute_handler.

So the ASCII flow now reads ... -> Redis Stream -> worker -> LLM classifier -> preflight middleware -> dispatcher -> ....

Worth noting separately: the TaskSpec docstring in openbot/infrastructure/queue/task_spec.py still claims "Built by the webhook async segment after running full preflight. The worker trusts this and executes the handler without re-running any preflight gates." That is stale in the same way, but it is a code comment rather than user-facing docs, so it is left out of this PR.

Why a generator script

scripts/build_architecture_diagram.py emits the SVG from node/edge tables instead of the SVG being hand-authored. A 16 KB hand-written SVG rots the first time a box moves; this way the diagram can be re-derived:

python3 scripts/build_architecture_diagram.py

Verification

ruff format / ruff check clean on the new script.
The SVG passes all six gates of the diagramming skill's validator — XML, marker references, arrow collisions, semantic geometry, composition quality, and render — under the strict showcase composition profile: zero edge crossings, at most two bends per edge, at least 40 px of whitespace between nodes, 20 px container gutters.
Exported to PNG and visually reviewed: no arrows through component interiors, no label/arrow or label/label overlaps, arrows terminate on node edges, legend clear of the flow corridors.

No Python source under openbot/ or evals/ is touched, so make check behaviour is unchanged.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MaszS22MH8osYjDjqgD5gr

Generated by Claude Code

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

Summary by CodeRabbit

Documentation
- Expanded the Architecture documentation with a runtime architecture diagram.
- Clarified webhook processing across web and worker processes.
- Updated the processing flow to show classification and preflight checks before dispatch and workflow execution.
New Features
- Added an accessible architecture diagram to visually explain system components and processing flow.

Adds a generated SVG architecture diagram to the Architecture section, showing the real runtime path: GitHub webhook -> FastAPI ingress -> ingest_webhook (dedup / router / run state machine) -> Redis Stream (TaskSpec v3) -> worker (LLM classifier + 10-gate preflight chain) -> DeepAgents workflow handler -> GitHub write-back, with the repo config, sandbox, Redis, Postgres, LLM router and the evals facade attached to the stages they actually touch. The diagram is generated by scripts/build_architecture_diagram.py rather than hand-authored, so it can be re-derived when the architecture moves. Geometry and composition are validated under the fireworks-tech-graph showcase profile (zero edge crossings, <= 2 bends per edge, >= 40px node whitespace). Also corrects the adjacent ASCII flow: preflight middleware runs in the worker, after the queue, not before the enqueue. ingest_webhook has no preflight call; worker._execute_task_spec runs classify_for_dispatch and run_preflight(build_preflight_chain()) before execute_handler, because the classifier's 10s timeout does not fit inside GitHub's webhook delivery deadline. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MaszS22MH8osYjDjqgD5gr

coderabbitai · 2026-08-20T05:01:37Z

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 2144ad0c-2947-47f7-b980-412c57fdeddb

📥 Commits

Reviewing files that changed from the base of the PR and between 7dd90bc and d0b708e.

⛔ Files ignored due to path filters (1)

docs/assets/openbot-architecture.svg is excluded by !**/*.svg

📒 Files selected for processing (2)

README.md
scripts/build_architecture_diagram.py

📝 Walkthrough

Walkthrough

The PR adds a standalone SVG architecture diagram generator and updates the README with the two-process runtime model. The documented flow moves classification and preflight processing to the worker after Redis dequeue.

Changes

Architecture documentation

Layer / File(s)	Summary
Architecture model and layout `scripts/build_architecture_diagram.py`	Defines the diagram nodes, containers, edges, themes, labels, geometry, and legend data.
Accessible SVG rendering `scripts/build_architecture_diagram.py`	Generates escaped SVG markup with accessibility metadata, styled process containers, directional edges, nodes, labels, and legend elements.
Generated output and README integration `scripts/build_architecture_diagram.py`, `README.md`	Writes the generated SVG to `docs/assets/openbot-architecture.svg`. Documents the separation between the bounded `web` process and asynchronous `worker` processing.

Estimated code review effort: 3 (Moderate) | ~20 minutes

✨ 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 claude/project-architecture-diagram-i9u634

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

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

SonarCloud's quality gate failed this PR with "C Security Rating on New Code". The only new Python is the diagram generator, and it carried a textbook path-injection taint flow: sys.argv -> Path(argv[1]) -> out.parent.mkdir() + out.write_text(), which Sonar reports as S2083. The override was a leftover from authoring the script outside the repo. The generator regenerates one committed file that README.md links to, so an output-path argument could only ever produce an untracked copy the README cannot see. Removing it deletes the taint source outright rather than suppressing the finding. The SVG regenerates byte-identically, so the diagram itself is unchanged. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MaszS22MH8osYjDjqgD5gr

sonarqubecloud · 2026-08-20T05:05:20Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

qodo-code-review · 2026-08-20T05:16:57Z

ⓘ Qodo reviews are paused because the subscription is no longer active. Ask your workspace admin to reactivate the subscription to resume reviews. Manage billing

YiWang24 marked this pull request as ready for review August 20, 2026 05:16

YiWang24 merged commit 7cdac2c into main Aug 20, 2026
8 checks passed

YiWang24 deleted the claude/project-architecture-diagram-i9u634 branch August 20, 2026 05:17

YiWang24 mentioned this pull request Aug 20, 2026

docs: add eval architecture diagram and OpenBot logo #134

Merged

Navigation Menu

Repository navigation

docs: add runtime architecture diagram to README - #133

docs: add runtime architecture diagram to README#133
YiWang24 merged 2 commits into
mainfrom
claude/project-architecture-diagram-i9u634

YiWang24 commented Aug 20, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Aug 20, 2026 •

edited

Loading

Review failed

Walkthrough

Changes

Uh oh!

sonarqubecloud Bot commented Aug 20, 2026

Uh oh!

qodo-code-review Bot commented Aug 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

YiWang24 commented Aug 20, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Doc correction included

Why a generator script

Verification

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Aug 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review failed

Walkthrough

Changes

Uh oh!

sonarqubecloud Bot commented Aug 20, 2026

Quality Gate passed

Uh oh!

qodo-code-review Bot commented Aug 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

YiWang24 commented Aug 20, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Aug 20, 2026 •

edited

Loading