A presentation at Open Source North in in St Paul, MN, USA by Jenna Pederson
A Conversation with your Architecture Kevin Hakanson & Jenna Pederson #OSN2025
What is your experience with diagrams? #OSN2025
Who are we? Kevin Hakanson ● ● ● ● ● Jenna Pederson Solutions Architect at AWS* 30+ years as developer and architect UST alumni (MS in Software Engineering) Diagram “snob” Humorous* ● ● ● ●
Diagrams are hard Reading, analyzing, creating, maintaining, making informed decisions from, and communicating through diagrams #OSN2025
Let’s play a game We’re going to show a diagram on the next slide and we need you to analyze it. #OSN2025
We also asked Claude to analyze the diagram It took 9 seconds. #OSN2025
The diagram illustrates a serverless architecture using AWS services. Here are the key components and services shown: 1. 2. 3. 4. 5. User: Represented by a simple icon, indicating the starting point of the interaction. Amazon API Gateway: This is the entry point for the user’s requests. It manages and routes API calls to the appropriate backend services. AWS Lambda: Shown as the next step after API Gateway. Lambda is a serverless compute service that runs code in response to events and automatically manages the underlying compute resources. Amazon DynamoDB: Depicted with a “read” arrow from Lambda. DynamoDB is a fully managed NoSQL database service that provides fast and predictable performance with seamless scalability. Amazon Simple Storage Service (Amazon S3): Shown with a “write” arrow from Lambda. S3 is an object storage service offering industry-leading scalability, data availability, security, and performance. The flow of the architecture appears to be: 1. 2. 3. 4. The user interacts with the API Gateway. API Gateway triggers a Lambda function. The Lambda function reads data from DynamoDB. The Lambda function then writes data to Amazon S3. This serverless architecture allows for building scalable, event-driven applications without managing servers. It leverages AWS’s managed services to handle infrastructure concerns, allowing developers to focus on writing code and business logic.
● Implementation technologies ● ● ● ● ● ● ● #OSN2025 Large Language Models (LLMs) Prompts (user and system) Multi-modal models for image understanding Retrieval-Augmented Generation (RAG) Knowledge Base integration Vector databases for semantic search MCPs and tools Agents and orchestration
Amazon Nova Canvas prompt: “A software project team is collaborating around a whiteboard. A developer is drawing a cloud architecture on the whiteboard. A security #OSN2025 engineer is holding a clipboard with a checklist of items. A project manger is on her laptop, working on a spreadsheet.”
USE CASE In the past: Onboarding & understanding New developer joining a complex project #OSN2025 ● ● ● ● ● Meetings, trainings Reading outdated docs and diagrams Reverse engineering code and infrastructure Sifting through git commits Finding and waiting for time from expert
What questions are we asking? ● ● ● ● ● ● How are we thinking about this problem? Why did we design it this way? What are some of the technical challenges that we had to address with this next generation serverless architecture? Why are namespaces so important today? How does data flow for the write path? The query path? What is adaptive caching and how does it work? What are some of the access patterns for this type of workload? #OSN2025
USE CASE In the past: Evolving an architecture ● ● ● Building out a new feature, integrating a new service ● #OSN2025 Reality differs from documentation Find historical examples of similar solutions, in the code, in other systems we maintain, in the industry Match against internal standards and architectural decision records (ADRs) stored in the project, on a wiki, or on a post-it note Architecture reviews with internal “experts”
What questions are we asking? ● ● ● ● ● How did our last project solve this problem? We need to add a recommendation engine. Where should we integrate it? Should be roll our own or use a 3rd party service? How would the first option affect our database load? What happens if the database has increased latency or goes down completely? Does that mean we can’t take orders, too? #OSN2025
USE CASE In the past: Security analysis ● ● ● Incident response, third-party integration security review ● ● #OSN2025 Review a checklist Analyze diagrams for potential vulnerabilities and then go re-analyze the actual infra/code Highlight trust boundaries and data flows Evaluate against security best practices Run pen tests
What questions are we asking? ● ● ● ● After a breach, which other services and data could be compromised through this entry point? We’re adding Stripe payments - what are the security implications? What are all the trust boundaries that change when we move to AWS? Who are our vendors and do we need to audit any licensing agreements? #OSN2025
State of AI & diagrams today #OSN2025 Today, we’re seeing: ● ● ● ● Text-to-diagram generation Diagram-to-text description Basic analysis capabilities Starting to see this integrated into developer tools like IDEs and coding assistants
“describe the key components and services in the diagram” This diagram illustrates a typical AWS VPC (Virtual Private Cloud) network architecture. Here are the key components and services depicted: 1. 2. 3. 4. 5. 6. 7. 8. VPC: The main container (10.0.0.0/16) that encompasses the entire private network infrastructure. Internet Gateway (IGW): Represented by the cloud icon at the top, allowing communication between the VPC and the internet. Subnets: Three distinct subnets are shown within the VPC: ○ Firewall subnet (10.0.4.0/28) ○ Customer subnet (10.0.2.0/24) ○ Another subnet labeled as “Firewall subnet” (vpc-4114) Route Tables: Depicted as tables showing destinations and targets for network traffic: ○ Internet Gateway route table ○ Firewall subnet route table ○ Customer subnet route table Availability Zone: The entire VPC setup is shown within a single Availability Zone (AZ1). Region: The VPC is contained within an AWS Region, as indicated by the “Region” label at the bottom. Security: The presence of a firewall subnet suggests security measures are in place to control traffic flow. Connectivity: Arrows between components indicate network connections and potential traffic flow. This architecture demonstrates a segmented network design with controlled internet access, which is typical for enhancing security and managing network traffic in cloud environments. The use of separate subnets for different purposes (firewall, customer) allows for more granular control over network access and security policies.
What do you think about this diagram? An architecture follows a serverless approach, where the AWS Lambda function handles the application logic, and the Amazon API Gateway acts as the entry point for user requests. The Amazon DynamoDB database stores structured data, while the Amazon S3 service stores unstructured data or files. Create a DrawIO formatted XML that demonstrates this architecture.
Context is key System Prompt Formatting Rules Golden Examples User Prompt
Amazon Q Developer
Amazon Q CLI “chat” Just User Prompt User Prompt with context added to: .amazonq/rules/drawio-standards.md #OSN2025
Vibe Architecting create an AWS CDK project with the following components: 1) a API Gateway HTTP API targeting an ALB as the integration. 2) create a lambda custom authorizer for the HTTP API that adds data to the context. 3) have the integration from REST API to ALB add the context as a custom HTTP header. 4) create a new VPC for the ALB, and add a VPC Link to the HTTP API. 5) add another lambda function as the target for the ALB and print out the custom header. 6) recommend any security group logic to only allow HTTP traffic from the API Gateway HTTP API
What is your experience using AI tools with diagrams? #OSN2025
But this is not perfect Benefits ● ● ● Limitations Time savings in creating initial diagrams Consistent visual representation Basic analysis capabilities ● ● ● #OSN2025 Limited understanding of your company’s context - business domain, patterns, ADRs, standards, rules Still requires human validation Not deeply integrated with other artifacts
This workflow is changing #OSN2025
Context is key #OSN2025
SOLUTION Architectural understanding comes from multiple sources: Beyond diagrams Integrated knowledge ● ● ● ● ● ● ● #OSN2025 Diagram images (visual structure) or file formats (text / as-code) Source code and comments (implementation) Infrastructure as Code (deployment) ADRs and design documents (decisions) Security policies (constraints) Change history (evolution) Usage / Observability (metrics)
Kevin’s OSN 2023 presentation The future is now
Kevin’s recent Q Developer chat can you review the changes since git commit 6a7ebc6adaa1b5fc63b31e7ef0ae10b32a2239e0 and provide a summary? if a similar change was made to multiple files, just give me a count of the number of files and short description. If a major change was made to a file, list out that file path and summary of the major change.
Whiteboard architecture of a content publishing system
“describe the data flow of this diagram based on the order of the numbered circles” 1. 2. 3. 4. 5. 6. Get Textbook: The process begins with the Editor creating or retrieving a textbook from the Shakespeare service, which is the editorial platform. Convert to PDF: The textbook is then sent to the Gutenberg service, which converts it into a PDF format. Save PDF to Library: The converted PDF is saved to the Alexandria service, which acts as the library for storing published textbooks. Index: The newly saved textbook in Alexandria is indexed, likely updating the NoSQL database to make the content searchable. Search: When a Customer initiates a search, their request is processed by the Search Microservice, which queries the NoSQL database to find relevant content. View: After finding the desired content, the Customer can view it through the Display Microservice. This microservice likely checks the SQL Entitlements database to ensure the customer has the right to access the content before displaying it.
Knowledge integration in action system prompt (text) user prompt (text) Claude 3.5 Sonnet diagram (image) tools vector database database
Diagrams-as-Code “There are benefits to using [diagrams as code] tools over the heavier alternatives, including easy version control and the ability to generate the DSLs from many sources.” Thoughtworks Technology Radar Blip (Oct 28, 2020) Mermaid is a JavaScript based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically. #OSN2025
“convert into a Mermaid formatted sequence diagram”
SOLUTION ● Multi-perspective visualization Different stakeholders need different views #OSN2025 ● ● ● ● ● Business: High-level capabilities Security: Trust boundaries Operations: Deployment topology Developers: Component interfaces Product: Processes UX: User journeys
C4 model for visualizing software architecture 1. 2. 3. 4. System context diagram Container diagram Component diagram Code diagram Structurizr builds upon “diagrams as code”, allowing you to create multiple software architecture diagrams from a single model. #OSN2025
SOLUTION ● Autonomous Agents To scale tasks #OSN2025 Deploy an agent or a team of agents to: ○ ○ ○ ○ Evaluate decisions Migrate a codebase when an SDK/API changes Respond to incidents and troubleshoot issues Evaluate which is the right chunking approach, embedding model, vector dimension, or search strategy based on usage patterns
Autonomous agent
● Practical takeaways ● ● ● ● ● #OSN2025 Know where your data is and what state it is in Know what good code/diagrams/results look right for you Know what you’re trying to accomplish Know the tools in your tool box and how to use them/what they are for Try things out Push past the hype
Please share your feedback Thank you! Any questions? /in/kevinhakanson /in/jennapederson https://pulse.aws/survey/ZQYU6TTY #OSN2025
Software and architecture diagrams are critical tools as they help developers and stakeholders understand complex systems. What if you could have a conversation with your diagrams? This session explores how generative AI can facilitate meaningful conversations with your architecture to gain deeper insights, make decisions, generate diagrams, and even generate infrastructure code. Leave with both a theoretical understanding and practical implementation guidance for using generative AI in architecture documentation and analysis.
for free. You
can too.