Skip to content

docs: lead the README with an accounts and trust-boundary diagram - #49

Merged
Robobc merged 1 commit into
mainfrom
docs/architecture-accounts-diagram
Aug 27, 2026
Merged

docs: lead the README with an accounts and trust-boundary diagram#49
Robobc merged 1 commit into
mainfrom
docs/architecture-accounts-diagram

Conversation

@Robobc

@Robobc Robobc commented Aug 27, 2026

Copy link
Copy Markdown
Contributor

What

Leads the README's Architecture section with an account-structure and trust-boundary diagram, and removes the four editable draw.io sources from the repo in favour of the rendered PNG.

Why

The README had no view of how the platform sits across accounts, which is the first thing a platform team needs to see. The new diagram reads top to bottom in request-flow order:

  • Application / UI — where requests start
  • AWS Organization — a management account (Control Tower, SCPs for AgentCore at Org/OU level, IAM Identity Center, org CloudTrail), a Security OU (log archive, security tooling), a Workloads OU (one account per use case, each with agents on Runtime, Memory, and a local token vault), and a Platform OU (auth, Gateway, agent registry, observability, golden-path IaC)
  • Inference — Amazon Bedrock, Guardrails, per-account model access

The trust model is the point of the picture: applications sign in once and carry a validated JWT, and cross-account trust is OAuth token exchange with no cross-account IAM on the data plane.

Changes

The .drawio files leave the repo. They were 553 lines of XML that only render in an external editor, kept in sync by hand against the Mermaid diagram in docs/ARCHITECTURE.md, which GitHub renders natively and which was already declared the source of truth. One PNG plus that Mermaid block covers what readers need.

Both docs that referenced the removed files are updated, so nothing links to a path that no longer exists:

  • README.md drops the "editable draw.io versions" list and points at docs/ARCHITECTURE.md
  • docs/ARCHITECTURE.md drops the architecture.drawio paragraph and cross-references the README diagram

Verified

  • No .drawio is tracked and none remain in docs/.
  • Every relative image and link target across all 12 tracked docs resolves. Without the doc edits the removals would have left four dead links in the README and one in docs/ARCHITECTURE.md.
  • The PNG's rendered text was read back with OCR rather than assumed, because the image is a screen capture with no embedded source XML to inspect. It renders "Enterprise Agentic AI Platform — accounts and trust boundaries" over a subtitle describing how the platform, workloads, and governance sit across accounts, and its PNG metadata chunks carry no diagram source.

Review notes

  • Net −550 lines.
  • The PNG is a 2450×1602 screen capture, so it carries an Apple sRGB profile and an XMP block. It renders correctly on GitHub; a native draw.io export at 2x would be marginally crisper if that matters later.

Replaces four editable draw.io sources in docs/ with a single rendered PNG, and
adds the account-structure view the README was missing: applications sign in
once and carry a validated JWT, agents run in workload accounts (one per use
case, owned by the teams that build them), the platform account holds the shared
services, and cross-account trust is OAuth token exchange with no cross-account
IAM on the data plane. Governance and security tooling sit in their own accounts.

The .drawio files leave the repo entirely. They were four large XML sources
(553 lines) that only render in an external editor, kept in sync by hand against
the Mermaid diagram in docs/ARCHITECTURE.md, which GitHub renders natively and
which was already declared the source of truth. One PNG plus that Mermaid block
covers what readers actually need.

Both docs that pointed at the removed files are updated, so nothing is left
linking to a path that no longer exists:

- README.md drops the "editable draw.io versions" list and points at
  docs/ARCHITECTURE.md instead.
- docs/ARCHITECTURE.md drops the architecture.drawio paragraph and
  cross-references the README diagram for the account view.

Verified:
- No .drawio is tracked and none remain in docs/.
- Every relative image and link target across all 12 tracked docs resolves;
  the removals would otherwise have left four dead links in the README and
  one in docs/ARCHITECTURE.md.
- The PNG's title and subtitle were read back with OCR rather than assumed,
  because the image is a screen capture with no embedded source XML to inspect:
  it renders "Enterprise Agentic AI Platform - accounts and trust boundaries"
  over a subtitle about how the platform, workloads and governance sit across
  accounts. Its PNG metadata chunks carry no diagram source.
@Robobc
Robobc merged commit fa90ed2 into main Aug 27, 2026
8 of 9 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.

1 participant