Modernizr Workshop

content/modernizr/00-preparation/index.en.md

@@ -0,0 +1,101 @@
+---
+title: "Environment Setup"
+date: 2025-09-01T09:53:04-05:00
+weight: 30
+chapter: true
+---
+
+## Development Environment Setup
+
+Before beginning the modernization process, you need to configure your development environment. You'll be working with Visual Studio Code Web running on a pre-configured EC2 instance that includes all necessary AWS permissions and tooling for this workshop. This cloud-based development environment provides immediate access to AWS services and the specialized MCP servers required for the modernization workflow, eliminating the need for local environment configuration.
+
+## Step 1: Accessing Your Development Environment
+
+Navigate to the workshop studio page and access the "Outputs" tab to retrieve your environment credentials:
+
+![Workshop studio tab](/static/images/modernizr/0/setup-01.png)
+
+Locate these two important values:
+- **VSCodeServerPassword** - Authentication credential for your VS Code instance
+- **VSCodeServerURLModernizr** - Direct endpoint to your cloud-based IDE
+
+Your values are unique to you and will differ from the above example.
+
+Click the `VSCodeServerURLModernizr` to launch your development environment. Enter the password when prompted and allow approximately 60 seconds for the environment to initialize. Any startup notifications can be safely dismissed.
+
+## Step 2: Configuring the Cline AI Agent
+
+Your workspace includes **Cline**, an autonomous AI coding agent that will assist with the modernization process. Cline provides intelligent code analysis, generation, and refactoring capabilities throughout this workshop.
+
+Access the [Cline](https://cline.bot/) extension through the VS Code interface:
+
+![Cline plugin](/static/images/modernizr/0/setup-02.png)
+
+## Step 3: Establishing Bedrock Integration
+
+Configure Cline to use Amazon Bedrock as its foundation model provider. Select "Use your own API Key" and choose "Amazon Bedrock" from the dropdown:
+
+![Cline plugin API config](/static/images/modernizr/0/setup-03.png)
+
+Apply the following configuration parameters:
+- **Authentication**: AWS Profile
+- **Profile**: empty (default)
+- **Region**: us-west-2
+- **Cross region inference**: enabled
+
+Confirm the settings and initialize the connection:
+
+![Cline plugin config](/static/images/modernizr/0/setup-04.png)
+
+
+::alert[You are working in a lab environment, the foundational models have configured rate limiting, it is highly likely during the workshop you will get throttled and you will have to retry the operations. You have 4 request per minute using Claude 4 and 6 request per minute using Claude 3.7.]{type="info"}
+
+
+## Step 4: Validating the Integration
+
+Verify the Bedrock connection is functioning correctly by sending the below test prompt to Cline. If you are throttled, press "proceed anyway" to retry the request.
+
+```terminal
+Hello and Welcome to this modernization project, can you confirm you can read and list all the files in the workspace?
+```
+
+![Cline plugin testing](/static/images/modernizr/0/setup-05.png)
+
+This workshop provides access to two foundation models: `claude-sonnet-4` (latest generation with enhanced reasoning capabilities) and `claude-sonnet-3.7` (previous generation with proven reliability).
+
+![Cline plugin response](/static/images/modernizr/0/setup-06.png) ![Cline plugin result](/static/images/modernizr/0/setup-07.png)
+
+## Step 5: Configuring Auto-Approval Settings
+
+Optimize Cline's efficiency by enabling automatic permissions for routine operations. Access the auto-approve settings via the `^` icon in the bottom-right corner of the Cline interface.
+
+Enable the following capabilities:
+- **Read all files** - Full workspace file access
+- **Use MCP servers** - Integration with specialized AI tools
+- **Edit project files** - Code modification permissions
+
+Increase the **Max requests** parameter from 20 to 40 to accommodate complex multi-step operations without interruption.
+
+![Cline plugin auto-approve settings](/static/images/modernizr/0/setup-08.png)
+
+## Step 6: Verifying MCP Server Status
+
+Access the MCP server management interface (stacked server icon) to confirm all specialized AI tools are operational. You should observe 3 active servers with green status indicators, confirming proper connectivity.
+
+![Cline plugin auto-approve settings](/static/images/modernizr/0/setup-09.png)
+
+## Step 7: MCP Integration Verification
+
+Test the MCP server functionality by querying existing DynamoDB resources:
+
+```shell
+Please show me the DynamoDB tables that I have in this region
+```
+
+![Task MCP Server](/static/images/modernizr/0/setup-10.png)
+
+## Environment Ready
+
+Your development environment is now fully configured with AI-assisted tooling. The integration of VS Code Web, Cline, Bedrock foundation models, and specialized MCP servers provides a comprehensive platform for the database modernization workflow.
+
+Proceed to the next module to begin the systematic analysis of your legacy application.

content/modernizr/01-modernization/index.en.md

@@ -0,0 +1,116 @@
+---
+title: "Database Modernizr Workflow"
+date: 2025-09-01T10:41:04-05:00
+weight: 30
+chapter: true
+---
+
+## Application Analysis and Baseline Establishment
+
+Before beginning the modernization process, you must thoroughly understand the existing system architecture. This involves analyzing the current MySQL-based e-commerce application to identify all data access patterns, performance characteristics, and system dependencies.
+
+Begin by reviewing the application documentation in the `README.md` file, which provides an overview of the system architecture and functionality.
+
+::alert[You don't have to follow the `README.md` instructions as your environment is already pre-configured for you. ]{type="info"}
+
+![README](/static/images/modernizr/1/workflow-01.png)
+
+## Starting the Application Services
+
+The e-commerce application follows a standard three-tier architecture:
+1. **Backend Service** - Express.js API server handling business logic and database interactions
+2. **Frontend Application** - React-based user interface for customer interactions
+3. **MySQL Database** - Relational database storing all application data
+
+While your application environment is already preconfigured, you'll still need to start both the backend and frontend services to establish a baseline for analysis.
+
+### Initializing the Backend Service
+
+The backend API server manages all client requests and database transactions. Navigate to the `/backend` directory and open an integrated terminal (right-click > "Open in Integrated Terminal"). Grant any requested permissions when prompted.
+
+![menu](/static/images/modernizr/1/workflow-02.png)
+
+Build and start the backend service using these commands:
+
+```shell
+npm run build
+npm run start
+```
+
+Monitor the startup sequence output. A successful initialization will display output similar to:
+
+```console
+👤 DatabaseFactory.createUserRepository called
+🔧 DynamoDBClientManager.getClient() called
+👤 Creating UserDualWriteWrapper
+🔐 AuthService repositories created
+🛍️ ShoppingCartService constructor called
+🛍️ ShoppingCartService repositories created
+🛍️ ShoppingCartService constructor called
+🛍️ ShoppingCartService repositories created
+Starting server with enhanced error handling...
+✅ Environment variables validated successfully
+✅ Database abstraction layer initialized with mysql configuration
+Registering routes...
+All routes registered.
+Server setup complete with comprehensive error handling
+📝 Using MySQL-only mode (Phase 1)
+🚀 Server is running on port 8100
+📊 Health check: http://localhost:8100/api/health
+🔧 Performance: http://localhost:8100/api/performance
+📈 Metrics: http://localhost:8100/api/metrics
+```
+
+**Important:** Keep this terminal window open! If you close it, the backend service will stop working, and our application won't function properly.
+
+### Launching the Frontend Application
+
+Initialize the React frontend application by opening a terminal in the `/frontend` directory and executing:
+
+```shell
+npm run serve:prod
+```
+
+Allow several minutes for the build process to complete. Dismiss any popup notifications that may appear during startup.
+
+## Application Verification and Analysis
+
+With both services running, you can now interact with the complete application stack to understand its current behavior and performance characteristics.
+
+### Backend Health Check
+
+Verify the API server is responding correctly by accessing the health endpoint:
+
+1. Copy your VS Code environment URL
+2. Open a new browser tab
+3. Navigate to `[your-url]/api/health`
+
+This endpoint should return status information confirming the backend is operational:
+
+![Backend](/static/images/modernizr/1/workflow-03.png)
+
+Monitor your backend terminal for request logging, which demonstrates the API request flow.
+
+### Frontend Application Access
+
+Access the e-commerce frontend by navigating to `[your-url]/store/`:
+
+![Store](/static/images/modernizr/1/workflow-04.png)
+
+## System Interaction Analysis
+
+Explore the application functionality to understand the data access patterns that will need to be modernized:
+
+**User Registration:** Create a new user account to observe authentication workflows
+
+**Admin Access:** Use the administrative account (username: `admin`, password: `0137183966133de0ace3d7e65e025d12`) to access extended functionality
+
+**E-commerce Operations:** Navigate through product browsing, cart management, and checkout processes. We have two simulated payment methods, paypal and credit card, both will auto-approve any order!
+
+Pay close attention to the backend terminal output as you interact with the application. Each user action generates specific database queries that represent the access patterns you'll need to replicate in your DynamoDB implementation.
+
+## Baseline Understanding
+
+This exploration phase establishes your baseline understanding of the current system architecture. Each user interaction demonstrates how the Express.js backend translates HTTP requests into MySQL queries, processes the results, and returns formatted responses to the React frontend.
+
+This request-response cycle represents the core functionality that must be preserved during the database modernization process, ensuring zero functional regression while achieving improved performance and scalability through DynamoDB.

content/modernizr/01-modernization/workflow-00.en.md

@@ -0,0 +1,61 @@
+---
+title: "1.1 The workflow"
+menuTitle: "The workflow"
+date: 2025-09-01T10:42:04-05:00
+weight: 31
+chapter: false
+---
+
+## Your 7-Step Journey to Database Modernization
+
+Think of database modernization like renovating a house while people are still living in it. You can't just tear everything down and start over — you need a careful, step-by-step plan that keeps everything working while you upgrade piece by piece. That's exactly what our modernization workflow does!
+
+Our process consists of seven carefully designed stages, each one building on the previous step. It's like following a recipe — each ingredient needs to be added at the right time and in the right order to get the perfect result.
+
+![Modernization workflow](/static/images/modernizr/1/workflow-base-01.png)
+
+## Stage 1: Understanding What You Have — Database Detective Work
+
+The first stage is like being a detective investigating the current system. We need to understand everything about how the existing MySQL database works before we can improve it. This involves connecting to the database, examining what predicates are used in queries and what data is returned, how fast different operations run, looking at the structure of all the tables, and studying the application code to understand exactly how data flows through the system.
+
+Think of it like doing a walkthrough with a designer before your remodel. They need to understand your taste and how you use your space to fully capture the requirements for the project. We use a specialized AI tool (the MySQL MCP server) to help us gather all this information systematically.
+
+## Stage 2: Designing the New Blueprint — Creating Your DynamoDB Model
+
+This is where the real design work happens! Using all the information we gathered in Stage 1, we create a completely new data model designed specifically for DynamoDB. This stage is highly interactive — you'll work closely with the AI to make important decisions about how to structure your data.
+
+It's like working with an architect to design your dream house renovation. The AI provides technical expertise and suggestions, but you need to guide the process and make the final decisions about what works best for your specific needs. This collaboration ensures the new design fits your application's requirements.
+
+## Stage 3: Building the Bridge — Creating a Database Abstraction Layer
+
+Now we create a special "bridge" layer in your application code that can talk to both the old MySQL database and the new DynamoDB system at the same time. This follows AWS best practices and ensures you can switch between systems safely without breaking anything.
+
+Think of this like rennovating the guest room before you rennovate the primary bedroom — you'll always have somewhere to sleep. Similarly with a database abstraction layer. everything continues to work normally while you prepare for the upgrade.
+
+## Stage 4: Testing the Connection — Validating DynamoDB Integration
+
+In this stage, we set up a local version of DynamoDB and test our bridge layer to make sure everything works correctly. It's like the city inspector making sure your renovated house systems are up to code before you complete the project.
+
+We validate that all the connections work properly and that data flows correctly through both systems. This gives us confidence that everything is ready for the next phase.
+
+## Stage 5: Running Both Systems — Application Refactoring and Dual Writes
+
+This is the most complex stage, where your application learns to write data to both databases simultaneously. We use a method called "test-driven development," which means we write tests first to ensure everything works correctly, then modify the code to pass those tests.
+
+During this stage, we also create a special admin control panel that lets you monitor and control the modernization process. You can watch both the old and new systems running side by side and manage the transition safely.
+
+## Stage 6: Moving to the Cloud — Deploying the cloud Infrastructure
+
+Once everything is tested and working locally, we deploy your new DynamoDB tables to the actual AWS cloud environment. You've finally got your Certificate of Occupancy!
+
+The deployment process ensures your cloud infrastructure is set up correctly and ready to handle real traffic.
+
+## Stage 7: The Great Migration — Moving Your Data
+
+The final stage is where we actually move all your existing data from MySQL to DynamoDB. This is carefully controlled and monitored — you decide when you're ready to start using dual writes, and then we gradually migrate all your historical data.
+
+We use specialized data processing tools (like the AWS Glue MCP Server) to handle this migration safely and efficiently. It's like having professional movers who ensure all your belongings get to the new house safely and end up in exactly the right places.
+
+## Why This Approach Works
+
+This seven-stage approach ensures that at no point during the modernization process is your application broken or unavailable. Users continue shopping, orders continue processing, and everything works smoothly while we upgrade the foundation underneath. It's a proven method that minimizes risk while maximizing the benefits of modern database technology.

content/modernizr/01-modernization/workflow-01.en.md

@@ -0,0 +1,35 @@
+---
+title: "1.2 The Anatomy of a prompt"
+menuTitle: "Anatomy of a prompt"
+date: 2025-09-01T10:43:04-05:00
+weight: 32
+chapter: false
+---
+
+## 📚 Prompt Engineering Architecture
+
+The `/prompts` directory implements a structured approach to AI-driven development through organized subfolders that correspond to each stage of the modernization workflow. Each subfolder contains three components: Requirements, Design, and Tasks documents. This architectural pattern creates a comprehensive framework that systematically guides the entire modernization process from initial analysis through final implementation.
+
+![Prompts](/static/images/modernizr/1/workflow-prompt-01.png)
+
+### Requirements Documentation — Defining Objectives and Success Criteria
+
+The Requirements Document establishes the foundational context by articulating the business objectives and technical constraints that drive the modernization initiative. This document defines explicit acceptance criteria and success metrics, creating what software engineers refer to as the "definition of done." By providing comprehensive context about the problem domain, the requirements document enables the LLM to understand not just what needs to be built, but why it needs to be built and how to validate that the implementation meets the specified goals.
+
+### Design Documentation — Technical Architecture and Implementation Strategy  
+
+The Design Document serves as the technical specification that translates high-level requirements into concrete architectural decisions and implementation strategies. This document defines the specific methodologies, data structures, and system workflows that will be employed throughout the modernization process. It includes detailed implementation guidelines, architectural patterns, and design rationale that provide the LLM with a comprehensive technical blueprint for executing the modernization according to established software engineering principles.
+
+### Task Documentation — Executable Implementation Steps
+
+The Tasks Document functions as the bridge between abstract architectural design and concrete implementation by decomposing design specifications into discrete, executable development tasks. This document provides sequenced instructions that reference specific files, tools, and expected deliverables, ensuring the LLM receives actionable directives rather than abstract concepts. The task breakdown transforms architectural decisions into manageable development units that can be systematically executed and validated.
+
+### The Importance of Structured Prompt Engineering
+
+This three-tier documentation approach addresses a fundamental challenge in AI-assisted development: the complexity management problem. When an LLM encounters a sophisticated design document without accompanying task structure, it faces the same challenges that human developers experience when given high-level specifications without clear implementation guidance. The system may attempt to implement multiple components simultaneously, leading to incomplete or inconsistent results, or it may struggle to determine the appropriate sequencing of development activities.
+
+The structured approach provides several advantages. The LLM receives explicit guidance on which specialized tools and MCP servers to utilize for each development phase. Dependencies between implementation tasks become clearly defined, preventing issues that arise from incorrect execution ordering. The system understands exactly what deliverables should be produced at each stage, enabling proper validation and quality assurance throughout the process.
+
+To conceptualize this framework using a navigation analogy: the Requirements document defines the destination and the reasons for traveling there, the Design document provides the comprehensive route map showing all available paths and optimal strategies, and the Tasks document functions as turn-by-turn GPS navigation that guides execution through each specific step of the journey. This structured approach transforms complex modernization challenges into systematic, manageable processes that can be executed reliably through AI-assisted development workflows.
+
+![Tasks](/static/images/modernizr/1/workflow-prompt-02.png)