Amazon Bedrock AgentCore: Automating Mermaid architecture diagrams and semantic indexing

From code to diagrams: Agentic architecture documentation with Amazon Bedrock AgentCore

A global interdealer broker now auto-generates more than 140 architecture diagrams every week with minimal human intervention. The setup uses a serverless agent that scans .NET repositories, emits Mermaid diagram source, validates and renders SVGs, publishes artifacts to S3, and indexes diagram metadata into an Amazon Bedrock Knowledge Base for semantic search.

How the pipeline works, at a glance

  • Developer commit (AWS CodeCommit) triggers a pipeline (AWS CodePipeline).
  • A CodeBuild job packages the source and invokes the Strands agent running on Amazon Bedrock AgentCore.
  • The agent fetches the source archive from S3, scans production code (excluding tests/build artifacts), and extracts architecture constructs.
  • It generates Mermaid-based UML diagrams (class, sequence, state, component, activity), validates Mermaid syntax, converts to SVG, and uploads Mermaid + SVG + metadata JSON to an S3 docs bucket.
  • Diagram metadata and Mermaid source are embedded using Amazon Titan Text Embeddings v2 and ingested into an Amazon Bedrock Knowledge Base to enable semantic search and natural-language queries (RAG).
  • CloudWatch and SNS provide monitoring and alerts, and IAM governs permissions for pipeline and agent actions.

Key components

  • Amazon Bedrock AgentCore (serverless runtime) hosting the Strands agent
  • Amazon Bedrock Knowledge Bases (RAG / semantic retrieval)
  • AWS CodeCommit → CodePipeline → CodeBuild for CI/CD orchestration
  • Amazon S3 for source archives, Mermaid files, SVGs, metadata, and used as the vector store backend in this design
  • Amazon Titan Text Embeddings v2 for vectorization (as noted in the walkthrough)
  • AWS CloudWatch, IAM, AWS CDK and Amazon SNS for monitoring, permissions, and deployment automation

What the agent actually produces

Each run produces versionable, human-editable artifacts you can check into docs repos or surface in wiki pages:

  • Mermaid source files (text-first diagrams you can diff)
  • SVG renderings for embedding in runbooks and documentation
  • Metadata JSON records used for semantic indexing and retrieval

{
“diagram_type”: “sequence”,
“title”: “Message Publishing Flow”,
“description”: “End-to-end message publishing sequence including connection establishment, channel creation, and broker confirmation.”,
“entities”: [“Publisher”, “ConnectionManager”, “Channel”, “RabbitMQ Broker”],
“mermaid_source”: “sequenceDiagram\n Publisher->>ConnectionManager: GetConnection()…”,
“svg_s3_uri”: “s3://amzn-s3-demo-source-bucket2/svg/3-sequence-diagram-publish.svg”,
“source_repository”: “my-dotnet-service”,
“generated_at”: “2025-01-15T10:30:00Z”
}

“Generate complete UML documentation for {project_name}. Steps: 1. Fetch source code from Amazon S3 bucket: {source_s3_bucket}, key: {source_s3_key} 2. Scan and analyze the codebase 3. Generate all required diagrams 4. Validate and convert each diagram to SVG 5. Upload all artifacts to Amazon S3 Begin now by fetching the source code.”

Why an agentic workflow matters

Instead of a single-shot prompt, the Strands agent runs an iterative, tool-driven process that extracts, generates, validates, converts, publishes, and ingests artifacts. The walkthrough reports that this iterative approach yields much better correctness than single-shot calls. Those reliability figures are vendor-reported, and the public notes do not include the test methodology, so treat the numbers as indicative rather than independently verified.

Iteration helps because validators like Mermaid syntax checks, targeted tooling, and retries cut down on hallucinations and formatting errors that a one-off prompt often produces.

Scale, costs, and the numbers to watch

