Skip to content

Add template architecture diagram workflow#150

Merged
guima-why merged 3 commits into
mainfrom
feature-repl-template-arch-diagram
Jul 7, 2026
Merged

Add template architecture diagram workflow#150
guima-why merged 3 commits into
mainfrom
feature-repl-template-arch-diagram

Conversation

@guima-why

@guima-why guima-why commented Jul 7, 2026

Copy link
Copy Markdown
Collaborator

Summary

This pull request adds the template architecture diagram workflow for ROS/IaC templates and integrates it into the interactive REPL Step 4 experience.

The main changes are:

  • Add architecture metadata loading, resource inventory extraction, rule-based facts, semantic planning, and Mermaid graph generation for ROS templates.
  • Add copied ROS architecture metadata and supplemental architecture rules so resource containment, attachments, compact child resources, and semantic relationships can be expressed consistently.
  • Add multi-view architecture rendering so complex templates can be shown as an overview plus focused detail diagrams instead of one oversized Mermaid graph.
  • Update the Step 4 REPL UI to render an immediate non-LLM architecture diagram first, then asynchronously replace it with the LLM-optimized result when semantic planning completes.
  • Add tabbed diagram navigation inside a candidate solution so multiple architecture views can be reviewed from the terminal UI.
  • Add rendering scripts and tests for real template preview workflows, including terminal-oriented preview behavior.
  • Add provider and prompt-flow support needed by the LLM architecture planner, including cache-friendly prompt boundaries and optional non-thinking behavior where supported by the configured provider.
  • Preserve internal tool rendering data as serializable metadata instead of carrying runtime renderer objects through stream events, avoiding deepcopy/pickle failures in REPL/session paths.
  • Keep public stream-json output stable by stripping internal render metadata and omitting empty metadata objects.
  • Regenerate i18n catalog updates for the new user-facing strings.

Motivation

The previous template architecture diagram feature produced a single rough Mermaid diagram with limited resource semantics. For realistic ROS templates this often made diagrams too long, too wide, or visually confusing, and it could miss important architecture relationships such as VPC/CEN connectivity, load balancing paths, attached resources, or compact configuration resources.

This change improves the feature from the result perspective:

  • Small templates can still be rendered as a single concise architecture diagram.
  • Complex templates can be split into a readable overview and detail views.
  • The UI no longer waits on the LLM before showing anything useful; users get an immediate deterministic diagram and then a refined version when available.
  • Step 4 can present multiple architecture views without replacing the existing solution-selection flow.
  • Internal render-only state is no longer stored as runtime objects in stream events, which reduces the risk of session serialization and scrollback failures.

User Impact

For interactive users:

  • Step 4 now shows architecture content earlier.
  • The architecture diagram can update after LLM optimization finishes.
  • Multiple diagrams for the same solution can be switched with the architecture-tab controls.
  • Large templates are easier to inspect because the planner can choose overview/detail views instead of forcing all relationships into one graph.

For headless / protocol users:

  • A2A and ACP event conversion remains compatible with the new diagram events.
  • Internal render metadata is filtered from public stream-json output.
  • Tool result rendering data is kept serializable and should not expose renderer instances or other runtime-only objects.

Implementation Notes

  • The architecture pipeline now separates raw template facts, supplemental rules, LLM semantic planning, validation, and terminal rendering.
  • Compact child resources and attachment resources are handled through configuration/rules rather than one-off hard-coded template fixes.
  • LLM semantic planning is still a single planning call for the architecture result, while deterministic rendering can run first for fast feedback.
  • The REPL renderer stores tool rendering hints as metadata and falls back to the tool registry when available.
  • Public output writers remove internal metadata keys such as _iac_code_tool_render and externalized-result metadata before emitting headless output.
  • Terminal preview rendering keeps termaid as a runtime optional import so Python 3.10 static lint/type checks do not require the Python 3.11-only diagram extra.

Validation

Local validation run before opening the PR:

make test

Result:

8478 passed, 1 skipped, 271 warnings in 30.45s

Additional local validation after fixing the CI lint failure:

make lint

Result:

All checks passed!
All checks passed!

The push also ran the repository pre-push hook and AK leak detection, which completed without finding data that needed scanning.

Risks and Follow-up

  • Architecture diagram quality is still partly LLM-dependent for complex templates, so future template review may uncover additional resource-specific semantics to encode in the supplemental rule file.
  • The copied architecture metadata is intentionally large because it mirrors the ROS resource metadata used by the online architecture editor; future synchronization should keep that data mechanically updated.
  • Terminal Mermaid rendering has inherent layout limitations, so very dense graphs may still need additional view-splitting or grouping rules over time.

@guima-why guima-why marked this pull request as ready for review July 7, 2026 12:15
@guima-why guima-why merged commit a7b0d94 into main Jul 7, 2026
13 checks passed
@guima-why guima-why deleted the feature-repl-template-arch-diagram branch July 7, 2026 12:15
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