Skip to content

[FEAT]: add architecture and test-execution-flow diagrams to the Concepts overview#37

Merged
spencrr merged 2 commits into
microsoft:mainfrom
bashirpartovi:dev/bashirpartovi/docs-diagrams
May 18, 2026
Merged

[FEAT]: add architecture and test-execution-flow diagrams to the Concepts overview#37
spencrr merged 2 commits into
microsoft:mainfrom
bashirpartovi:dev/bashirpartovi/docs-diagrams

Conversation

@bashirpartovi

@bashirpartovi bashirpartovi commented May 7, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds two new visual diagrams to the RAMPART documentation and rewrites the Concepts -> Overview page so that the diagrams flow naturally with the surrounding narrative. Also clears out a couple of pre‑existing doc‑warnings unrelated to the diagrams.

What's changed

New diagrams (added to docs/images/):

  1. rampart-architecture-dark.svg (+ .png fallback) - layered architecture showing PyRIT (L1) → RAMPART (L2) → Consumer Package (L3) → Agent Under Test (L4), and where the consumer's AgentAdapter and pytest suite plug in.
  2. rampart-execution-flow-dark.svg (+ .png fallback) - request/response cycle for a single test run: Test → Attacks/Probes → AgentAdapter → Agent System and back.
  3. Light variants are also included for completeness, but the docs currently embed the dark versions only.

docs/concepts/overview.md — restructured:

  • Architecture at a Glance (new section) introduces the layered diagram and frames how the layers fit together. The pre‑existing component table now reads as a "zoom in" on the runtime path.
  • Execution Lifecycle now leads with the execution‑flow diagram as the high‑level visual, then transitions into the existing mermaid sequence diagram as the per‑turn detail.
  • The previous mermaid Component Model diagram (which the architecture image fully supersedes) was removed to avoid redundancy.

docs/stylesheets/custom.css - small CSS rule to make embedded SVG/PNG diagrams scale to the content column instead of honoring their intrinsic width/height attributes (which previously caused the diagrams to render either squeezed or overflowed).

Cleanup of pre‑existing doc warnings (unrelated to the diagrams, but they were noisy in mkdocs serve while iterating):

  • Removed the orphaned docs/guides/ folder (authoring-tests.md, results-and-reporting.md). These files were byte‑identical duplicates of the canonical docs/usage/*.md versions already in the nav, were not linked from anywhere, and contained one broken cross‑link.

How to verify

From the RAMPART directory:

uv sync --group docs
uv run mkdocs serve

Then open Concepts → Overview and check that:

  • The "Architecture at a Glance" diagram renders at column width with readable text.
  • The "Execution Lifecycle" diagram renders correctly above the existing mermaid sequence diagram.
  • mkdocs serve no longer reports the orphaned‑pages warnings or the broken getting-started/pytest-integration.md#rampart_sinks link warning.

Screenshots

image image

@bashirpartovi bashirpartovi requested a review from a team May 7, 2026 13:38
Comment thread docs/images/rampart-architecture-dark.png
Comment thread docs/concepts/overview.md Outdated
Comment thread docs/concepts/overview.md
Comment thread docs/concepts/overview.md

@nina-msft nina-msft left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

small wording nit & tala look at my comments for the lazy load config, otherwise lgtm!

@spencrr spencrr merged commit e4e9278 into microsoft:main May 18, 2026
11 checks passed
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.

4 participants