Case study highlights and reported figures:

  • Production scale shown: operating across 20 repositories and generating over 140 diagrams weekly with minimal manual overhead (reported by the case study).
  • Token counts reported for a medium-sized repository (~1, 500 files): ~29, 000 input tokens and ~10, 000 output tokens per generation. Token totals depend on tokenizer and exact prompt/chunking, confirm which tokenizer was used when you reproduce these numbers.
  • Per-generation model-cost figures appear in the walkthrough as both “Approx. $0.24” and later “~$0.28.” That internal inconsistency suggests a range of roughly $0.24, $0.28 per generation; request the original cost workbook to reconcile the discrepancy for your own budgeting.
  • AWS service examples in the walkthrough: CodePipeline ≈ $1.00 per active pipeline/month (first pipeline free), CodeBuild ≈ $0.005 per build minute × 5 minutes = $0.025 per execution, and S3 storage for documentation artifacts is noted as negligible (typically under 10 MB).
  • Weekly cost projections in the walkthrough (model + pipeline): 5 repositories ≈ $1.40/week → $5.60/month; 20 repositories ≈ $5.60/week → $22.40/month; 100 repositories ≈ $28.00/week → $112.00/month.
  • Operational impact metrics reported from six months of telemetry: delivery timelines compressed from 10 days to 3 days, message throughput doubled, mean time to recovery (MTTR) reduced by 20%, production incidents decreased by 30%, audit preparation reduced from two weeks to two days, developer onboarding accelerated from 4 weeks to 1 week, and documentation time per repository dropped from 2-4 hours to ~5 minutes. These are case-study claims, and the public notes do not include measurement methodology or raw telemetry.

Action: treat the impact numbers as promising vendor-reported outcomes and ask deployment owners for the measurement details before using them to set targets for your organization.

Design trade-offs and limits you must test

  • S3 as a vector store. The walkthrough uses S3 for storing embeddings and vectors as part of the Bedrock Knowledge Base pipeline. That reduces architectural complexity and cost, but you should validate query latency, retrieval accuracy, and concurrency for your workload against a purpose-built vector DB. The walkthrough does not specify the on-disk format or ANN index, so validate performance with realistic queries (latency and recall) before committing.
  • Language and analysis limits. Examples focus on .NET. Static analysis can miss dynamic behaviors (reflection, runtime-generated code) and cross-repo links, and polyglot stacks require language-specific parsers or language-server integrations to approach the same fidelity.
  • Security, data residency, and governance. The walkthrough lists IAM roles and region guidance (us-east-1) but omits end-to-end governance detail. For regulated environments, you will need VPC/PrivateLink, customer-managed keys (CMEK), pinned model versions, prompt/response logging with tamper-evident storage, and approval gates before diagrams are published.
  • Agentic failure modes. Expect mis-inferred relationships, missed cross-repo dependencies, or Mermaid formatting edge cases. Validators reduce but do not eliminate these errors, so build a small QA loop where architects review diffs for critical diagrams.
  • Cost sensitivity. Token totals vary with chunking, overlap, and prompt size. The walkthrough recommends hierarchical chunking (1, 500-token parent chunks and 300-token child chunks with overlapTokens: 60). Model choice and run frequency (per-commit vs scheduled) will drive costs.

Security & governance checklist (practical controls)

  • Pin model versions and record the exact model ARN used for each ingestion/generation run.
  • Enable prompt and response logging; retain logs in a tamper-evident store for audit evidence.
  • Use VPC endpoints / PrivateLink for Bedrock and S3 access where supported to avoid public egress.
  • Encrypt artifacts and embeddings at rest with customer-managed keys (CMEK) and require TLS in transit.
  • Add a diff-based approval step for diagrams used in compliance evidence (manual sign-off or automated rule gates).
  • Define retention policies for embeddings, prompts, and generated artifacts consistent with your data-residency and regulator requirements.

