docs: lead the README with an accounts and trust-boundary diagram - #49
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
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
.drawiofiles 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 indocs/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.mddrops the "editable draw.io versions" list and points atdocs/ARCHITECTURE.mddocs/ARCHITECTURE.mddrops thearchitecture.drawioparagraph and cross-references the README diagramVerified
.drawiois tracked and none remain indocs/.docs/ARCHITECTURE.md.Review notes