Practical starter plan (30-90 day pilot)

  • Select 5-10 repositories that cover different patterns (messaging-heavy service, infra component, shared library).
  • Use the walkthrough’s embedding model recommendation (Amazon Titan Text Embeddings v2) in the suggested region (us-east-1) and the hierarchical chunking settings as a starting point; confirm tokenization behavior for your codebase.
  • Pin models, enable full logging, and add a lightweight manual review step before diagrams are published to any compliance-facing location.
  • Measure: diagrams generated per run, time-to-first-diagram after commit, Mermaid validation-failure rate, and number of developer corrections. Use these metrics to iterate validators and parsers.
  • Run a load test of your retrieval queries against the KB to measure query latency and relevance under expected concurrency.

Open items to confirm with the authors / deployment owners

  • Conflicting production-date references: the walkthrough contains both “running in production since December 2025” and “running in production since Q1 2026.” Clarify which is correct or whether these refer to different rollouts.
  • Per-generation cost inconsistency: the document lists both “Approx. $0.24” and “~$0.28” per generation. Request the cost workbook that breaks down model calls, token counts, and pricing.
  • The “95% reliability vs 65%” claim is reported without methodology. Ask for the test plan, dataset, and definition of “reliability” used to produce those numbers.
  • Details of how embeddings are stored and served from S3 (format, indexing strategy, and retrieval SLAs) and whether Bedrock Knowledge Bases officially support S3-backed vectors at scale.
  • Security architecture used by the financial customer: PrivateLink/VPC setup, CMEK usage, retention/erasure policies for embeddings and prompts, and whether human sign-off gates were used for audit artifacts.

When this pattern is a good fit, and when it’s not

Good fit:

  • Microservice landscapes with frequent change where up-to-date diagrams matter for runbooks, audits, and onboarding.
  • Teams that prefer text-first, versionable diagrams (Mermaid) and want CI/CD-driven documentation updates.
  • Organizations willing to add lightweight approvals and governance controls for regulated artifacts.

Poor fit:

  • Binary-only repositories, heavily obfuscated code, or codebases where static analysis offers poor visibility into runtime architecture.
  • Environments that cannot meet data residency or model governance requirements unless the deployment can satisfy those controls.
  • Very large mono-repos with unpredictable token growth or high-frequency commits without a staged generation strategy, where model and infra costs can grow quickly.

Authors and provenance

The walkthrough and sample deployment were authored by Göksel Sarikaya, Abhijit Gautam, and Richard Merritt at AWS. The case study material and deployment examples are drawn from that walkthrough and a production deployment with a global interdealer broker cited in the documentation.

Key takeaways, questions you’d ask, answered

  • Can this pipeline keep diagrams current automatically?

    The CI/CD flow in the walkthrough triggers diagram regeneration on commits: yes, artifacts are regenerated and re-ingested into the Knowledge Base each pipeline run, keeping diagrams in sync with code commits (as reported in the case study).

  • What does it cost to run per repository?

    The walkthrough gives token estimates (~29, 000 input / ~10, 000 output for a ~1, 500-file repo) and reports per-generation model-costs as approximately $0.24 and, in another place, ~$0.28. Expect a range (~$0.24, $0.28) per generation and verify with the authors’ cost workbook for an exact figure tailored to your model choices and run frequency.

  • How reliable is the agent compared to a single-shot prompt?

    The case study reports a large improvement for the iterative agentic workflow (95% vs 65%), but the public notes do not disclose the measurement method. Treat this as vendor-reported telemetry indicating meaningful gains from validation and self-correction rather than an independently validated benchmark.

  • Is S3 a safe choice for vector storage?

    The walkthrough uses S3 as the vector store backend integrated with Bedrock Knowledge Bases. That simplifies operations, but teams should validate query latency, recall, and metadata-filtering needs against specialized vector DBs before adopting S3 for large-scale retrieval workloads.

  • What should a pilot look like?

    Start with 5-10 diverse repositories. Pin embedding and LLM models, enable full logging, add a manual review step for compliance artifacts, and measure correction rates and retrieval latency to iterate validators and parsers.

The pattern is pragmatic. Programmatic diagrams plus semantic indexing accelerate onboarding, support audits, and cut surprises during incidents. But confirm cost details, production dates, and reliability methodology with the walkthrough authors, and implement the security and governance controls described above before rolling this out in a regulated environment.

0