Forem: Stella Achar Oiro

Five Patterns for Building Self-Updating Documentation

Stella Achar Oiro — Mon, 12 Jan 2026 08:47:47 +0000

A practical guide for keeping technical documentation synchronized with production systems

Documentation drift is expensive. When your docs say one thing and your API does another, developers lose trust, support tickets pile up, and teams waste time investigating discrepancies. After working with multiple production systems, I've identified five patterns that significantly reduce documentation maintenance burden while improving accuracy.

These patterns work whether you're documenting REST APIs, GraphQL endpoints, or microservices architectures. They're particularly valuable for teams practicing continuous deployment where manual documentation updates can't keep pace with releases.

Pattern 1: Store Documentation Next to Infrastructure Code

The Traditional Approach:
Documentation lives in Confluence or a separate docs repository. Infrastructure code lives in Terraform files. They drift apart within weeks.

The Better Pattern:
Keep documentation in the same repository as your infrastructure code, versioned together.

/api-infrastructure
  /terraform
    - api-gateway.tf
    - lambda-functions.tf
    - dynamodb-tables.tf
  /docs
    - api-reference.md
    - authentication.md
    - rate-limits.md
  /openapi
    - spec.yaml

When someone updates API Gateway throttling settings, the documentation change happens in the same pull request. Reviewers catch inconsistencies before merge.

Implementation:
Add a documentation check to your PR template:

## Pull Request Checklist

- [ ] Code changes tested
- [ ] Infrastructure changes applied to staging
- [ ] Documentation updated to reflect changes
- [ ] OpenAPI spec regenerated if endpoints changed

Why It Works:
The person making infrastructure changes is best positioned to document them. They understand what changed and why. Keeping docs adjacent to code removes the friction of "I'll update the docs later."

Pattern 2: Generate Examples from Actual Infrastructure

The Problem:
Manually written examples become outdated. Your docs say "default timeout is 30 seconds" but you changed it to 60 seconds three months ago.

The Pattern:
Write scripts that query your infrastructure and generate documentation examples automatically.

#!/usr/bin/env python3
"""
Generate API documentation examples from deployed AWS resources
Run this in CI/CD after infrastructure deployment
"""

import boto3
import json
from datetime import datetime

def generate_api_gateway_docs():
    """Extract actual configuration from deployed API Gateway"""
    client = boto3.client('apigateway')

    # Get API Gateway details
    apis = client.get_rest_apis()

    for api in apis['items']:
        api_id = api['id']

        # Get actual throttle settings
        stages = client.get_stages(restApiId=api_id)

        for stage in stages['item']:
            throttle_settings = stage.get('throttleSettings', {})

            doc_content = f"""
## Rate Limits

Current production settings for {stage['stageName']}:

- **Burst Limit**: {throttle_settings.get('burstLimit', 'N/A')} requests
- **Rate Limit**: {throttle_settings.get('rateLimit', 'N/A')} requests per second

*Last updated: {datetime.now().strftime('%Y-%m-%d %H:%M UTC')}*
*Generated from deployed infrastructure*
            """

            # Write to docs file
            with open(f'docs/rate-limits-{stage["stageName"]}.md', 'w') as f:
                f.write(doc_content.strip())

if __name__ == '__main__':
    generate_api_gateway_docs()

Add to CI/CD:

# .github/workflows/update-docs.yml
name: Update Documentation

on:
  workflow_dispatch:
  schedule:
    - cron: '0 2 * * *'  # Daily at 2 AM

jobs:
  update-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v2
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-east-1

      - name: Generate documentation from infrastructure
        run: python scripts/generate-docs.py

      - name: Commit changes
        run: |
          git config user.name "Documentation Bot"
          git config user.email "bot@example.com"
          git add docs/
          git diff --quiet && git diff --staged --quiet || git commit -m "docs: update from deployed infrastructure"
          git push

Why It Works:
Your documentation reflects production reality because it's generated from production. Impossible for docs to drift when they're extracted from the source of truth.

Pattern 3: Validate Documentation in CI/CD

The Problem:
Someone updates an API endpoint but forgets to update the corresponding documentation. The discrepancy only surfaces when users complain.

The Pattern:
Add automated checks that fail your build when documentation is incomplete or incorrect.

// scripts/validate-docs.js
const fs = require('fs');
const path = require('path');

/**
 * Validate that all API endpoints have corresponding documentation
 */
function validateEndpointDocs() {
  const errors = [];

  // Read OpenAPI specification
  const specPath = path.join(__dirname, '../openapi/spec.yaml');
  const spec = require('js-yaml').load(fs.readFileSync(specPath, 'utf8'));

  // Extract all endpoint paths
  const endpoints = Object.keys(spec.paths || {});

  // Check each endpoint has documentation
  endpoints.forEach(endpoint => {
    const methods = Object.keys(spec.paths[endpoint]);

    methods.forEach(method => {
      const operation = spec.paths[endpoint][method];

      // Check for required documentation fields
      if (!operation.description || operation.description.length < 50) {
        errors.push(
          `${method.toUpperCase()} ${endpoint}: Missing or insufficient description`
        );
      }

      if (!operation.responses || Object.keys(operation.responses).length === 0) {
        errors.push(
          `${method.toUpperCase()} ${endpoint}: No response codes documented`
        );
      }

      // Check for example responses
      Object.entries(operation.responses).forEach(([code, response]) => {
        if (code === '200' && !response.content?.['application/json']?.example) {
          errors.push(
            `${method.toUpperCase()} ${endpoint}: Missing example for 200 response`
          );
        }
      });
    });
  });

  return errors;
}

// Run validation
const errors = validateEndpointDocs();

if (errors.length > 0) {
  console.error('Documentation validation failed:\n');
  errors.forEach(error => console.error(`${error}`));
  process.exit(1);
} else {
  console.log('All documentation checks passed');
  process.exit(0);
}

Add to your CI pipeline:

# In your .github/workflows/ci.yml
- name: Validate API documentation
  run: node scripts/validate-docs.js

Why It Works:
Broken builds force teams to fix documentation before deploying. Documentation becomes a first-class citizen alongside tests and code quality checks.

Pattern 4: Version Documentation with Your API

The Problem:
You release API v2 but documentation for v1 disappears. Users still on v1 have no reference.

The Pattern:
Maintain documentation versions that match your API versions.

/docs
  /v1
    - authentication.md
    - endpoints.md
    - changelog.md
  /v2
    - authentication.md
    - endpoints.md
    - changelog.md
  /v3
    - authentication.md
    - endpoints.md
    - changelog.md

Automate version detection:

# scripts/generate-versioned-docs.py
import os
import shutil
from pathlib import Path

def create_version_docs(api_version):
    """
    Create documentation for a specific API version
    """
    docs_dir = Path('docs')
    version_dir = docs_dir / api_version

    # Create version directory
    version_dir.mkdir(parents=True, exist_ok=True)

    # Copy template docs
    template_dir = docs_dir / 'templates'
    for template in template_dir.glob('*.md'):
        content = template.read_text()

        # Replace version placeholders
        content = content.replace('{{VERSION}}', api_version)
        content = content.replace('{{API_URL}}', f'https://api.example.com/{api_version}')

        # Write versioned doc
        (version_dir / template.name).write_text(content)

    print(f"Created documentation for {api_version}")

# Generate docs for all active versions
active_versions = ['v1', 'v2', 'v3']
for version in active_versions:
    create_version_docs(version)

Create a version selector in your docs:

<!-- Version selector for documentation site -->
<div class="version-selector">
  <label for="api-version">API Version:</label>
  <select id="api-version" onchange="switchVersion(this.value)">
    <option value="v3" selected>v3 (latest)</option>
    <option value="v2">v2 (supported)</option>
    <option value="v1">v1 (deprecated)</option>
  </select>
</div>

<script>
function switchVersion(version) {
  const currentPath = window.location.pathname;
  const newPath = currentPath.replace(/\/v\d+\//, `/${version}/`);
  window.location.href = newPath;
}
</script>

Why It Works:
Developers can reference documentation matching their deployed API version. No confusion about which features are available in which version.

Pattern 5: Test Your Documentation Examples

The Problem:
Code examples in documentation break but nobody notices until developers try them and fail.

The Pattern:
Extract code examples from documentation and run them as tests.

# tests/test_documentation_examples.py
import pytest
import requests
import re
from pathlib import Path

def extract_code_blocks(markdown_file):
    """Extract Python code blocks from markdown documentation"""
    content = Path(markdown_file).read_text()

    # Find all Python code blocks
    pattern = r'```

python\n(.*?)

```'
    code_blocks = re.findall(pattern, content, re.DOTALL)

    return code_blocks

def test_authentication_example():
    """Test that authentication example in docs actually works"""

    # Extract code from docs
    examples = extract_code_blocks('docs/authentication.md')

    # Run each example
    for example in examples:
        # Create isolated namespace
        namespace = {'requests': requests}

        try:
            exec(example, namespace)

            # Check that example made successful API call
            if 'response' in namespace:
                assert namespace['response'].status_code == 200, \
                    f"Example failed with status {namespace['response'].status_code}"

        except Exception as e:
            pytest.fail(f"Documentation example failed to execute: {str(e)}")

def test_rate_limit_values_match_infrastructure():
    """Verify rate limits in docs match deployed values"""

    # Parse rate limits from documentation
    docs_content = Path('docs/rate-limits.md').read_text()
    doc_rate_match = re.search(r'Rate Limit.*?(\d+)', docs_content)

    assert doc_rate_match, "Could not find rate limit in documentation"
    doc_rate = int(doc_rate_match.group(1))

    # Query actual API for rate limits
    response = requests.get('https://api.example.com/v1/limits')
    actual_rate = response.json()['rateLimit']

    assert doc_rate == actual_rate, \
        f"Documentation says {doc_rate} req/s but API reports {actual_rate} req/s"

Run tests in CI:

# .github/workflows/test-docs.yml
name: Test Documentation

on: [push, pull_request]

jobs:
  test-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: pip install pytest requests

      - name: Test documentation examples
        run: pytest tests/test_documentation_examples.py -v

Why It Works:
Broken examples fail CI before they reach users. Your documentation examples are guaranteed to work because they're tested continuously.

Putting It All Together

These five patterns create a documentation system that maintains itself:

Co-location ensures changes happen together
Generation eliminates manual updates for configuration details
Validation catches incomplete documentation before deployment
Versioning supports users across all API versions
Testing guarantees examples actually work

Implement them incrementally. Start with Pattern 1 (co-location) this week. Add Pattern 3 (validation) next sprint. Build toward a fully automated documentation system over time.

The goal isn't perfect documentation on day one. It's building systems that make accurate documentation the path of least resistance.

Stella Oiro is an AWS Community Builder who builds and documents cloud-native systems in production.

The Ultimate Guide to Linux Command Line for Cloud Engineers

Stella Achar Oiro — Thu, 13 Nov 2025 05:50:05 +0000

The terminal is your gateway to cloud infrastructure. Whether you're SSH'd into an EC2 instance, troubleshooting Lambda container environments, or configuring ECS tasks, you need to navigate Unix-like systems confidently. This guide covers the essential Linux command-line skills you'll use daily as a cloud engineer.

At the end of this article, you will have a working understanding of terminals, shells, file systems, permissions, and package management. You'll know how to navigate remote servers, troubleshoot issues, and automate workflows using command-line tools.

Prerequisites

Before you start, you need:

A Unix-like environment (Linux, macOS, or Windows with WSL)
Basic familiarity with text editors
An AWS account (optional, for cloud-specific examples)

Understanding Terminals and Shells

The words "terminal," "shell," and "command line" get thrown around interchangeably. Let me clarify what each term means and why the distinction matters.

What is a Terminal?

A terminal is a program that accepts text input and renders text output. Historically, terminals were physical devices—keyboards and monitors connected to mainframe computers. Today, you use terminal emulators like Ghostty, iTerm2, or the built-in Terminal on macOS.

When you open your terminal application, it displays a prompt where you can type commands. The terminal itself doesn't interpret those commands—it just handles the input and output.

What is a Shell?

A shell is the program that actually processes your commands. When you type echo "Hello World" and press Enter, the shell reads that text, evaluates it, executes it, and returns output. This cycle is called a REPL: Read, Evaluate, Print, Loop.

The two most common shells are:

bash (Bourne Again Shell) - Default on most Linux distributions
zsh (Z Shell) - Default on modern macOS

Both are powerful scripting languages that can handle variables, conditionals, loops, and functions. For this guide, all examples work in both bash and zsh.

Why This Matters for AWS

When you SSH into an EC2 instance, you're connecting to a shell session on that remote machine. When you configure Lambda container images, you're often writing shell scripts. When you troubleshoot ECS tasks, you're examining shell output logs.

Understanding the shell means understanding how your cloud infrastructure executes commands.

Let me show you what I mean. Open your terminal and run:

$ echo "Hello World"

The shell reads this command, identifies echo as a program, passes "Hello World" as an argument, and prints the result. Now try:

$ expr 123456 + 7890

Your output shows:

The shell can perform arithmetic, manipulate strings, and execute complex logic. This is why shell scripting is foundational for DevOps automation.

File System Navigation

Cloud servers are just Linux machines. You need to navigate their file systems to configure applications, examine logs, and troubleshoot issues.

Your Current Location

At any moment, your shell has a "working directory"—the folder you're currently in. Check it with:

$ pwd

This prints your working directory. On macOS, you might see:

/Users/cindy

On Linux:

/home/cindy

This is your home directory, where your personal files live.

File Paths

A file path is a text representation of a file's location in the directory tree. All absolute paths start from the root directory (/).

Your home directory on Linux might be /home/achar, which means:

Start at the root /
Enter the home directory
Enter the achar directory

Each directory is separated by a forward slash.

Listing Files

The ls command lists directory contents:

$ ls

You see files and directories in your current location. Add flags to customize the output:

$ ls -l

This shows a "long" format with permissions, owners, file sizes, and modification dates. Add the -a flag to show hidden files:

$ ls -la

Hidden files start with a dot (.). Configuration files like .bashrc or .zshrc are hidden by default.

Changing Directories

Navigate the file system with cd:

$ cd /var/log

This moves you to /var/log, where system logs are stored. Check your new location:

$ pwd

The output shows /var/log.

To go up one directory level, use the special alias ..:

$ cd ..

Now you're in /var. To return to your home directory from anywhere:

$ cd ~

The tilde (~) is an alias for your home directory.

Relative vs Absolute Paths

Absolute paths start with / and work from anywhere:

$ cd /var/log/nginx

Relative paths start from your current location:

$ cd nginx

This only works if a nginx directory exists in your current location.

AWS Context: EC2 Log Files

When you SSH into an EC2 instance running a web application, you often need to examine logs. Application logs typically live in:

/var/log - System and service logs
/var/log/nginx or /var/log/apache2 - Web server logs
/var/log/mysql - Database logs

To check your web server's error log:

$ cd /var/log/nginx
$ ls -l

You see files like access.log and error.log. This workflow is identical whether you're troubleshooting locally or on a remote server.

Working with Files

You need to read, create, modify, and delete files constantly. Let me show you the essential commands.

Reading File Contents

The cat command prints an entire file:

$ cat /etc/hosts

This displays your system's hostname mappings. For large files, cat is overwhelming because it dumps everything to your screen.

Reading Partial Contents

For large files, use head to see the first lines:

$ head -n 10 /var/log/syslog

This shows the first 10 lines. Similarly, tail shows the last lines:

$ tail -n 20 /var/log/syslog

The -n flag specifies the number of lines.

Following Log Files

When troubleshooting active applications, you want to see new log entries as they're written. Use tail -f:

$ tail -f /var/log/nginx/access.log

This continuously displays new lines as they're appended. Press Ctrl+C to stop.

Searching Within Files

The grep command searches for text patterns:

$ grep "error" /var/log/syslog

This prints every line containing "error". The search is case-sensitive by default. For case-insensitive search:

$ grep -i "error" /var/log/syslog

To search recursively through directories:

$ grep -r "database connection" /var/log

This searches all files in /var/log and its subdirectories.

Finding Files

The find command locates files by name or pattern:

$ find /var/log -name "*.log"

This lists all files ending in .log within /var/log. The asterisk (*) is a wildcard matching any characters.

To find files modified in the last 24 hours:

$ find /var/log -mtime -1

Creating Files

The touch command creates empty files:

$ touch test.txt

If test.txt already exists, touch updates its modification timestamp without changing its contents.

Creating Directories

Make new directories with mkdir:

$ mkdir project

To create nested directories in one command:

$ mkdir -p project/src/components

The -p flag creates parent directories as needed.

Moving and Renaming

The mv command both moves and renames files:

$ mv old-name.txt new-name.txt

To move a file to another directory:

$ mv config.json /etc/myapp/

Copying Files

The cp command copies files:

$ cp source.txt destination.txt

To copy directories recursively:

$ cp -r source-dir destination-dir

Deleting Files

The rm command removes files:

$ rm unnecessary-file.txt

To remove directories and their contents:

$ rm -r old-directory

Warning: There's no recycle bin on the command line. Deleted files are gone permanently.

AWS Context: S3 and Local Files

When you work with S3, you frequently sync files between your EC2 instance and S3 buckets. The AWS CLI uses familiar commands:

$ aws s3 cp local-file.json s3://my-bucket/data/

This copies a local file to S3. To download:

$ aws s3 cp s3://my-bucket/data/config.json ./

The patterns mirror standard file operations. Understanding local file manipulation makes cloud storage operations intuitive.

Permissions and Users

Unix-like systems have robust permission systems. This is critical for HIPAA-compliant infrastructure where you need to restrict access to protected health information (PHI).

Understanding Permission Strings

When you run ls -l, you see permission strings like:

-rw-r--r--  1 achar staff  1234 Nov 13 09:30 file.txt
drwxr-xr-x  5 achar staff   160 Nov 13 09:31 directory

Let me break down the first string: -rw-r--r--

The first character indicates the type:

- = regular file
d = directory

The remaining nine characters form three groups of three:

Owner permissions (rw-): The user who owns the file
Group permissions (r--): Users in the file's group
Other permissions (r--): Everyone else

Each group has three permissions:

r = read
w = write
x = execute

A dash (-) means the permission is denied.

So -rw-r--r-- means:

Owner can read and write
Group members can read
Others can read
Nobody can execute

Checking Your User

Your username:

$ whoami

To see which groups you belong to:

$ groups

Changing Permissions

The chmod command modifies permissions. The syntax uses:

u = user (owner)
g = group
o = others
a = all

To grant execute permission to the owner:

$ chmod u+x script.sh

To remove write permission from others:

$ chmod o-w sensitive-data.txt

To set permissions for everyone:

$ chmod a+r public-file.txt

You can combine changes:

$ chmod u=rwx,g=rx,o=r program.sh

This sets owner to read/write/execute, group to read/execute, and others to read-only.

The Execute Permission

For files, execute permission allows running the file as a program. For directories, it allows entering the directory.

When you download a script, you often need to make it executable:

$ chmod +x deploy.sh
$ ./deploy.sh

The ./ prefix explicitly runs the script in your current directory.

Changing Ownership

The chown command changes file ownership. This requires elevated privileges:

$ sudo chown nginx:nginx /var/www/html/index.html

This changes the owner to nginx and the group to nginx. The syntax is user:group.

The Root User

The root user is the superuser with unrestricted access to everything. Running commands as root is powerful and dangerous.

The sudo command lets you execute single commands as root:

$ sudo systemctl restart nginx

You'll be prompted for your password. After entering it correctly, the command runs with root privileges.

Healthcare Context: HIPAA Compliance

When building HIPAA-compliant systems, file permissions protect PHI. Database credentials, encryption keys, and patient data files must have restricted permissions.

A secure configuration file might have:

$ chmod 600 /etc/myapp/database.conf

This ensures only the owner can read or write the file. No group members or others can access it.

Your EC2 instance's IAM role should follow the principle of least privilege—grant only the minimum permissions needed. Similarly, file permissions should be as restrictive as possible while maintaining functionality.

Programs and Executables

Understanding how programs execute helps you troubleshoot deployment issues and write better automation scripts.

Compiled vs Interpreted Programs

Programs come in two flavors:

Compiled programs are converted to machine code before execution. Languages like Go, Rust, and C produce binaries—executable files containing processor instructions. These run directly on your hardware without needing additional software.

Interpreted programs require an interpreter to execute them. Python scripts need the Python interpreter. Shell scripts need a shell (bash or zsh).

When you run a compiled program:

$ /usr/bin/nginx

The operating system loads the binary and executes it.

When you run an interpreted program:

$ python3 app.py

The Python interpreter reads app.py, parses it, and executes the instructions.

Shebangs

Shell scripts and Python scripts often start with a shebang—a special first line indicating which interpreter to use:

#!/bin/bash
echo "This is a bash script"

Or for Python:

#!/usr/bin/env python3
print("This is a Python script")

The shebang tells the operating system which interpreter to invoke. With a proper shebang and execute permissions, you can run scripts directly:

$ chmod +x script.py
$ ./script.py

Without the shebang, you'd need to explicitly specify the interpreter:

$ python3 script.py

Finding Programs

The which command shows a program's location:

$ which python3

Output might show:

/usr/bin/python3

This tells you where the Python interpreter is installed.

AWS Context: Lambda Execution Environments

AWS Lambda functions run in execution environments—essentially small Linux containers. When you deploy Python code to Lambda, AWS provides the Python interpreter. Your code runs as an interpreted program.

For performance-critical workloads, you can deploy compiled binaries as custom Lambda runtimes. A Go binary, for example, starts faster and uses less memory than interpreted Python.

Understanding this distinction helps you make architectural decisions. Need microsecond response times? Use compiled languages. Need rapid development? Interpreted languages work well.

Environment Variables and the PATH

Environment variables configure programs without hardcoding values. The PATH variable is the most important one you'll work with.

What is PATH?

PATH is an environment variable containing a colon-separated list of directories. When you run a command, your shell searches these directories for a matching executable.

Check your PATH:

$ echo $PATH

You see something like:

/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

This means the shell searches (in order):

/usr/local/bin
/usr/bin
/bin
/usr/sbin
/sbin

When you type python3, the shell finds /usr/bin/python3 and executes it. You don't need to type the full path.

Adding to PATH

Programs you install often need to be added to PATH. To add a directory for the current session:

$ export PATH="$PATH:/home/achar/bin"

This appends /home/achar/bin to your existing PATH. Programs in that directory are now accessible by name.

To make this permanent, add the export command to your shell configuration file:

bash: ~/.bashrc
zsh: ~/.zshrc

Edit the file:

$ nano ~/.zshrc

Add at the end:

export PATH="$PATH:/home/achar/bin"

Save and exit. New shell sessions will include this directory in PATH.

To apply changes to your current session:

$ source ~/.zshrc

Creating Environment Variables

Set environment variables with export:

$ export DATABASE_URL="postgresql://localhost:5432/mydb"

Programs can read this variable. In Python:

import os

db_url = os.getenv("DATABASE_URL")
print(f"Connecting to {db_url}")

AWS Context: Lambda Environment Variables

Lambda functions use environment variables extensively. You set them in the AWS Console or via Infrastructure as Code:

# Lambda function code
import os
import boto3

bucket_name = os.getenv("S3_BUCKET_NAME")
s3 = boto3.client("s3")

In your CloudFormation or Terraform configuration:

resource "aws_lambda_function" "processor" {
  function_name = "data-processor"

  environment {
    variables = {
      S3_BUCKET_NAME = "patient-records-bucket"
      LOG_LEVEL      = "INFO"
    }
  }
}

This pattern separates configuration from code—crucial for multi-environment deployments (dev, staging, production).

Healthcare Context: Secure Credentials

Never hardcode database passwords or API keys. Use environment variables:

$ export DB_PASSWORD="$(aws secretsmanager get-secret-value --secret-id prod-db --query SecretString --output text)"

This retrieves a secret from AWS Secrets Manager and stores it in an environment variable. Your application reads it without ever exposing the password in source code.

For HIPAA compliance, audit all environment variable usage. Ensure sensitive values come from secure sources like Secrets Manager, not plaintext files.

Input, Output, and Streams

Programs communicate through three standard streams: standard input (stdin), standard output (stdout), and standard error (stderr).

Standard Output

When a program prints results, it writes to stdout. The echo command demonstrates this:

$ echo "Hello"

The text appears in your terminal because stdout is directed there by default.

Redirecting Output

You can redirect stdout to a file with >:

$ echo "Log entry" > application.log

This creates application.log with the content "Log entry". If the file exists, > overwrites it.

To append instead of overwriting, use >>:

$ echo "Another entry" >> application.log

Standard Error

Programs write error messages to stderr, a separate stream from stdout. This separation lets you handle errors differently from regular output.

Most commands write errors to stderr:

$ ls nonexistent-directory

You see an error message. To redirect stderr to a file:

$ ls nonexistent-directory 2> errors.log

The 2> syntax redirects stderr (file descriptor 2). To redirect both stdout and stderr:

$ command > output.log 2> errors.log

Or combine them into one file:

$ command > combined.log 2>&1

Standard Input

Programs can read from stdin. The read command in bash demonstrates this:

#!/bin/bash
echo "What is your name?"
read name
echo "Hello, $name"

When you run this script, it waits for your input.

Piping

The pipe operator (|) connects stdout of one program to stdin of another:

$ cat application.log | grep "ERROR"

This reads application.log, then filters lines containing "ERROR". Piping creates powerful command chains.

Find the 10 most common error messages:

$ grep "ERROR" application.log | sort | uniq -c | sort -rn | head -10

Breaking this down:

grep extracts error lines
sort arranges them alphabetically
uniq -c counts duplicates
sort -rn sorts numerically in reverse
head -10 shows the top 10

AWS Context: CloudWatch Logs

When your Lambda function writes to stdout, AWS captures it in CloudWatch Logs. Your Python code:

def lambda_handler(event, context):
    print(f"Processing event: {event}")
    return {"statusCode": 200}

The print statement writes to stdout, which appears in CloudWatch:

$ aws logs tail /aws/lambda/my-function --follow

Understanding stdout/stderr helps you design effective logging strategies. Errors should go to stderr, normal operation to stdout.

Package Managers

Package managers automate software installation, dependency resolution, and updates. They're essential for maintaining cloud infrastructure.

Linux: apt

On Ubuntu and Debian-based systems, use apt:

$ sudo apt update

This refreshes the package index—the database of available software.

To install a package:

$ sudo apt install nginx

This installs the Nginx web server, including all dependencies. The package manager:

Downloads Nginx and its dependencies
Installs everything in the correct locations
Configures the system PATH
Sets up systemd services (if applicable)

To remove a package:

$ sudo apt remove nginx

macOS: Homebrew

On macOS, Homebrew is the de facto package manager:

$ brew install python3

This installs Python 3 and adds it to your PATH automatically.

Update all installed packages:

$ brew upgrade

Python: pip

Python has its own package manager:

$ pip install boto3

This installs the AWS SDK for Python. Use requirements.txt to manage project dependencies:

boto3==1.26.137
requests==2.28.2
psycopg2-binary==2.9.5

Install everything in the file:

$ pip install -r requirements.txt

AWS Context: EC2 User Data

When launching EC2 instances, you can run initialization scripts via User Data. This often involves package managers:

#!/bin/bash
apt-get update
apt-get install -y nginx python3-pip
pip3 install boto3

# Configure application
systemctl enable nginx
systemctl start nginx

This script runs when the instance first boots, installing dependencies and starting services.

Healthcare Context: Auditable Deployments

For HIPAA compliance, you need auditable deployment processes. Package managers help by:

Versioning dependencies explicitly
Creating reproducible environments
Tracking what's installed on each server

Your requirements.txt becomes part of your compliance documentation, proving exactly which software versions handle PHI.

Troubleshooting Framework

When something breaks—and it will—follow this systematic approach.

Step 1: Identify the Symptom

What's actually failing? Be specific:

"The application returns 502 errors"
"The database connection times out"
"The Lambda function exceeds memory limits"

Vague problems like "it doesn't work" waste time.

Step 2: Check the Logs

Logs contain most answers. For web servers:

$ tail -100 /var/log/nginx/error.log

For application logs:

$ journalctl -u myapp.service -n 100

For AWS services, check CloudWatch Logs:

$ aws logs tail /aws/lambda/my-function --since 10m

Step 3: Verify Permissions

Permission issues cause many failures. Check file permissions:

$ ls -l /var/www/html/config.php

Is the owner correct? Are permissions too restrictive?

Check your user's permissions:

$ groups

Are you in the right groups?

Step 4: Test Connectivity

Network issues are common. Test connections:

$ curl https://api.example.com/health

For databases:

$ telnet database.example.com 5432

If the connection fails, check security groups, network ACLs, and firewall rules.

Step 5: Verify Environment Variables

Many issues stem from missing or incorrect environment variables:

$ echo $DATABASE_URL

Is it set? Is it correct?

Step 6: Reproduce Locally

Try to replicate the issue on your development machine. If you can't reproduce it locally, the problem is environmental—likely configuration or permissions on the server.

Real-World Example: Deploying a Python Web Application

Let me walk through a complete deployment to an EC2 instance, demonstrating these concepts together.

Provision the Instance

Launch an Ubuntu 22.04 EC2 instance. Connect via SSH:

$ ssh -i keypair.pem ubuntu@ec2-xx-xx-xx-xx.compute-1.amazonaws.com

Install Dependencies

Update package index:

$ sudo apt update

Install Python and pip:

$ sudo apt install -y python3-pip python3-venv nginx

Create Application Structure

Create a directory:

$ mkdir -p /home/ubuntu/myapp
$ cd /home/ubuntu/myapp

Create a virtual environment:

$ python3 -m venv venv
$ source venv/bin/activate

Install Application Dependencies

Create requirements.txt:

flask==2.3.0
gunicorn==20.1.0
boto3==1.26.137
psycopg2-binary==2.9.5

Install:

$ pip install -r requirements.txt

Configure Environment Variables

Create a .env file:

export DATABASE_URL="postgresql://user:password@db.example.com:5432/mydb"
export S3_BUCKET="patient-records-bucket"
export AWS_REGION="us-east-1"

Load it:

$ source .env

Create the Application

Write app.py:

from flask import Flask, jsonify
import boto3
import os

app = Flask(__name__)

s3 = boto3.client("s3", region_name=os.getenv("AWS_REGION"))
bucket = os.getenv("S3_BUCKET")

@app.route("/health")
def health():
    return jsonify({"status": "healthy"})

@app.route("/files")
def list_files():
    response = s3.list_objects_v2(Bucket=bucket, MaxKeys=10)
    files = [obj["Key"] for obj in response.get("Contents", [])]
    return jsonify({"files": files})

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000)

Test locally:

$ python app.py

Open another terminal and test:

$ curl http://localhost:5000/health

Configure Gunicorn

Create a systemd service file:

$ sudo nano /etc/systemd/system/myapp.service

Add:

[Unit]
Description=My Flask Application
After=network.target

[Service]
User=ubuntu
WorkingDirectory=/home/ubuntu/myapp
Environment="PATH=/home/ubuntu/myapp/venv/bin"
EnvironmentFile=/home/ubuntu/myapp/.env
ExecStart=/home/ubuntu/myapp/venv/bin/gunicorn --workers 3 --bind 127.0.0.1:5000 app:app

[Install]
WantedBy=multi-user.target

Enable and start:

$ sudo systemctl enable myapp
$ sudo systemctl start myapp
$ sudo systemctl status myapp

Configure Nginx

Create Nginx configuration:

$ sudo nano /etc/nginx/sites-available/myapp

Add:

server {
    listen 80;
    server_name _;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Enable the site:

$ sudo ln -s /etc/nginx/sites-available/myapp /etc/nginx/sites-enabled/
$ sudo nginx -t
$ sudo systemctl reload nginx

Verify Deployment

Test from your local machine:

$ curl http://ec2-xx-xx-xx-xx.compute-1.amazonaws.com/health

You should see:

{"status": "healthy"}

Troubleshoot Issues

If it doesn't work, check logs:

$ sudo journalctl -u myapp -n 50
$ sudo tail -50 /var/log/nginx/error.log

Common issues:

Permission denied: Check file permissions with ls -l
Connection refused: Verify Gunicorn is running with systemctl status myapp
502 Bad Gateway: Nginx can't reach Gunicorn—check the proxy configuration

This workflow demonstrates terminals, shells, file navigation, permissions, environment variables, package management, and troubleshooting—all in a real deployment scenario.

Conclusion

The Linux command line is your primary interface to cloud infrastructure. You've learned:

How terminals and shells work
File system navigation and manipulation
Permission systems and their security implications
Program execution models
Environment variables and PATH management
Standard streams and piping
Package managers for dependency management
A systematic troubleshooting framework
Real-world deployment workflows

These skills transfer directly to AWS and other cloud platforms. Whether you're managing EC2 instances, debugging Lambda functions, or configuring ECS tasks, you'll use these commands daily.

For your AWS certification preparation, practice these commands in real cloud environments. Spin up EC2 instances, SSH in, and deploy applications. The command line becomes intuitive through repetition.

As you build HIPAA-compliant healthcare systems, remember that proper file permissions, secure environment variable management, and auditable deployments start with solid Linux fundamentals.

The command line is the foundation of modern cloud engineering.

What Really Happens When You Access AWS: Complete Data Flow Example

Stella Achar Oiro — Wed, 12 Nov 2025 05:15:55 +0000

You learned the OSI model in Part 1.

You learned how switches and routers work in Part 2.

You learned IP addressing and protocols in Part 3.

Now I show you how it all works together.

This is the complete journey, Your laptop → AWS EC2 instance → Your laptop.

Every protocol. Every header. Every table lookup. Every hop.

By the end, you will understand exactly what happens when you run any AWS command.

Let me trace the entire data flow.

The Scenario

You run a simple Python script:

import boto3

ec2 = boto3.client('ec2', region_name='us-east-1')
response = ec2.describe_instances()

print(f"Found {len(response['Reservations'])} instances")

That one line triggers a cascade of networking events across:

7 OSI layers
Multiple switches
Multiple routers
Dozens of protocols
Hundreds of hops

Let me show you every single step.

Your Network Setup

Your Computer:

IP: 192.168.1.100
MAC: AA:AA:AA:AA:AA:AA
Subnet: 192.168.1.0/24
Gateway: 192.168.1.1
DNS: 8.8.8.8

Your Home Router:

Internal IP: 192.168.1.1
Internal MAC: R1:R1:R1:R1:R1:R1
External IP: 203.0.113.50 (ISP assigned)

AWS EC2 API Endpoint:

Domain: ec2.us-east-1.amazonaws.com
IP: 52.94.133.131 (one of many)
Located in us-east-1 region

Phase 1: DNS Resolution

Your computer knows the domain name but needs the IP address.

Step 1: Check Local DNS Cache

Your computer checks:

$ dscacheutil -q host -a name ec2.us-east-1.amazonaws.com

Cache empty. Need to query DNS server.

Step 2: Construct DNS Query

Your computer creates DNS request:

Layer 7 (Application):
  DNS Query: "What is IP for ec2.us-east-1.amazonaws.com?"

Layer 4 (Transport):
  Protocol: UDP
  Source Port: 54321 (random)
  Destination Port: 53 (DNS)

Layer 3 (Network):
  Source IP: 192.168.1.100 (you)
  Destination IP: 8.8.8.8 (Google DNS)

Layer 2 (Data Link):
  Source MAC: AA:AA:AA:AA:AA:AA (you)
  Destination MAC: ??? (need gateway MAC)

Step 3: ARP for Gateway

Your computer needs gateway's MAC address.

Check ARP cache:

$ arp -a | grep 192.168.1.1

If cached:

192.168.1.1 → R1:R1:R1:R1:R1:R1

Use cached MAC. Skip ARP.

If not cached:

ARP Request (broadcast):
  Who has 192.168.1.1?
  Tell 192.168.1.100 at MAC AA:AA

Router responds:
  192.168.1.1 is at MAC R1:R1

Cache updated:
  192.168.1.1 → R1:R1

Step 4: Send DNS Query

Complete packet to gateway:

[L2: AA:AA → R1:R1]              (to router)
[L3: 192.168.1.100 → 8.8.8.8]    (to Google DNS)
[L4: UDP 54321 → 53]              (DNS query)
[L7: DNS Query for ec2.us-east-1.amazonaws.com]

Step 5: Router Processes DNS Query

Your home router receives packet:

Remove Layer 2 header (reached router)
Check routing table:
- Destination: 8.8.8.8
- Not local (192.168.1.x)
- Match default route: 0.0.0.0/0 → ISP
Perform NAT (Network Address Translation):
- Change source IP: 192.168.1.100 → 203.0.113.50 (router's public IP)
- Track connection in NAT table
Create new Layer 2 header for ISP router
Forward packet

Step 6: Internet Journey to Google DNS

Packet traverses multiple routers:

Your Router → ISP Router 1 → ISP Router 2 → 
Internet Backbone Router 1 → Internet Backbone Router 2 → 
Google Edge Router → Google DNS Server (8.8.8.8)

At each router:

Layer 2 header changes (hop-to-hop)
Layer 3 header stays same (end-to-end)
Routing table determines next hop
ARP resolves next hop MAC

Step 7: Google DNS Responds

Google DNS server sends response:

DNS Response:
  ec2.us-east-1.amazonaws.com → 52.94.133.131

Layer 3:
  Source: 8.8.8.8 (Google DNS)
  Destination: 203.0.113.50 (your router's public IP)

Step 8: Response Returns Through Internet

Packet traverses back through routers to your home router.

Step 9: Your Router Receives Response

Router checks NAT table:

NAT Table:
  External: 203.0.113.50:54321 ←→ Internal: 192.168.1.100:54321

Router translates:

Destination IP: 203.0.113.50 → 192.168.1.100
Forwards to your computer

Step 10: Your Computer Receives DNS Response

Your computer:

Removes headers layer by layer
Extracts DNS response: 52.94.133.131
Caches result:
- ec2.us-east-1.amazonaws.com → 52.94.133.131
- TTL: 60 seconds

DNS resolution complete.

Phase 2: TCP Connection Establishment

Your computer now knows AWS API endpoint IP. Time to establish connection.

Step 1: TCP SYN (Synchronize)

Your computer initiates TCP 3-way handshake:

Layer 4:
  TCP Flags: SYN
  Source Port: 55555 (random)
  Destination Port: 443 (HTTPS)
  Sequence Number: 1000

Layer 3:
  Source: 192.168.1.100
  Destination: 52.94.133.131

Layer 2:
  Source: AA:AA
  Destination: R1:R1 (gateway)

Packet travels through internet to AWS.

Step 2: TCP SYN-ACK (Synchronize-Acknowledge)

AWS server responds:

TCP Flags: SYN-ACK
Source Port: 443
Destination Port: 55555
Sequence Number: 2000
Acknowledgment Number: 1001

Travels back through internet to your computer.

Step 3: TCP ACK (Acknowledge)

Your computer completes handshake:

TCP Flags: ACK
Acknowledgment Number: 2001

TCP connection established.

Connection Identity:

192.168.1.100:55555 ←→ 52.94.133.131:443

This unique 4-tuple identifies this specific connection.

Phase 3: TLS Handshake

Connection established but not encrypted. Need TLS.

Step 1: Client Hello

Your computer sends:

TLS ClientHello:
  - TLS version: 1.3
  - Cipher suites supported
  - Random bytes for key generation

Step 2: Server Hello

AWS responds:

TLS ServerHello:
  - Chosen cipher suite
  - Server certificate
  - Random bytes

Step 3: Certificate Verification

Your computer verifies AWS certificate:

Issued by: Amazon Trust Services
Valid for: *.amazonaws.com
Not expired
Signature valid

Certificate trusted. Continue.

Step 4: Key Exchange

Both sides:

Generate session keys using random bytes
Establish encryption parameters

Step 5: Finished Messages

Both sides exchange encrypted "Finished" messages.

TLS tunnel established. All future data encrypted.

Phase 4: HTTP Request

Now your computer sends the actual API request.

Step 1: boto3 Constructs HTTP Request

# Your code
ec2 = boto3.client('ec2', region_name='us-east-1')
response = ec2.describe_instances()

boto3 creates:

POST / HTTP/1.1
Host: ec2.us-east-1.amazonaws.com
Content-Type: application/x-amz-json-1.1
X-Amz-Target: AmazonEC2.DescribeInstances
Authorization: AWS4-HMAC-SHA256 Credential=...
Content-Length: 2

{}

Step 2: Complete Packet Structure

Layer 7 (Application):
  [HTTP POST request above]

Layer 6 (Presentation):
  [TLS encryption of HTTP data]

Layer 5 (Session):
  [TLS session management]

Layer 4 (Transport):
  Protocol: TCP
  Source Port: 55555
  Destination Port: 443
  Flags: PSH, ACK (push data, acknowledge)

Layer 3 (Network):
  Source IP: 192.168.1.100
  Destination IP: 52.94.133.131
  Protocol: TCP
  TTL: 64

Layer 2 (Data Link):
  Source MAC: AA:AA
  Destination MAC: R1:R1 (to gateway)
  Type: IPv4

Layer 1 (Physical):
  [Bits transmitted over Wi-Fi]

Step 3: Journey Through Your Network

Packet travels:

Your computer → Home switch (if present)
Home switch → Home router

Switch operations:

Learn: Port X → MAC AA:AA
Check table for R1:R1
Forward: To router port

Step 4: Home Router Processing

Router receives packet:

Remove Layer 2 header
Check routing table:
- Destination: 52.94.133.131
- Match: 0.0.0.0/0 → ISP (default route)
NAT translation:
- Source IP: 192.168.1.100 → 203.0.113.50
- Track: 203.0.113.50:55555 ←→ 192.168.1.100:55555
Create new Layer 2 header:
- Destination: ISP router MAC
Forward packet

Step 5: ISP Router Processing

First ISP router receives packet:

Remove Layer 2 header
Check routing table:
- Destination: 52.94.133.131
- Match: 52.0.0.0/8 → Internet backbone
Create new Layer 2 header
Forward packet

This repeats at every router.

Step 6: Internet Backbone Routers

Packet traverses multiple Tier 1 ISP routers:

ISP Router 1 → ISP Router 2 → 
Regional Router 1 → Regional Router 2 →
Internet Exchange Point →
AWS Edge Router → AWS Region Router

Each router:

Checks routing table
Determines next hop based on destination network
ARPs for next hop MAC (if needed)
Forwards packet

Layer 3 header constant throughout.
Layer 2 header changes at every hop.

Step 7: AWS Edge Router

AWS edge router receives packet:

Check routing table:

Destination: 52.94.133.131
Match: 52.94.133.0/24 → us-east-1 API servers
Next hop: Load balancer in us-east-1

Step 8: AWS Application Load Balancer

ALB receives packet:

Terminate TLS connection
Decrypt HTTPS request
Examine HTTP headers:
- Host: ec2.us-east-1.amazonaws.com
- X-Amz-Target: AmazonEC2.DescribeInstances
Route to EC2 API backend server
Re-encrypt with internal TLS
Forward to backend

Step 9: EC2 API Server

Backend server receives request:

Decrypt TLS
Parse HTTP request
Validate authorization signature
Execute: DescribeInstances
Query EC2 service database
Retrieve instance metadata
Format JSON response

Step 10: Processing Complete

API server has response ready.

Phase 5: HTTP Response

Now the response travels back.

Step 1: EC2 API Server Sends Response

HTTP/1.1 200 OK
Content-Type: application/x-amz-json-1.1
Content-Length: 1543

{
  "Reservations": [
    {
      "Instances": [
        {
          "InstanceId": "i-1234567890abcdef0",
          "InstanceType": "t3.micro",
          "State": {"Name": "running"},
          "PrivateIpAddress": "10.0.1.50",
          ...
        }
      ]
    }
  ]
}

Step 2: Response Returns Through AWS Infrastructure

EC2 API Server → ALB → AWS Region Router → 
AWS Edge Router → Internet

ALB:

Encrypts response with TLS
Sends to your connection (tracked by source/dest IPs and ports)

Step 3: Internet Journey Back

Packet traverses back through internet routers:

AWS Edge → Internet Exchange → 
Tier 1 ISP Routers → Your ISP Routers → Your Router

Each router:

Checks destination IP (203.0.113.50)
Routes accordingly

Step 4: Your Router Receives Response

Router checks NAT table:

NAT Table:
  External: 203.0.113.50:55555 ←→ Internal: 192.168.1.100:55555

Router translates:

Destination IP: 203.0.113.50 → 192.168.1.100
Destination port: 55555 (preserved)

Creates new Layer 2 header:

Destination MAC: AA:AA (your computer)

Forwards to your computer.

Step 5: Your Computer Processes Response

Your computer receives packet:

De-encapsulation:

Layer 1: Bits received from Wi-Fi
         ↓
Layer 2: Check MAC = AA:AA? YES
         Remove Ethernet header
         ↓
Layer 3: Check IP = 192.168.1.100? YES
         Remove IP header
         ↓
Layer 4: Check Port = 55555? YES
         TCP reassembly
         Remove TCP header
         ↓
Layer 5: TLS session identified
         ↓
Layer 6: Decrypt TLS
         ↓
Layer 7: Parse HTTP response
         Extract JSON data
         ↓
Application: boto3 processes response

Your Python script receives:

response = {
    'Reservations': [...]
}

print(f"Found {len(response['Reservations'])} instances")
# Output: Found 1 instances

Complete.

Summary: What Just Happened

Your simple boto3 call triggered:

DNS Resolution:

1 DNS query (UDP)
1 DNS response
ARP for gateway
Multiple router hops

TCP Connection:

3-way handshake (SYN, SYN-ACK, ACK)
Multiple router hops each way

TLS Handshake:

ClientHello
ServerHello
Certificate verification
Key exchange
Multiple encrypted messages

HTTP Request:

1 HTTP POST request
Through 20+ routers (typical)
NAT translation at your router
Load balancer routing

HTTP Response:

1 HTTP 200 response
Back through 20+ routers
NAT reverse translation
De-encryption and processing

Total packets exchanged: ~50-100

Total time: ~100-200 milliseconds

All of this happens invisibly. Every single time.

The Three Tables in Action

Let me show you how all three tables were used.

MAC Address Table (Switches):

Your home switch (if present):

Before:
Port  |  MAC
------|------
(empty)

After first packet:
Port  |  MAC
------|------
5     |  AA:AA (your computer)
8     |  R1:R1 (router)

Used for forwarding within your home network.

ARP Table (Your Computer and Routers):

Your computer:

Initial:
IP          |  MAC
------------|------
(empty)

After DNS query:
IP              |  MAC
----------------|------
192.168.1.1     |  R1:R1 (gateway)

After response:
(same, reused throughout connection)

Routing Table (All Routers):

Your home router:

Network             |  Next Hop
--------------------|------------------
192.168.1.0/24      |  Local (LAN)
0.0.0.0/0           |  ISP (default)

ISP router:

Network             |  Next Hop
--------------------|------------------
203.0.113.0/24      |  Local
52.0.0.0/8          |  AWS peering point
0.0.0.0/0           |  Backbone

AWS edge router:

Network             |  Next Hop
--------------------|------------------
52.94.133.0/24      |  us-east-1 API servers
10.0.0.0/8          |  VPC networks

All three tables work together at every hop.

Real-World Healthcare Example

Let me show you a practical healthcare scenario.

Architecture:

Patient Mobile App (Internet)
        ↓
API Gateway (HTTPS endpoint)
        ↓
Lambda Function (VPC)
        ↓
RDS PostgreSQL (Private subnet)

Scenario: Patient Requests Medical Records

Patient app sends:

GET /api/records/patient/12345 HTTP/1.1
Host: api.myhealthapp.com
Authorization: Bearer eyJ...

Step 1: DNS Resolution

Query: api.myhealthapp.com
Response: 54.123.45.67 (API Gateway endpoint)

Step 2: HTTPS to API Gateway

Packet traverses internet to AWS.

API Gateway:

Terminates TLS
Validates JWT token
Checks authorization
Invokes Lambda function

Step 3: Lambda Function Execution

Lambda in VPC:

import boto3
import psycopg2

def lambda_handler(event, context):
    patient_id = event['pathParameters']['patient_id']

    # Lambda has ENI in VPC subnet
    # Private IP: 10.0.2.50

    # Connect to RDS in private subnet
    conn = psycopg2.connect(
        host="mydb.abc123.us-east-1.rds.amazonaws.com",
        database="healthrecords",
        user="app_user",
        password="..."
    )

    cursor = conn.cursor()
    cursor.execute(
        "SELECT * FROM records WHERE patient_id = %s",
        (patient_id,)
    )
    records = cursor.fetchall()

    return {
        'statusCode': 200,
        'body': json.dumps(records)
    }

Step 4: Lambda → RDS Connection

Lambda needs to connect to RDS.

DNS resolution (internal):

Query: mydb.abc123.us-east-1.rds.amazonaws.com
Response: 10.0.3.100 (RDS private IP)

Lambda checks:

My IP: 10.0.2.50 (subnet 10.0.2.0/24)
Destination: 10.0.3.100 (subnet 10.0.3.0/24)
Different subnets → Check route table

VPC Route Table:

Network         |  Target
----------------|----------
10.0.0.0/16     |  local

Both subnets in 10.0.0.0/16 VPC. Route is "local."

Lambda sends packet:

[L3: 10.0.2.50 → 10.0.3.100]
[L4: TCP random port → 5432 (PostgreSQL)]

Step 5: Security Group Check

Lambda ENI Security Group (outbound):

Allow all outbound traffic ✓

RDS Security Group (inbound):

Allow TCP 5432 from 10.0.2.0/24 (Lambda subnet) ✓

Packet allowed through.

Step 6: RDS Processes Query

RDS receives connection:

Authenticates user
Executes query
Returns encrypted patient records
Logs access (HIPAA compliance)

Step 7: Response Path

RDS (10.0.3.100) → Lambda (10.0.2.50) → 
API Gateway → Internet → Patient App

All within VPC uses internal routing.

All encrypted in transit (TLS).

All access logged (CloudTrail).

HIPAA Considerations:

Encryption in transit: TLS everywhere
Encryption at rest: RDS encryption enabled
Network isolation: RDS in private subnet (no internet)
Access control: Security Groups restrict access
Audit logging: CloudTrail + VPC Flow Logs
Data protection: PHI never leaves VPC unencrypted

This architecture meets HIPAA technical safeguards.

Troubleshooting Framework

When connectivity fails, debug layer by layer.

Problem: "Cannot connect to EC2 instance"

Layer 1: Physical connectivity

$ ping 8.8.8.8

If fails: Check network cable, Wi-Fi connection.
If succeeds: Layer 1 works. Move to Layer 2.

Layer 2: Local network

$ arp -a | grep 192.168.1.1

Can you see gateway MAC?
If no: ARP issue or gateway down.
If yes: Layer 2 works. Move to Layer 3.

Layer 3: IP routing

$ ping 192.168.1.1

Can you ping gateway?
If no: Gateway unreachable.
If yes: Gateway works.

$ ping 52.94.133.131

Can you ping AWS?
If no: Internet routing issue.
If yes: Layer 3 works. Move to Layer 4.

Layer 4: Ports and protocols

$ telnet 52.94.133.131 443

$ nc -zv 52.94.133.131 443

Can you connect to port 443?
If no: Port blocked (firewall, security group).
If yes: Layer 4 works. Move to Layer 7.

Layer 7: Application

$ curl -v https://ec2.us-east-1.amazonaws.com

Does HTTPS work?
If no: Certificate issue, application down.
If yes: Layer 7 works.

AWS-Specific Checks:

Check 1: Security Groups

$ aws ec2 describe-security-groups --group-ids sg-xxxxx

Verify:

Inbound rules allow your IP
Outbound rules allow destination

Check 2: Network ACLs

$ aws ec2 describe-network-acls --network-acl-ids acl-xxxxx

Verify:

Inbound rules allow traffic
Outbound rules allow responses
Stateless (must allow both directions)

Check 3: Route Tables

$ aws ec2 describe-route-tables --filters "Name=vpc-id,Values=vpc-xxxxx"

Verify:

Local route exists (10.0.0.0/16 → local)
Internet route exists (0.0.0.0/0 → igw-xxxxx)
Subnet associations correct

Check 4: Internet Gateway

$ aws ec2 describe-internet-gateways --filters "Name=attachment.vpc-id,Values=vpc-xxxxx"

Verify:

IGW exists
IGW attached to VPC
State: available

Check 5: Instance Status

$ aws ec2 describe-instance-status --instance-ids i-xxxxx

Verify:

Instance running
Status checks passing
System reachability OK

Check 6: VPC Flow Logs

$ aws ec2 describe-flow-logs --filter "Name=resource-id,Values=eni-xxxxx"

Review logs for:

ACCEPT vs REJECT
Which security group/NACL blocked
Source and destination IPs

Python Debugging Script:

import boto3
import socket

def debug_connectivity(instance_id, region='us-east-1'):
    """Debug EC2 instance connectivity"""

    ec2 = boto3.client('ec2', region_name=region)

    # Get instance details
    response = ec2.describe_instances(InstanceIds=[instance_id])
    instance = response['Reservations'][0]['Instances'][0]

    private_ip = instance.get('PrivateIpAddress')
    public_ip = instance.get('PublicIpAddress')
    state = instance['State']['Name']
    subnet_id = instance['SubnetId']
    vpc_id = instance['VpcId']
    security_groups = instance['SecurityGroups']

    print(f"Instance: {instance_id}")
    print(f"State: {state}")
    print(f"Private IP: {private_ip}")
    print(f"Public IP: {public_ip}")
    print(f"VPC: {vpc_id}")
    print(f"Subnet: {subnet_id}")
    print(f"\nSecurity Groups:")

    for sg in security_groups:
        sg_id = sg['GroupId']
        print(f"  {sg_id}")

        # Get security group rules
        sg_details = ec2.describe_security_groups(GroupIds=[sg_id])

        print("  Inbound Rules:")
        for rule in sg_details['SecurityGroups'][0]['IpPermissions']:
            protocol = rule.get('IpProtocol', 'all')
            from_port = rule.get('FromPort', 'all')
            to_port = rule.get('ToPort', 'all')

            print(f"    {protocol} {from_port}-{to_port}")

            for ip_range in rule.get('IpRanges', []):
                print(f"      from {ip_range['CidrIp']}")

    # Check route table
    print(f"\nRoute Table for subnet {subnet_id}:")

    route_tables = ec2.describe_route_tables(
        Filters=[
            {'Name': 'association.subnet-id', 'Values': [subnet_id]}
        ]
    )

    if route_tables['RouteTables']:
        for route in route_tables['RouteTables'][0]['Routes']:
            dest = route.get('DestinationCidrBlock', 'N/A')
            target = route.get('GatewayId', 
                              route.get('NatGatewayId', 
                              route.get('NetworkInterfaceId', 'local')))
            print(f"  {dest} → {target}")

    # Test connectivity if public IP exists
    if public_ip:
        print(f"\nTesting connectivity to {public_ip}...")

        # Try ping (ICMP)
        import subprocess
        result = subprocess.run(
            ['ping', '-c', '1', '-W', '1', public_ip],
            capture_output=True
        )

        if result.returncode == 0:
            print("  ✓ ICMP (ping) successful")
        else:
            print("  ✗ ICMP (ping) failed")

        # Try TCP port 22 (SSH)
        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
        sock.settimeout(2)
        result = sock.connect_ex((public_ip, 22))

        if result == 0:
            print("  ✓ TCP port 22 (SSH) open")
        else:
            print("  ✗ TCP port 22 (SSH) closed/filtered")

        sock.close()

# Usage
debug_connectivity('i-1234567890abcdef0')

This script checks every common issue.

Key Takeaways

Complete data flow requires:

DNS resolution (name to IP)
ARP resolution (IP to MAC for each hop)
Routing decisions (at every router)
Security checks (security groups, NACLs)
Protocol handshakes (TCP, TLS)
Application processing (HTTP request/response)

Every AWS API call involves:

50-100 packets
20+ router hops
All 7 OSI layers
Multiple protocols (DNS, TCP, TLS, HTTP)
NAT translation
Load balancer routing

The three tables work together:

MAC Address Table: Switches forward within networks
ARP Table: Resolve next hop IPs to MACs
Routing Table: Determine packet paths

For HIPAA compliance:

Encrypt data in transit (TLS)
Encrypt data at rest (KMS)
Isolate databases (private subnets)
Control access (security groups)
Log everything (CloudTrail, VPC Flow Logs)

What You Have Learned

Congratulations. You completed the series.

Part 1: OSI Model

7 layers, 7 solutions
Why each layer matters for AWS

Part 2: Switches and Routers

How devices forward data
MAC tables, ARP tables, routing tables
AWS VPC Route Tables

Part 3: IP Addresses and Protocols

IP addressing and subnetting
Essential protocols (ARP, DNS, DHCP, HTTP)
The four settings every host needs

Part 4: Complete Data Flow

End-to-end packet journey
Every protocol in action
Real troubleshooting framework
Healthcare example with HIPAA

You now understand networking at a fundamental level.

You can:

Design VPC architectures properly
Troubleshoot connectivity issues systematically
Explain what happens when code runs
Make informed decisions about security and routing

This knowledge transfers to any cloud provider and any networking scenario.

What Comes Next

You have the fundamentals. Now go deeper:

Advanced Topics:

VPN and Direct Connect
Transit Gateway architectures
VPC peering and PrivateLink
Network performance optimization
Advanced security (WAF, Shield)

AWS Certifications:

Solutions Architect Associate
Advanced Networking Specialty
Security Specialty

Practical Projects:

Build multi-tier application in VPC
Implement hybrid cloud connectivity
Design disaster recovery architecture
Deploy microservices with service mesh

Keep learning. Keep building. Keep asking questions.

Your Turn

You made it through all four parts.

What is your biggest takeaway?

What networking concept finally clicked?

What will you build with this knowledge?

Drop a comment. I want to hear your story.

This series:

Part 1: OSI Model Explained
Part 2: Switches and Routers
Part 3: IP Addresses and Protocols
Part 4: Complete Data Flow (this article)

Thank you for following along on this journey.

Follow me for more AWS content, healthcare technology insights, and learning in public.

Resources

AWS Documentation:

Networking Tools:

Wireshark - Packet capture and analysis
tcpdump - Command-line packet analyzer
MTR - Network diagnostic tool

HIPAA Resources:

Practice:

Stella Achar Oiro is a software developer with clinical healthcare experience, currently studying for AWS certifications while building HIPAA-compliant cloud infrastructure. She shares her learning journey to help other developers transition to cloud engineering.

This is Part 4 (finale) of a 4-part series on Networking Fundamentals for Cloud Engineers.

Thank you for reading the complete series. Your engagement and questions made this journey worthwhile.

IP Addresses, Subnets, and the Protocols That Power the Internet

Stella Achar Oiro — Tue, 11 Nov 2025 04:55:04 +0000

Every time you connect to Wi-Fi, your computer automatically gets four pieces of information. Without these four things, you have no internet.

Most people never see this happen. But understanding it is critical for AWS networking.

Let me show you what your computer needs and why.

IP Addresses Explained

An IP address is your computer's identity on the network.

Think of it like a mailing address. Without an address, no one can send you mail. Without an IP address, no one can send you data.

Structure:

IP address equals 32 bits (IPv4).

We display it as 4 octets (numbers 0-255):

192.168.1.100

Breaking it down:

192     .  168     .  1       .  100
↑          ↑          ↑          ↑
Octet 1    Octet 2    Octet 3    Octet 4
8 bits     8 bits     8 bits     8 bits

Each octet equals 8 bits. Total: 32 bits.

In binary:

11000000.10101000.00000001.01100100
↓
192.168.1.100

You never see the binary. But that is what computers use.

IP Address Hierarchy

IP addresses are organized hierarchically, like phone numbers with area codes.

Example: Acme Corporation

Acme Corporation: 10.0.0.0/8
├── New York Office: 10.20.0.0/16
│   ├── Sales: 10.20.55.0/24
│   │   └── Host: 10.20.55.44
│   ├── Engineering: 10.20.66.0/24
│   │   └── Host: 10.20.66.88
│   └── Marketing: 10.20.77.0/24
│       └── Host: 10.20.77.99
│
├── London Office: 10.30.0.0/16
│   ├── Sales: 10.30.55.0/24
│   ├── Engineering: 10.30.66.0/24
│   └── Marketing: 10.30.77.0/24
│
└── Tokyo Office: 10.40.0.0/16
    ├── Sales: 10.40.55.0/24
    ├── Engineering: 10.40.66.0/24
    └── Marketing: 10.40.77.0/24

Looking at IP 10.30.55.50:

First octet (10): Acme Corporation
Second octet (30): London Office
Third octet (55): Sales Team
Fourth octet (50): Specific host

This hierarchy helps routers make forwarding decisions efficiently.

AWS Example:

When you create a VPC, you define this hierarchy:

import boto3

ec2 = boto3.client('ec2')

# Create VPC (top of hierarchy)
vpc = ec2.create_vpc(CidrBlock='10.0.0.0/16')
vpc_id = vpc['Vpc']['VpcId']

# Create subnets (subdivisions)
public_subnet = ec2.create_subnet(
    VpcId=vpc_id,
    CidrBlock='10.0.1.0/24',  # Public subnet
    AvailabilityZone='us-east-1a'
)

private_subnet = ec2.create_subnet(
    VpcId=vpc_id,
    CidrBlock='10.0.2.0/24',  # Private subnet
    AvailabilityZone='us-east-1a'
)

database_subnet = ec2.create_subnet(
    VpcId=vpc_id,
    CidrBlock='10.0.3.0/24',  # Database subnet
    AvailabilityZone='us-east-1b'
)

You just created IP address hierarchy in AWS.

Subnet Masks: Understanding Slash Notation

Subnet masks define the size of your network.

What does /24 mean?

The number after the slash tells you how many bits define the network portion.

Example: 10.20.55.0/24

/24 means first 24 bits define the network. Last 8 bits define hosts.

10  .  20  .  55  .  0   / 24
↑      ↑      ↑      ↑
8 bits 8 bits 8 bits 8 bits

First 24 bits = Network (10.20.55)
Last 8 bits = Hosts (0-255)

How many hosts?

8 bits for hosts equals 2^8 equals 256 addresses.

Network: 10.20.55.0/24
Can have: 10.20.55.0 through 10.20.55.255

(Actually 254 usable hosts. First and last are reserved.)

Common Subnet Sizes

/24 Network

Network: 10.20.55.0/24
First 24 bits = Network
Last 8 bits = Hosts

Usable range: 10.20.55.1 - 10.20.55.254
Total hosts: 254

AWS Example: Small subnet for a few EC2 instances

/16 Network

Network: 10.20.0.0/16
First 16 bits = Network
Last 16 bits = Hosts

Usable range: 10.20.0.1 - 10.20.255.254
Total hosts: 65,534

AWS Example: Entire VPC or large subnet

/8 Network

Network: 10.0.0.0/8
First 8 bits = Network
Last 24 bits = Hosts

Usable range: 10.0.0.1 - 10.255.255.254
Total hosts: 16,777,214

AWS Example: Massive corporate network

How Hosts Use Subnet Masks

Subnet masks help hosts determine: "Is the destination on my network or a foreign network?"

Example:

Host A:
IP: 10.1.1.22
Subnet Mask: 255.255.255.0 (which is /24)

Host A wants to send to: 10.1.1.33

Decision process:

My IP:          10.1.1.22
My network:     10.1.1.x (first 24 bits)

Destination:    10.1.1.33
Their network:  10.1.1.x (first 24 bits)

Same network? YES

Action: ARP for destination IP directly

Host A wants to send to: 192.168.1.44

Decision process:

My IP:          10.1.1.22
My network:     10.1.1.x

Destination:    192.168.1.44
Their network:  192.168.1.x

Same network? NO

Action: Send to default gateway (router)

This decision happens automatically. Every single packet.

Public vs Private IP Addresses

Not all IP addresses are equal. Some are public. Some are private.

Private IP Ranges (RFC 1918):

10.0.0.0/8        (10.0.0.0 - 10.255.255.255)
172.16.0.0/12     (172.16.0.0 - 172.31.255.255)
192.168.0.0/16    (192.168.0.0 - 192.168.255.255)

Private IPs:

Used inside networks
Not routable on internet
Can be reused (your home, my home, both use 192.168.1.x)

Public IPs:

Unique across entire internet
Routable on internet
Must be obtained from ISP or cloud provider

AWS Example:

# Private IP (VPC internal)
ec2.run_instances(
    ImageId='ami-xxxxx',
    InstanceType='t3.micro',
    SubnetId=private_subnet_id,  # Gets private IP automatically
    MaxCount=1,
    MinCount=1
)

# Public IP (internet-accessible)
allocation = ec2.allocate_address(Domain='vpc')
public_ip = allocation['PublicIp']

# Associate public IP with instance
ec2.associate_address(
    InstanceId=instance_id,
    AllocationId=allocation['AllocationId']
)

Your EC2 instance now has:

Private IP: 10.0.1.50 (internal VPC communication)
Public IP: 54.123.45.67 (internet communication)

ARP: Address Resolution Protocol

ARP links Layer 3 (IP addresses) to Layer 2 (MAC addresses).

The Problem:

Your computer knows the destination IP address. But it needs the MAC address to send the frame.

The Solution: ARP

ARP resolves IP addresses to MAC addresses.

How ARP Works

Scenario:

Host A: 10.1.1.22 (MAC: AA:AA)
Host B: 10.1.1.33 (MAC: BB:BB)

Host A wants to send to Host B but does not know BB:BB MAC address.

Step 1: ARP Request (Broadcast)

Host A sends:

ARP Request:
Who has 10.1.1.33?
Tell 10.1.1.22 at MAC AA:AA

Layer 2 Header:
Source MAC: AA:AA
Destination MAC: FF:FF:FF:FF:FF:FF (broadcast)

Broadcast means everyone on the network receives it.

Step 2: Host B Responds

Host B sees the request:

"That is my IP (10.1.1.33). I will respond."

Host B sends:

ARP Response:
10.1.1.33 is at MAC BB:BB

Layer 2 Header:
Source MAC: BB:BB
Destination MAC: AA:AA (unicast - directly to Host A)

Step 3: Host A Updates ARP Cache

Host A stores:

ARP Cache:
10.1.1.33 → BB:BB

Now Host A can send data directly to Host B.

Future communication:

Host A already has BB:BB in its ARP cache. No ARP needed. Send immediately.

View Your ARP Cache

Linux/Mac:

$ arp -a

Output:

? (10.1.1.1) at e4:e4:e4:e4:e4:e4 on en0 ifscope [ethernet]
? (10.1.1.33) at bb:bb:bb:bb:bb:bb on en0 ifscope [ethernet]

Windows:

C:\> arp -a

This shows all IP to MAC mappings your computer learned.

Python example:

import subprocess
import re

def get_arp_table():
    """Get ARP table entries"""
    result = subprocess.run(['arp', '-a'], capture_output=True, text=True)

    entries = []
    for line in result.stdout.split('\n'):
        # Parse IP and MAC from output
        match = re.search(r'\((\d+\.\d+\.\d+\.\d+)\) at ([0-9a-f:]+)', line)
        if match:
            ip = match.group(1)
            mac = match.group(2)
            entries.append({'ip': ip, 'mac': mac})

    return entries

# Get and display ARP table
arp_table = get_arp_table()
for entry in arp_table:
    print(f"{entry['ip']} → {entry['mac']}")

DNS: Domain Name System

DNS converts human-readable names to IP addresses.

The Problem:

Humans think in names: aws.amazon.com

Computers need IP addresses: 52.94.133.131

The Solution: DNS

DNS translates names to IP addresses automatically.

How DNS Works

Example: Browsing to www.google.com

Step 1: Browser Checks Cache

Your computer checks: "Do I already know google.com's IP?"

If yes: Use cached IP.
If no: Continue to Step 2.

Step 2: Query DNS Server

Your computer asks DNS server:

Query: What is the IP address for www.google.com?

Step 3: DNS Server Responds

Response: www.google.com is at 142.250.80.46

Step 4: Browser Connects

Browser now connects to 142.250.80.46 using HTTP/HTTPS.

You never saw the IP address. But it was used.

DNS in Python

import socket

# Resolve domain name to IP
hostname = 'aws.amazon.com'
ip_address = socket.gethostbyname(hostname)

print(f"{hostname} → {ip_address}")

Output:

aws.amazon.com → 52.94.133.131

Reverse DNS (IP to hostname):

import socket

# Resolve IP to hostname
ip = '8.8.8.8'
hostname = socket.gethostbyaddr(ip)

print(f"{ip} → {hostname[0]}")

Output:

8.8.8.8 → dns.google

DNS in AWS: Route 53

Route 53 is AWS's DNS service.

Create DNS record:

import boto3

route53 = boto3.client('route53')

# Create A record (domain → IP)
response = route53.change_resource_record_sets(
    HostedZoneId='Z1234567890ABC',
    ChangeBatch={
        'Changes': [{
            'Action': 'CREATE',
            'ResourceRecordSet': {
                'Name': 'api.example.com',
                'Type': 'A',
                'TTL': 300,
                'ResourceRecords': [{'Value': '54.123.45.67'}]
            }
        }]
    }
)

print(f"Created DNS record: api.example.com → 54.123.45.67")

Now when users visit api.example.com, DNS returns your EC2 instance IP.

DHCP: Dynamic Host Configuration Protocol

DHCP automatically configures network settings on your computer.

The Problem:

Every host needs four settings:

IP Address
Subnet Mask
Default Gateway
DNS Server

Manually configuring these on every device is tedious.

The Solution: DHCP

DHCP server automatically assigns all four settings when you connect to a network.

How DHCP Works

Step 1: DHCP Discover

Your computer connects to network and broadcasts:

"Is there a DHCP server here?"

Step 2: DHCP Offer

DHCP server responds:

"Yes. Here are your settings:
- IP Address: 192.168.1.50
- Subnet Mask: 255.255.255.0
- Default Gateway: 192.168.1.1
- DNS Server: 8.8.8.8
Valid for 24 hours."

Step 3: DHCP Request

Your computer responds:

"I accept these settings."

Step 4: DHCP Acknowledge

DHCP server confirms:

"Confirmed. They are yours for 24 hours."

Your computer now has all four settings. You have internet.

The Four Things Every Host Needs

This is critical. Every host on the internet needs these four settings:

1. IP Address

Your identity on the network.

Example: 192.168.1.50

2. Subnet Mask

Defines your network size.

Example: 255.255.255.0 (or /24)

Tells you: "My network is 192.168.1.x"

3. Default Gateway

Router's IP address on your network.

Example: 192.168.1.1

Your way out to reach other networks.

4. DNS Server

Converts domain names to IP addresses.

Example: 8.8.8.8 (Google DNS)

Allows you to browse by name instead of IP.

View Your Network Settings

Linux/Mac:

$ ifconfig en0

Output:

en0: flags=8863<UP,BROADCAST,SMART,RUNNING,SIMPLEX,MULTICAST> mtu 1500
    inet 192.168.1.50 netmask 0xffffff00 broadcast 192.168.1.255

View gateway:

$ netstat -nr | grep default

Output:

default            192.168.1.1        UGSc           en0

View DNS servers:

$ cat /etc/resolv.conf

Output:

nameserver 8.8.8.8
nameserver 8.8.4.4

Windows:

C:\> ipconfig /all

Shows all four settings.

DHCP in AWS

AWS VPCs have built-in DHCP.

When you launch an EC2 instance, it automatically gets:

Private IP address (from subnet range)
Subnet mask (from subnet configuration)
Default gateway (VPC router)
DNS server (AWS-provided or custom)

Custom DHCP Options Set:

import boto3

ec2 = boto3.client('ec2')

# Create DHCP options set
dhcp_options = ec2.create_dhcp_options(
    DhcpConfigurations=[
        {
            'Key': 'domain-name-servers',
            'Values': ['8.8.8.8', '8.8.4.4']  # Use Google DNS
        },
        {
            'Key': 'domain-name',
            'Values': ['example.com']
        }
    ]
)

dhcp_options_id = dhcp_options['DhcpOptions']['DhcpOptionsId']

# Associate with VPC
ec2.associate_dhcp_options(
    DhcpOptionsId=dhcp_options_id,
    VpcId=vpc_id
)

print(f"Custom DHCP options applied to VPC")

Now all EC2 instances in this VPC use Google DNS instead of AWS default.

HTTP and HTTPS

HTTP (HyperText Transfer Protocol) is how web browsers communicate with web servers.

HTTP Request:

GET /index.html HTTP/1.1
Host: www.example.com
User-Agent: Mozilla/5.0

This is what your browser sends when you visit a website.

HTTP Response:

HTTP/1.1 200 OK
Content-Type: text/html
Content-Length: 1234

<html>
  <body>
    <h1>Welcome</h1>
  </body>
</html>

This is what the server sends back.

HTTP Methods

GET: Retrieve data

GET /api/users/123 HTTP/1.1

POST: Send data

POST /api/users HTTP/1.1
Content-Type: application/json

{"name": "John", "email": "john@example.com"}

PUT: Update data

PUT /api/users/123 HTTP/1.1
Content-Type: application/json

{"name": "John Updated"}

DELETE: Remove data

DELETE /api/users/123 HTTP/1.1

HTTP in Python

import requests

# GET request
response = requests.get('https://api.github.com/users/octocat')
print(f"Status: {response.status_code}")
print(f"Data: {response.json()}")

# POST request
data = {'name': 'Test Repository'}
response = requests.post(
    'https://api.github.com/user/repos',
    json=data,
    headers={'Authorization': 'token YOUR_TOKEN'}
)
print(f"Created: {response.json()['name']}")

HTTPS: HTTP Secure

HTTPS equals HTTP inside an encrypted tunnel (TLS/SSL).

How it works:

Step 1: TLS Handshake

Client and server establish encryption keys.

Step 2: Encrypted Tunnel

All HTTP traffic flows through encrypted tunnel.

Step 3: Data Exchange

[Encrypted] GET /api/data HTTP/1.1
[Encrypted] HTTP/1.1 200 OK

No one in the middle can read the data.

Port numbers:

HTTP: Port 80
HTTPS: Port 443

AWS Example:

Application Load Balancer with HTTPS:

import boto3

elbv2 = boto3.client('elbv2')

# Create HTTPS listener
response = elbv2.create_listener(
    LoadBalancerArn='arn:aws:elasticloadbalancing:...',
    Protocol='HTTPS',
    Port=443,
    Certificates=[{
        'CertificateArn': 'arn:aws:acm:us-east-1:...'
    }],
    DefaultActions=[{
        'Type': 'forward',
        'TargetGroupArn': 'arn:aws:elasticloadbalancing:...'
    }]
)

print("HTTPS listener created on port 443")

Your load balancer now handles HTTPS traffic with TLS encryption.

TCP and UDP

Layer 4 (Transport Layer) uses two protocols:

TCP (Transmission Control Protocol)

Reliable transmission:

Confirms delivery
Retransmits if lost
Guarantees order
Slower but reliable

Used for:

HTTP/HTTPS
SSH
Email (SMTP)
File transfers (FTP)

UDP (User Datagram Protocol)

Fast transmission:

No confirmation
No retransmission
No ordering guarantee
Faster but unreliable

Used for:

DNS queries
Video streaming
Online gaming
VoIP calls

When to use which:

Need reliability? Use TCP.
Need speed? Use UDP.

Protocol Summary

ARP (Layer 2):

Resolves IP to MAC
Used for local network communication
Broadcast request, unicast response

DNS (Layer 7):

Resolves domain names to IPs
Uses UDP port 53 (usually)
Critical for web browsing

DHCP (Layer 7):

Auto-configures network settings
Uses UDP ports 67/68
Provides IP, mask, gateway, DNS

HTTP (Layer 7):

Web communication
TCP port 80
Request/response model

HTTPS (Layer 7):

Secure web communication
TCP port 443
HTTP inside TLS tunnel

TCP (Layer 4):

Reliable transmission
Connection-oriented
Used by HTTP, SSH, FTP

UDP (Layer 4):

Fast transmission
Connectionless
Used by DNS, streaming

Complete AWS Networking Example

Let me tie everything together with a complete AWS setup:

import boto3

ec2 = boto3.client('ec2')

# 1. Create VPC (IP addressing)
vpc = ec2.create_vpc(CidrBlock='10.0.0.0/16')
vpc_id = vpc['Vpc']['VpcId']
print(f"VPC created: {vpc_id} with range 10.0.0.0/16")

# 2. Create subnet (subnet mask /24)
subnet = ec2.create_subnet(
    VpcId=vpc_id,
    CidrBlock='10.0.1.0/24',
    AvailabilityZone='us-east-1a'
)
subnet_id = subnet['Subnet']['SubnetId']
print(f"Subnet created: {subnet_id} with range 10.0.1.0/24")

# 3. Create Internet Gateway (default gateway)
igw = ec2.create_internet_gateway()
igw_id = igw['InternetGateway']['InternetGatewayId']
ec2.attach_internet_gateway(InternetGatewayId=igw_id, VpcId=vpc_id)
print(f"Internet Gateway created and attached: {igw_id}")

# 4. Create route table (routing)
route_table = ec2.create_route_table(VpcId=vpc_id)
rt_id = route_table['RouteTable']['RouteTableId']

# Add default route to Internet Gateway
ec2.create_route(
    RouteTableId=rt_id,
    DestinationCidrBlock='0.0.0.0/0',
    GatewayId=igw_id
)

# Associate with subnet
ec2.associate_route_table(RouteTableId=rt_id, SubnetId=subnet_id)
print(f"Route table created with default route to IGW")

# 5. Configure DHCP options (DNS)
dhcp_options = ec2.create_dhcp_options(
    DhcpConfigurations=[{
        'Key': 'domain-name-servers',
        'Values': ['8.8.8.8', '8.8.4.4']
    }]
)
dhcp_id = dhcp_options['DhcpOptions']['DhcpOptionsId']
ec2.associate_dhcp_options(DhcpOptionsId=dhcp_id, VpcId=vpc_id)
print(f"DHCP options configured with Google DNS")

# 6. Create security group (Layer 4 rules)
sg = ec2.create_security_group(
    GroupName='web-server-sg',
    Description='Allow HTTP and HTTPS',
    VpcId=vpc_id
)
sg_id = sg['GroupId']

# Allow HTTPS (TCP port 443)
ec2.authorize_security_group_ingress(
    GroupId=sg_id,
    IpPermissions=[
        {
            'IpProtocol': 'tcp',
            'FromPort': 443,
            'ToPort': 443,
            'IpRanges': [{'CidrIp': '0.0.0.0/0'}]
        },
        {
            'IpProtocol': 'tcp',
            'FromPort': 80,
            'ToPort': 80,
            'IpRanges': [{'CidrIp': '0.0.0.0/0'}]
        }
    ]
)
print(f"Security group created allowing HTTP/HTTPS")

# 7. Launch EC2 instance
response = ec2.run_instances(
    ImageId='ami-0c55b159cbfafe1f0',  # Amazon Linux 2
    InstanceType='t3.micro',
    SubnetId=subnet_id,
    SecurityGroupIds=[sg_id],
    MinCount=1,
    MaxCount=1
)

instance_id = response['Instances'][0]['InstanceId']
print(f"EC2 instance launched: {instance_id}")

# The instance automatically gets via DHCP:
# - IP: 10.0.1.x (from subnet range)
# - Subnet Mask: 255.255.255.0 (/24)
# - Gateway: 10.0.1.1 (VPC router)
# - DNS: 8.8.8.8, 8.8.4.4 (from DHCP options)

This creates a complete working network with all the concepts we covered.

Troubleshooting Checklist

Problem: "Cannot reach internet from EC2 instance"

Check 1: Does instance have IP address?

$ aws ec2 describe-instances --instance-ids i-xxxxx

Look for PrivateIpAddress field.

Check 2: Does subnet have route to Internet Gateway?

$ aws ec2 describe-route-tables --filters "Name=association.subnet-id,Values=subnet-xxxxx"

Look for route: 0.0.0.0/0 → igw-xxxxx

Check 3: Does instance have public IP (if needed)?

$ aws ec2 describe-instances --instance-ids i-xxxxx

Look for PublicIpAddress field.

Check 4: Do security groups allow traffic?

$ aws ec2 describe-security-groups --group-ids sg-xxxxx

Check outbound rules allow destination ports.

Check 5: Can instance resolve DNS?

$ ssh ec2-user@instance
$ nslookup google.com

Should return IP address.

Key Takeaways

IP Addresses:

32-bit identifiers (IPv4)
Organized hierarchically
Public vs private ranges

Subnet Masks:

Define network size
/24 = 254 hosts
/16 = 65,534 hosts
Help determine local vs foreign

Four Things Every Host Needs:

IP Address (identity)
Subnet Mask (network size)
Default Gateway (way out)
DNS Server (name resolution)

Essential Protocols:

ARP: IP to MAC resolution
DNS: Name to IP resolution
DHCP: Auto-configuration
HTTP/HTTPS: Web traffic
TCP: Reliable transport
UDP: Fast transport

AWS provides all of these automatically in VPCs.

What Comes Next: Part 4

You now understand IP addresses, protocols, and how everything is configured.

Part 4 ties it all together with a complete data flow example.

In Part 4, I will show:

Complete packet journey from your browser to AWS
Every protocol in action
Every header at every layer
Every table lookup
How DNS, ARP, routing, and switching work together
Real-world troubleshooting scenario

Coming next.

Your Turn

What networking concept still confuses you?

Are there protocols I should cover in more detail?

Drop a comment. I am building this series based on your questions.

This series:

Part 1: OSI Model Explained
Part 2: Switches and Routers
Part 3: IP Addresses and Protocols (this article)
Part 4: Complete Data Flow (next)

Follow me for the final part and daily AWS learning.

Resources

Practice Labs:

AWS Documentation:

RFCs (Official Specs):

This is Part 3 of a 4-part series on Networking Fundamentals for Cloud Engineers.

How Parallel Universe DB on Tiger Cloud’s Agentic Postgres Cuts Query Costs to $0.02

Stella Achar Oiro — Sat, 08 Nov 2025 09:04:01 +0000

This is a submission for the Agentic Postgres Challenge with Tiger Data

What if your database could exist in multiple realities?

Database optimization is expensive and scary. Create a full clone (30+ minutes, $12+), test a fix, pray it works. If it doesn't? Start over.

What if you could test 4 different optimization strategies on real database forks, watch intelligent agents compete to find the best solution, and promote the winner to production—all in under 10 minutes for $0.02?

That's Parallel Universe Database, built for the Agentic Postgres Challenge using Tiger Cloud's revolutionary zero-copy fork technology.

Key Innovation: No paid AI APIs required. Agents use intelligent rule-based strategies powered by PostgreSQL's built-in analysis tools.

Demo Video

What you'll see:

Querry
Four optimization agents spawn sequentially
Real-time performance metrics
Winner crowned
One-click promotion to production
Cost comparison

Live Demo

Try it yourself

GitHub

The Problem I'm Solving

Traditional database optimization forces impossible trade-offs:

Full clones take 15-30+ minutes and cost $12+ each
Testing multiple strategies means multiple clones ($47.50 for 4 strategies)
Production testing is risky - one bad change can bring down your app
Most teams only test one approach due to cost and time constraints

Example: You have a slow email lookup query. Should you add an index? Rewrite the query? Create a materialized view? Optimize the schema? You can only afford to test one.

How Parallel Universe Database Solves This

1. Describe Your Problem

Simple UI where you describe your performance issue:

"Slow queries on users table with email lookups taking over 200ms"

Select which optimization strategies to test:

Index Optimization
Query Rewriting
Caching Strategy
Schema Optimization

2. Instant Fork Creation (Free Tier Compatible!)

// backend/src/routes/optimize.js
for (let i = 0; i < selectedStrategies.length; i++) {
  const strategy = selectedStrategies[i];

  // Create fork (~2 seconds)
  const fork = await tigerService.createFork(`universe-${universeName}`);

  // Run agent on isolated fork
  const agent = new AgentClass(fork.connectionString, fork.id);
  const result = await agent.optimize(problemDescription);

  // Delete fork immediately (stay within free tier limits!)
  await tigerService.deleteFork(fork.id);

  results.push(result);
}

How it works:

Tiger Cloud's zero-copy forks create in ~2 seconds (vs 30+ minutes)
Sequential execution: Create → Test → Delete → Repeat
Each agent gets a real isolated database fork
Free tier compatible: Only 1 fork exists at a time (2 services total: main + 1 fork)

Total time: 8-10 minutes for 4 agents
Total cost: $0.02 vs $47.50 traditional

3. Intelligent Agents Test Strategies

Four specialized agents run sequentially, each on its own isolated fork:

IndexAgent

What it does:

// Analyzes pg_stat_statements for slow queries
const slowQueries = await this.findSlowQueries();

// Rule-based recommendations
const recommendations = await this.getIndexRecommendations(analysis);
// Example: "High sequential scans on users table → B-tree index on email column"

// Creates and tests indexes
await this.applyIndexes(recommendations);

// Benchmarks improvement
const improvement = this.calculateImprovement(before, after);

Strategy:

Scans pg_stat_statements for slow queries
Identifies tables with high sequential scan rates
Creates B-tree, GIN, GiST, or BRIN indexes based on column types
Benchmarks before/after performance

Typical result: 60-90% improvement

QueryAgent

What it does:

// Gets execution plan
const plan = await client.query(`EXPLAIN ANALYZE ${query}`);

// Identifies bottlenecks (seq scans, nested loops, sorts)
const bottlenecks = this.analyzeExecutionPlan(plan);

// Applies rule-based optimizations
// - Replace subqueries with CTEs
// - Optimize JOIN order
// - Add LIMIT clauses
// - Use EXISTS instead of IN for large datasets
const optimizedQuery = this.rewriteQuery(originalQuery, bottlenecks);

Strategy:

Uses EXPLAIN ANALYZE to identify bottlenecks
Applies database optimization best practices
Tests different query patterns
Measures execution time improvements

Typical result: 40-75% improvement

CacheAgent

What it does:

Identifies frequently accessed queries in pg_stat_statements
Creates materialized views for expensive aggregations
Implements smart refresh strategies
Reduces query load on main tables

Typical result: 50-90% improvement

SchemaAgent

What it does:

Analyzes table structures and constraints
Runs ANALYZE to update statistics
Adds optimal constraints (NOT NULL, CHECK)
Runs VACUUM for storage optimization
Improves query planner decisions

Typical result: 30-60% improvement

4. Real-Time Competition

Watch agents compete with live updates:

// frontend/src/components/UniverseCard.jsx
<motion.article
  className={isWinner ? 'border-yellow-500 shadow-glow' : 'border-gray-700'}
  aria-label={`Universe ${universe.id}`}
>
  {isWinner && (
    <motion.div
      className="text-4xl"
      initial={{ scale: 0 }}
      animate={{ scale: 1 }}
    >
      🏆
    </motion.div>
  )}

  <div className="text-2xl font-bold text-green-400">
    +{universe.improvement}%
  </div>

  <div className="text-lg font-semibold text-blue-400">
    {universe.executionTime}ms
  </div>

  <div className="text-sm text-gray-400">
    {universe.strategy}
  </div>
</motion.article>

Features:

Live progress indicators for each universe
Performance metrics update in real-time
Winner automatically crowned with 🏆
Beautiful Recharts visualization
Full keyboard navigation

5. One-Click Promotion

// Determine winner
const winner = universes.reduce((best, current) =>
  current.improvement > best.improvement ? current : best
);

// Promote to production (in transaction)
await tigerService.promoteFork(
  winner.forkId,
  winner.details.appliedChanges
);

Apply the winning optimization to production with one click. All changes execute in a transaction—if anything fails, everything rolls back.

Real-World Results

Test database:

100,000 users
500,000 orders
1,000,000 order items
1,000 products

Problem: Slow email lookup query taking 234ms

SELECT u.email, COUNT(o.id) as order_count, SUM(o.total) as total_spent
FROM users u
LEFT JOIN orders o ON u.id = o.user_id
WHERE u.email LIKE '%@gmail.com'
GROUP BY u.id, u.email
ORDER BY total_spent DESC;

Results:

Universe	Agent	Strategy	Time	Improvement
🏆 Alpha	IndexAgent	B-tree index on users.email	38ms	84%
Beta	QueryAgent	Optimized JOIN order + LIMIT	52ms	78%
Gamma	CacheAgent	Materialized view for aggregations	68ms	71%
Delta	SchemaAgent	ANALYZE + constraint optimization	82ms	65%

Cost: $0.02 to test all 4 strategies vs $47.50 for traditional cloning
Time: ~8 minutes vs 2+ hours traditional
Winner: IndexAgent with 84% improvement

Technical Architecture

┌─────────────────────────────────────────────┐
│        Frontend (React + Vite + Tailwind)   │
│  ┌─────────────────────────────────────┐   │
│  │  UniverseSpawner                    │   │
│  │  └─ Problem input + strategy select │   │
│  ├─────────────────────────────────────┤   │
│  │  Universe Cards (Real-time updates) │   │
│  │  └─ Framer Motion animations        │   │
│  ├─────────────────────────────────────┤   │
│  │  Performance Chart (Recharts)       │   │
│  ├─────────────────────────────────────┤   │
│  │  Cost Calculator                    │   │
│  └─────────────────────────────────────┘   │
└──────────────┬──────────────────────────────┘
               │ REST API
               ▼
┌─────────────────────────────────────────────┐
│        Backend (Node.js + Express)          │
│  ┌─────────────────────────────────────┐   │
│  │  POST /api/optimize                 │   │
│  │  1. Create forks (sequential)       │   │
│  │  2. Run agents on isolated forks    │   │
│  │  3. Delete forks (free tier compat) │   │
│  │  4. Determine winner                │   │
│  └─────────────────────────────────────┘   │
│  ┌─────────────────────────────────────┐   │
│  │  Intelligent Agents (Rule-Based)    │   │
│  │  ├─ IndexAgent (pg_stat_statements) │   │
│  │  ├─ QueryAgent (EXPLAIN ANALYZE)    │   │
│  │  ├─ CacheAgent (materialized views) │   │
│  │  └─ SchemaAgent (ANALYZE + VACUUM)  │   │
│  └─────────────────────────────────────┘   │
└──────────────┬──────────────────────────────┘
               │ Tiger CLI
               ▼
┌─────────────────────────────────────────────┐
│      Tiger Cloud (Agentic Postgres)         │
│  ┌─────────────────────────────────────┐   │
│  │ Sequential Fork Execution           │   │
│  │ Fork α → Test → Delete → Fork β ... │   │
│  └─────────────────────────────────────┘   │
│  ┌─────────────────────────────────────┐   │
│  │  Main Database (TimescaleDB)       │   │
│  │  - pg_stat_statements enabled      │   │
│  │  - Zero-copy fork support           │   │
│  └─────────────────────────────────────┘   │
└─────────────────────────────────────────────┘

Tech Stack

Frontend:

React 18 - Modern UI framework
Vite - Lightning-fast builds
Tailwind CSS - Utility-first styling
Framer Motion - Accessible animations
Recharts - Performance visualizations
Lucide React - Icons

Backend:

Express.js - RESTful API
pg (node-postgres) - PostgreSQL client
Tiger CLI - Fork management
dotenv - Environment configuration

Database:

Tiger Cloud (TimescaleDB/PostgreSQL 14+)
pg_stat_statements - Query performance tracking
Zero-copy fork technology

Deployment:

Frontend: Vercel (instant deploys, auto-scaling)
Backend: Render (free tier, auto-deploys from GitHub)
Database: Tiger Cloud (free tier with 2 concurrent services)

Why No AI APIs Are Needed

The Secret: PostgreSQL has everything we need built-in

// IndexAgent - Rule-based recommendations
async getIndexRecommendations(analysis) {
  const recommendations = [];

  // Rule 1: High sequential scans → Add B-tree index
  if (analysis.missingIndexes.length > 0) {
    analysis.missingIndexes.slice(0, 2).forEach(table => {
      recommendations.push({
        tableName: table.tablename,
        columnName: 'id', // or detected foreign keys
        indexType: 'btree',
        reason: `High sequential scan rate (${table.seq_scan} scans)`
      });
    });
  }

  // Rule 2: Text searches → GIN index with pg_trgm
  // Rule 3: Range queries on timestamps → BRIN index
  // Rule 4: JSON columns → GIN index

  return recommendations;
}

Agents use:

pg_stat_statements - Identifies slow queries
EXPLAIN ANALYZE - Shows query bottlenecks
pg_stat_user_tables - Finds tables needing indexes
Database best practices - Proven optimization patterns

Benefits:

No API costs
No rate limits
No external dependencies
Works offline
Consistent performance
Privacy-friendly (no data sent to third parties)

Technical Challenges & Solutions

Challenge 1: Free Tier Service Limits

Problem: Tiger Cloud free tier allows max 2 services (1 main + 1 fork), but we need to test 4 strategies.

Initial approach: Create all 4 forks in parallel
Error: You have reached your free service limit

Solution: Sequential execution

// Create → Optimize → Delete → Repeat
for (const strategy of strategies) {
  const fork = await createFork();      // Service #2 created
  await agent.optimize();               // Test strategy
  await deleteFork(fork.id);            // Service #2 deleted
  // Now we can create the next fork
}

Trade-off: 8-10 minutes total (vs 2-3 minutes parallel), but works perfectly on free tier!

Challenge 2: Fork Password Authentication

Problem: Tiger Cloud forks get unique passwords not exposed in CLI JSON output.

Error: password authentication failed for user "tsdbadmin"

Solution: Use --password-storage pgpass flag

tiger --password-storage pgpass service fork main --name test

This writes fork passwords to ~/.pgpass automatically, which we parse programmatically:

async getPasswordFromPgpass(hostname, port, database) {
  const content = await fs.readFile(`${process.env.HOME}/.pgpass`, 'utf-8');
  const lines = content.split('\n');

  // Parse format: hostname:port:database:username:password
  for (const line of lines) {
    const [h, p, d, u, password] = line.split(':');
    if (h === hostname && p === port && d === database) {
      return password;
    }
  }
  return null;
}

Challenge 3: SSL Certificate Hostname Mismatch

Problem: Forks get different hostnames, but SSL certs only valid for parent.

Error: Hostname/IP does not match certificate's altnames

Solution: Disable SSL hostname verification for forks

const pool = new Pool({
  connectionString: forkUrl,
  ssl: { rejectUnauthorized: false }
});

Note: This is acceptable for development. In production with properly configured certs, this wouldn't be necessary.

Challenge 4: CORS Configuration for Vercel Frontend

Problem: Deployed frontend on Vercel couldn't access backend on Render.

Error: No 'Access-Control-Allow-Origin' header is present

Solution: Proper CORS configuration

// backend/src/server.js
const allowedOrigins = [
  'http://localhost:5173',                     // Local dev
  'https://paralleluniversedb.vercel.app',    // Production
  process.env.FRONTEND_URL
].filter(Boolean);

app.use(cors({
  origin: function (origin, callback) {
    if (!origin) return callback(null, true);  // Allow no-origin requests
    if (allowedOrigins.indexOf(origin) !== -1) {
      callback(null, true);
    } else {
      callback(null, true);  // Permissive for now
    }
  },
  credentials: true,
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization']
}));

Challenge 5: Performance - Real vs Demo Mode

Problem: Real database operations take 20-40 seconds per agent. Too slow for demos.

Solution: Fast Mode environment variable

// .env
FAST_MODE=true

// backend/src/agents/IndexAgent.js
if (process.env.FAST_MODE === 'true') {
  // Return instant simulated results
  return {
    improvement: 60 + Math.random() * 30,  // 60-90%
    executionTime: Math.round(baselineTime * 0.3),
    strategy: 'Created B-tree indexes on high-traffic columns'
  };
}

// Otherwise, run real database operations
const analysis = await this.analyzeDatabase();
// ... full optimization process

Benefits:

Production/demos: Instant results (~2 seconds per agent)
Development: Real testing with actual database operations
Flexibility: Toggle via environment variable

Accessibility (WCAG AA Compliant)

Accessibility was built in from day one:

Semantic HTML:

<main id="main-content">
  <section aria-labelledby="spawner-title">
    <h2 id="spawner-title">Launch Parallel Universes</h2>

    <button
      onClick={handleLaunch}
      aria-label="Launch optimization universes"
      aria-busy={isLoading}
    >
      {isLoading ? 'Launching...' : 'Launch Universes'}
    </button>
  </section>
</main>

Keyboard Navigation:

// All interactive elements support keyboard
<button
  onClick={handleClick}
  onKeyDown={(e) => {
    if (e.key === 'Enter' || e.key === ' ') {
      e.preventDefault();
      handleClick();
    }
  }}
>

Screen Reader Support:

<div role="status" aria-live="polite" aria-atomic="true">
  Universe {universe.id}: {universe.status}
  {universe.improvement && `Improvement: ${universe.improvement}%`}
</div>

<table role="table" aria-label="Performance comparison results">
  <thead>
    <tr>
      <th scope="col">Universe</th>
      <th scope="col">Strategy</th>
      <th scope="col">Improvement</th>
      <th scope="col">Time</th>
    </tr>
  </thead>
</table>

Color Contrast:

All text: 4.5:1 minimum (WCAG AA)
Interactive elements: Clear focus indicators
Success (green): #10B981 on dark background
Warning (yellow): #FBBF24 on dark background

Results:

Fully keyboard navigable (Tab, Enter, Escape)
Screen reader tested (NVDA)
ARIA labels on all interactive elements
Semantic HTML throughout
Color contrast WCAG AA compliant

How to Run Locally

Prerequisites

Node.js 18+
PostgreSQL 14+ or Tiger Cloud account
(Optional) Tiger CLI for real fork testing

Quick Start

# 1. Clone repository
git clone https://github.com/Stella-Achar-Oiro/parallel-universe-db
cd parallel-universe-db

# 2. Setup database (local PostgreSQL)
createdb parallel_universe_db
psql parallel_universe_db < database/schema.sql
psql parallel_universe_db < database/seed.sql

# 3. Backend setup
cd backend
npm install
cp .env.example .env

# Edit .env:
# DATABASE_URL=postgresql://user:password@localhost:5432/parallel_universe_db
# TIGER_CLI_AVAILABLE=false  # Set to 'true' if you have Tiger CLI
# FAST_MODE=true              # Instant results for demos

# 4. Frontend setup
cd ../frontend
npm install

# 5. Run (2 terminals)
# Terminal 1 - Backend
cd backend && npm run dev

# Terminal 2 - Frontend
cd frontend && npm run dev

Visit http://localhost:5173 and watch the magic happen!

Using Real Tiger Cloud Forks

# 1. Install Tiger CLI
# See: https://docs.timescale.com/use-timescale/latest/services/create-a-service/

# 2. Get your Tiger Cloud service ID
tiger service list

# 3. Update .env
TIGER_SERVICE_ID=your-service-id
TIGER_CLI_AVAILABLE=true
FAST_MODE=false  # Use real database operations

# 4. Run as above

Free tier notes:

Allows 2 concurrent services (1 main + 1 fork)
Sequential execution works perfectly
Each fork tests in ~2-2.5 minutes
Total: ~8-10 minutes for 4 strategies

Future Enhancements

1. Hybrid Search (BM25 + Vector Embeddings)

-- Optimization history with semantic search
CREATE TABLE optimization_history (
    id SERIAL PRIMARY KEY,
    problem_description TEXT,
    strategy VARCHAR(50),
    improvement FLOAT,
    execution_time INT,
    applied_changes JSONB,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    embedding VECTOR(1536)  -- For semantic search
);

-- BM25 index for keyword matching
CREATE INDEX idx_optimization_history_bm25
    ON optimization_history
    USING GIN(to_tsvector('english', problem_description));

-- Vector index for semantic similarity
CREATE INDEX idx_optimization_history_vector
    ON optimization_history
    USING ivfflat(embedding vector_cosine_ops)
    WITH (lists = 100);

How it works:

User describes problem: "email lookups are slow"
BM25 finds keyword matches: "email", "lookup", "slow"
Vector search finds semantically similar: "user search performance"
Combine with RRF (Reciprocal Rank Fusion)
Show: "Similar to optimization #42 from last month (84% improvement)"

Impact: System learns from every optimization!

2. Persistent Agent Memory

class LearningIndexAgent extends IndexAgent {
  async selectStrategy(problemDescription) {
    // Query past optimizations
    const pastSuccesses = await db.query(`
      SELECT strategy, AVG(improvement) as avg_improvement
      FROM optimization_history
      WHERE agent = 'IndexAgent'
        AND to_tsvector('english', problem_description) @@
            to_tsquery('english', $1)
      GROUP BY strategy
      ORDER BY avg_improvement DESC
      LIMIT 3
    `, [problemDescription]);

    // Agents learn: "B-tree on email columns typically gives 80%+ improvement"
    return pastSuccesses[0]?.strategy || this.defaultStrategy;
  }
}

3. More Agent Types

PartitionAgent: Tests table partitioning strategies (by date, range, hash)
ConnectionPoolAgent: Optimizes connection pooling settings
VacuumAgent: Schedules automated maintenance (VACUUM, ANALYZE, REINDEX)
ReplicationAgent: Tests read replica configurations
SecurityAgent: Audits permissions and identifies security issues

4. WebSocket Real-Time Updates

// Replace REST polling with WebSocket streaming
io.on('connection', (socket) => {
  socket.on('start-optimization', async (problemDescription) => {
    for (const strategy of strategies) {
      socket.emit('universe-creating', { strategy });
      const fork = await createFork();

      socket.emit('universe-optimizing', { strategy, forkId });
      const result = await runAgent(fork);

      socket.emit('universe-complete', { strategy, result });
      await deleteFork(fork);
    }
  });
});

Benefits: True real-time updates without polling, lower latency, better UX

5. CI/CD Integration

# .github/workflows/test-migrations.yml
name: Test Database Migrations
on: [pull_request]

jobs:
  test-migrations:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Create Tiger Cloud fork
        run: |
          tiger service fork ${{ secrets.TIGER_SERVICE_ID }} \
            --name pr-${{ github.event.pull_request.number }} \
            --now

      - name: Run migrations on fork
        run: npm run migrate

      - name: Run tests on production-like data
        run: npm test

      - name: Delete fork
        if: always()
        run: tiger service delete pr-${{ github.event.pull_request.number }}

Impact: Test every migration on real production data without risk!

Why Parallel Universe DB

1. Solves Real Pain

Every developer has faced slow queries. This makes optimization:

Fast: 8-10 minutes vs 2+ hours traditional
Safe: Test on real forks without production risk
Cheap: $0.02 vs $47.50 (2,375x savings)
Smart: 4 strategies tested simultaneously
Accessible: No database expertise required

2. Novel Technical Approach

I haven't seen anyone combine:

Zero-copy forks for instant experimentation
Intelligent agent competition
Real-time visualization with Framer Motion
One-click promotion workflow
Free tier compatible (sequential execution)
No paid APIs required (rule-based intelligence)

3. Production-Ready

Deployed and live: Frontend on Vercel, Backend on Render
Free tier compatible: Works within Tiger Cloud limits
Graceful fallbacks: Demo mode when Tiger CLI unavailable
Error handling: Full transaction rollbacks on failure
CORS configured: Works across domains
Environment-based: Fast mode for demos, real mode for testing

4. Accessibility First

Most submissions ignore accessibility. Mine is WCAG AA compliant:

Full keyboard navigation
Screen reader tested
Semantic HTML
ARIA labels throughout
4.5:1 color contrast minimum
Focus indicators on all elements

5. Demonstrates Tiger Cloud's Power

Zero-copy forks enable:

Testing multiple strategies without cost explosion
Sequential execution within free tier limits
Real isolated environments for each test
Instant fork creation (~2 seconds vs 30+ minutes)

This is impossible with traditional PostgreSQL.

The Vision

Imagine this becoming standard for database optimization:

Junior Developer notices slow query
Parallel Universe DB automatically spawns 4 optimization tests
Agents compete on real forks, finding the best solution
Senior Developer reviews AI recommendations
One-click promotion to production
System learns from every optimization

Database optimization becomes:

Accessible to developers of all skill levels
Fast enough to do continuously
Safe enough to test wild ideas
Smart enough to find non-obvious solutions

This is the future. And it's powered by Tiger Cloud's Agentic Postgres.

What I Learned

1. Zero-Copy Forks Are Game-Changing

Before this challenge, I understood the theory. After building this, I felt the impact. The ability to create 4 test environments in 8 seconds instead of 2 hours fundamentally changes how you think about database experimentation.

2. Free Tier Constraints Drive Innovation

I initially designed for parallel execution (all 4 forks simultaneously). The free tier limit forced me to rethink this as sequential. The result is actually better - it works for everyone, demos clearly show the process, and the extra time is negligible compared to traditional approaches.

3. Accessibility Must Be Built In

You can't bolt accessibility on at the end. It requires:

Semantic HTML from the start
Keyboard navigation in every component
ARIA labels as you build
Screen reader testing throughout

Result: Lighthouse accessibility score of 94/100 with zero refactoring needed.

4. PostgreSQL Has Everything You Need

I started by integrating AI APIs for recommendations. Then I discovered PostgreSQL's built-in analysis tools are more than enough:

pg_stat_statements - Shows exactly what's slow
EXPLAIN ANALYZE - Reveals bottlenecks
pg_stat_user_tables - Identifies missing indexes

No AI API needed. Just PostgreSQL expertise encoded as rules.

Acknowledgments

Tiger Cloud - For making zero-copy forks accessible to everyone
TimescaleDB Team - For building on PostgreSQL with powerful extensions
PostgreSQL Community - For the amazing database that powers everything
DEV Community - For hosting this incredible challenge
Vercel & Render - For free deployment platforms that make demos possible

Your Thoughts?

I'd love to hear:

Would you use this for database optimization?
What other agent types would be useful?
What optimization problems do you face daily?

Drop a comment below

Making database optimization feel like magic with Tiger Cloud's Agentic Postgres

This is Part 2 of my 4-part series on Networking Fundamentals for Cloud Engineers.

Stella Achar Oiro — Fri, 07 Nov 2025 04:18:37 +0000

Stella Achar Oiro for AWS Community Builders

Nov 7 '25

How Switches and Routers Actually Work: The Three Tables That Run the Internet

#networking #aws #cloudcomputing #devops

Comments

13 min read

How Switches and Routers Actually Work: The Three Tables That Run the Internet

Stella Achar Oiro — Fri, 07 Nov 2025 04:13:36 +0000

Yesterday, I explained the OSI model and why each layer matters for AWS.

Today, I show you what switches and routers actually do.

Here is what clicked for me, Networking is not magic. It comes down to three tables and three actions.

That is it.

Once you understand these tables, you understand how data flows from your laptop to AWS and back.

Let me show you.

The Two Fundamental Devices

Before we dive into how they work, you need to understand what they do.

Switches: Move data WITHIN networks

Your home Wi-Fi? That is a network. All your devices (laptop, phone, printer) connect through a switch (often built into your router). The switch handles communication between devices on the same network.

Routers: Move data BETWEEN networks

Your home network is separate from AWS's network. A router connects these different networks. When you access AWS, your data travels through multiple routers to get there.

Key Difference:

Switches operate at Layer 2 (MAC addresses)
Routers operate at Layer 3 (IP addresses)

AWS Equivalent:

Switches = Traffic within a subnet
Routers = VPC Route Tables moving traffic between subnets

Let me show you exactly how each one works.

How Switches Work

A switch has one job: Forward data to the correct device within a network.

Scenario:

Network: 10.1.1.0/24

         [SWITCH]
        /  |  |  \
       /   |  |   \
     A    B  C    D

Host A: MAC AA:AA, IP 10.1.1.10
Host B: MAC BB:BB, IP 10.1.1.20
Host C: MAC CC:CC, IP 10.1.1.30
Host D: MAC DD:DD, IP 10.1.1.40

All four hosts connect to the same switch. They are all on the same network (10.1.1.x).

The MAC Address Table

Every switch maintains a MAC Address Table. This table maps switch ports to MAC addresses.

Initial State (Empty):

Port  |  MAC Address
------|-------------
(empty)

The switch learns this table dynamically as traffic flows.

Three Switch Actions

Every switch performs exactly three actions. That is all.

1. LEARN

When a frame arrives on a port, the switch examines the source MAC address and updates its table.

2. FLOOD

When the switch does not know where the destination MAC address is, it sends the frame out all ports (except the incoming port).

3. FORWARD

When the switch knows where the destination MAC address is, it sends the frame only to that specific port.

Let me show you these actions in a real example.

Complete Example: Host A → Host D

Step 1: Host A Sends Frame

Host A wants to send data to Host D.

Frame arrives at switch on Port 1:

Layer 2 Header:
- Source MAC: AA:AA
- Destination MAC: DD:DD

Step 2: Switch LEARNS

Switch sees frame arrived on Port 1 with Source MAC: AA:AA

MAC Address Table updates:

Port  |  MAC Address
------|-------------
1     |  AA:AA

Step 3: Switch Checks Destination

Switch looks for DD:DD in its table.

Port  |  MAC Address
------|-------------
1     |  AA:AA

DD:DD is not in the table.

Step 4: Switch FLOODS

Switch sends frame out all ports except Port 1:

Port 2 → Host B receives frame
- Checks destination MAC: DD:DD
- Not my MAC (BB:BB)
- Discards frame
Port 3 → Host C receives frame
- Checks destination MAC: DD:DD
- Not my MAC (CC:CC)
- Discards frame
Port 4 → Host D receives frame
- Checks destination MAC: DD:DD
- That is my MAC
- Accepts and processes frame

The Return Journey: Host D → Host A

Host D sends response back to Host A.

Step 1: Host D Sends Frame

Frame arrives at switch on Port 4:

Layer 2 Header:
- Source MAC: DD:DD
- Destination MAC: AA:AA

Step 2: Switch LEARNS

Switch sees frame arrived on Port 4 with Source MAC: DD:DD

MAC Address Table updates:

Port  |  MAC Address
------|-------------
1     |  AA:AA
4     |  DD:DD

Step 3: Switch Checks Destination

Switch looks for AA:AA in its table.

Port  |  MAC Address
------|-------------
1     |  AA:AA  ← Found it
4     |  DD:DD

AA:AA is on Port 1.

Step 4: Switch FORWARDS

Switch sends frame only to Port 1.

Hosts B and C do not receive this frame. The switch knows exactly where to send it.

Future Communication

All future communication between Host A and Host D is now efficient.

The switch knows both MAC addresses:

Port  |  MAC Address
------|-------------
1     |  AA:AA
4     |  DD:DD

Every frame between A and D goes directly to the correct port. No flooding needed.

VLANs: Virtual Networks on One Switch

A VLAN (Virtual LAN) divides one physical switch into multiple isolated networks.

Example:

Physical Switch with 8 ports

VLAN 10 (Engineering):
- Ports 1, 2, 3, 4

VLAN 20 (Sales):
- Ports 5, 6, 7, 8

How VLANs Work:

Each VLAN has its own MAC address table. Traffic in VLAN 10 cannot reach VLAN 20 (without a router).

VLAN 10 MAC Table:

Port  |  MAC Address
------|-------------
1     |  AA:AA
2     |  BB:BB

VLAN 20 MAC Table:

Port  |  MAC Address
------|-------------
5     |  CC:CC
6     |  DD:DD

Same three actions (Learn, Flood, Forward), just confined to specific ports.

AWS Equivalent:

VLANs are like subnets in a VPC. Each subnet isolates traffic. You need a router (or Route Table rules) to move traffic between subnets.

How Routers Work

A router has one job: Forward packets between different networks.

Scenario:

Network 1: 10.0.4.0/24    Network 2: 10.0.5.0/24    Network 3: 10.0.6.0/24

    Host A ←→ R1 ←→ R2 ←→ Host C

Host A:
- IP: 10.0.4.9
- MAC: AA:AA
- Gateway: 10.0.4.1

R1 (Router 1):
- Right interface: 10.0.4.1 (MAC: E4:E4)
- Left interface: 10.0.5.1 (MAC: E5:E5)

R2 (Router 2):
- Right interface: 10.0.5.2 (MAC: F5:F5)
- Left interface: 10.0.6.1 (MAC: F6:F6)

Host C:
- IP: 10.0.6.7
- MAC: CC:CC
- Gateway: 10.0.6.1

Host A and Host C are on different networks. They need routers to communicate.

The Routing Table

Every router maintains a routing table. This table maps destination networks to next hop instructions.

R1's Routing Table:

Network         |  Next Hop
----------------|---------------------------
10.0.4.0/24     |  Directly Connected (right interface)
10.0.5.0/24     |  Directly Connected (left interface)
10.0.6.0/24     |  via 10.0.5.2 (R2)

R2's Routing Table:

Network         |  Next Hop
----------------|---------------------------
10.0.5.0/24     |  Directly Connected (right interface)
10.0.6.0/24     |  Directly Connected (left interface)
10.0.4.0/24     |  via 10.0.5.1 (R1)

Critical Point:

If a destination network is not in the routing table, the router drops the packet. The routing table must be populated before traffic flows.

Three Ways to Populate Routing Tables

1. Directly Connected

When you configure an IP address on a router interface, the router automatically adds that network to its routing table.

R1 configured with:
- Right interface: 10.0.4.1/24
- Left interface: 10.0.5.1/24

Routing table automatically includes:
10.0.4.0/24 → Directly Connected
10.0.5.0/24 → Directly Connected

2. Static Routes

An administrator manually tells the router how to reach a network.

R1 manual configuration:
"To reach 10.0.6.0/24, send packets to 10.0.5.2"

Routing table now includes:
10.0.6.0/24 → Static, via 10.0.5.2

3. Dynamic Routes

Routers automatically share network information with each other using routing protocols (OSPF, BGP, EIGRP).

R1 tells R2: "I know about 10.0.4.0/24"
R2 tells R1: "I know about 10.0.6.0/24"

Both routers update their tables automatically.

AWS Equivalent:

VPC Route Tables work like routing tables. You populate them with:

Local routes (automatically added)
Static routes (you configure manually)
Dynamic routes (VPC peering, Transit Gateway)

Routers Also Have ARP Tables

Critical concept: Routers are just nodes with IP addresses.

Just like hosts, routers use ARP to map IP addresses to MAC addresses.

R1's ARP Table (initially empty):

IP Address  |  MAC Address
------------|-------------
(empty)

R2's ARP Table (initially empty):

IP Address  |  MAC Address
------------|-------------
(empty)

Routers populate ARP tables dynamically as needed, just like hosts do.

Complete Packet Flow: Host A → Host C

Now let me show you every step as a packet travels from Host A to Host C through two routers.

Step 1: Host A Prepares Packet

Host A has data for Host C (10.0.6.7).

Create Layer 3 header:

Source IP: 10.0.4.9 (Host A)
Destination IP: 10.0.6.7 (Host C)

Host A determines: Destination is foreign (10.0.6.x not equal to 10.0.4.x)

Must send to default gateway: 10.0.4.1 (R1)

Step 2: Host A ARPs for Gateway

Host A does not know the gateway's MAC address.

ARP Request:

Who has 10.0.4.1?
Tell 10.0.4.9 at MAC: AA:AA

R1 receives and responds:

10.0.4.1 is at MAC: E4:E4

Host A updates ARP table:

10.0.4.1 → E4:E4

Step 3: Host A Sends Packet to R1

Complete packet:

[Layer 2: AA:AA → E4:E4]          (to R1)
[Layer 3: 10.0.4.9 → 10.0.6.7]    (end-to-end)
[DATA]

Packet travels to R1.

Step 4: R1 Processes Packet

R1 receives packet on right interface.

Action 1: Remove Layer 2 header (purpose complete: reached R1)

Action 2: Check routing table

Destination IP: 10.0.6.7
Which network? 10.0.6.0/24

Routing table match:
10.0.6.0/24 → via 10.0.5.2 (R2)

Next hop IP: 10.0.5.2

Action 3: Need new Layer 2 header

Source MAC: E5:E5 (R1's left interface)
Destination MAC: ??? (need R2's MAC)

Problem: R1 does not know R2's MAC address.

Step 5: R1 ARPs for R2

ARP Request:

Who has 10.0.5.2?
Tell 10.0.5.1 at MAC: E5:E5

R2 receives and responds:

10.0.5.2 is at MAC: F5:F5

R1 updates ARP table:

10.0.5.2 → F5:F5

Step 6: R1 Forwards to R2

Packet with new Layer 2 header:

[Layer 2: E5:E5 → F5:F5]          (R1 to R2)
[Layer 3: 10.0.4.9 → 10.0.6.7]    (SAME)
[DATA]

Notice: Layer 3 header never changed.

Packet travels to R2.

Step 7: R2 Processes Packet

R2 receives packet on right interface.

Action 1: Remove Layer 2 header (purpose complete: reached R2)

Action 2: Check routing table

Destination IP: 10.0.6.7
Which network? 10.0.6.0/24

Routing table match:
10.0.6.0/24 → Directly Connected (left interface)

This is the final hop.

Action 3: Need new Layer 2 header

Source MAC: F6:F6 (R2's left interface)
Destination MAC: ??? (need Host C's MAC)

Problem: R2 does not know Host C's MAC address.

Step 8: R2 ARPs for Host C

ARP Request:

Who has 10.0.6.7?
Tell 10.0.6.1 at MAC: F6:F6

Host C receives and responds:

10.0.6.7 is at MAC: CC:CC

Host C also learns from the request and updates its ARP table:

10.0.6.1 → F6:F6

R2 updates ARP table:

10.0.6.7 → CC:CC

Step 9: R2 Delivers to Host C

Final packet:

[Layer 2: F6:F6 → CC:CC]          (R2 to Host C)
[Layer 3: 10.0.4.9 → 10.0.6.7]    (SAME)
[DATA]

Packet travels to Host C.

Step 10: Host C Processes Packet

Host C receives packet:

Remove Layer 2 header (arrived at correct NIC)
Remove Layer 3 header (arrived at correct host)
Process DATA

Return Traffic: Host C → Host A

Good news: All ARP tables now populated. Much faster journey back.

Host C Sends Response

[Layer 2: CC:CC → F6:F6]          (to R2)
[Layer 3: 10.0.6.7 → 10.0.4.9]    (response)
[DATA]

R2 Processes

Remove Layer 2 header.

Check routing table: Destination 10.0.4.9 matches 10.0.4.0/24 via 10.0.5.1

Already has ARP for 10.0.5.1 → E5:E5

Create new Layer 2 header immediately:

[Layer 2: F5:F5 → E5:E5]
[Layer 3: 10.0.6.7 → 10.0.4.9]
[DATA]

Send to R1.

R1 Processes

Remove Layer 2 header.

Check routing table: Destination 10.0.4.9 matches 10.0.4.0/24 Directly Connected

Already has ARP for 10.0.4.9 → AA:AA

Create new Layer 2 header immediately:

[Layer 2: E4:E4 → AA:AA]
[Layer 3: 10.0.6.7 → 10.0.4.9]
[DATA]

Send to Host A.

Host A Processes

Remove Layer 2 header. Remove Layer 3 header. Process response data.

Key Observations

1. Layer 3 Header Never Changes

Throughout entire journey:

Source IP: 10.0.4.9 (Host A)
Destination IP: 10.0.6.7 (Host C)

Constant from start to finish. This is end-to-end delivery (Layer 3's job).

2. Layer 2 Header Changes at Every Hop

Hop 1: Host A → R1

Layer 2: AA:AA → E4:E4

Hop 2: R1 → R2

Layer 2: E5:E5 → F5:F5

Hop 3: R2 → Host C

Layer 2: F6:F6 → CC:CC

This is hop-to-hop delivery (Layer 2's job).

3. Every Router Follows Same Process

Remove old Layer 2 header (hop complete)
Check routing table (where does this go?)
Determine next hop IP (from routing table)
ARP if needed (get next hop MAC)
Create new Layer 2 header (for next hop)
Forward packet

This process repeats at every router across the entire internet.

The Three Critical Tables

Understanding data flow equals understanding these three tables:

1. MAC Address Table (Switches)

Port → MAC Address mapping

Actions: Learn, Flood, Forward

Purpose: Move data within networks

2. ARP Table (Hosts and Routers)

IP Address → MAC Address mapping

Purpose: Resolve next hop MAC addresses

Populated: Dynamically as needed

3. Routing Table (Routers)

Network → Next Hop mapping

Purpose: Determine packet path

Populated: Directly connected, static, dynamic

AWS VPC Route Tables

AWS VPC Route Tables work exactly like router routing tables.

Example VPC Configuration:

import boto3

ec2 = boto3.client('ec2')

# Create VPC
vpc = ec2.create_vpc(CidrBlock='10.0.0.0/16')
vpc_id = vpc['Vpc']['VpcId']

# Create public subnet
public_subnet = ec2.create_subnet(
    VpcId=vpc_id,
    CidrBlock='10.0.1.0/24',
    AvailabilityZone='us-east-1a'
)
public_subnet_id = public_subnet['Subnet']['SubnetId']

# Create private subnet
private_subnet = ec2.create_subnet(
    VpcId=vpc_id,
    CidrBlock='10.0.2.0/24',
    AvailabilityZone='us-east-1a'
)
private_subnet_id = private_subnet['Subnet']['SubnetId']

# Create Internet Gateway
igw = ec2.create_internet_gateway()
igw_id = igw['InternetGateway']['InternetGatewayId']

# Attach Internet Gateway to VPC
ec2.attach_internet_gateway(
    InternetGatewayId=igw_id,
    VpcId=vpc_id
)

# Create route table for public subnet
public_route_table = ec2.create_route_table(VpcId=vpc_id)
public_rt_id = public_route_table['RouteTable']['RouteTableId']

# Add route to Internet Gateway
ec2.create_route(
    RouteTableId=public_rt_id,
    DestinationCidrBlock='0.0.0.0/0',
    GatewayId=igw_id
)

# Associate route table with public subnet
ec2.associate_route_table(
    RouteTableId=public_rt_id,
    SubnetId=public_subnet_id
)

Resulting Route Table:

Destination      |  Target
-----------------|------------------
10.0.0.0/16      |  local (VPC)
0.0.0.0/0        |  igw-xxxxx (Internet Gateway)

This works exactly like a router routing table:

10.0.0.0/16 → local means "directly connected" (traffic stays in VPC)
0.0.0.0/0 → igw-xxxxx means "default route" (send to Internet Gateway)

View Your VPC Route Tables

import boto3

ec2 = boto3.client('ec2')

# Get all route tables
route_tables = ec2.describe_route_tables()

for rt in route_tables['RouteTables']:
    print(f"\nRoute Table: {rt['RouteTableId']}")
    print(f"VPC: {rt['VpcId']}")
    print("\nRoutes:")

    for route in rt['Routes']:
        destination = route.get('DestinationCidrBlock', 'N/A')

        # Determine target
        if 'GatewayId' in route:
            target = route['GatewayId']
        elif 'NatGatewayId' in route:
            target = route['NatGatewayId']
        elif 'NetworkInterfaceId' in route:
            target = route['NetworkInterfaceId']
        else:
            target = 'local'

        print(f"  {destination} → {target}")

Output example:

Route Table: rtb-abc123
VPC: vpc-xyz789

Routes:
  10.0.0.0/16 → local
  0.0.0.0/0 → igw-123456

This is your router routing table in AWS.

Troubleshooting with Tables

When connectivity fails, check the three tables:

Problem: "EC2 instance in private subnet cannot reach internet"

Check 1: Routing Table

$ aws ec2 describe-route-tables --route-table-ids rtb-abc123

Look for:

0.0.0.0/0 → nat-xxxxx (NAT Gateway)

If missing: Private subnet needs route to NAT Gateway.

Check 2: Security Groups (Layer 4)

$ aws ec2 describe-security-groups --group-ids sg-abc123

Look for outbound rules allowing traffic.

Check 3: Network ACLs (Layer 4)

$ aws ec2 describe-network-acls --network-acl-ids acl-abc123

Look for rules allowing traffic in and out.

Problem: "Cannot connect two VPCs"

Check 1: VPC Peering Connection

$ aws ec2 describe-vpc-peering-connections

Verify status is active.

Check 2: Route Tables

Both VPCs need routes pointing to the peering connection:

VPC A Route Table:

10.1.0.0/16 → local
10.2.0.0/16 → pcx-xxxxx (peering connection)

VPC B Route Table:

10.2.0.0/16 → local
10.1.0.0/16 → pcx-xxxxx (peering connection)

If routes missing: Add them.

Real-World AWS Example

Scenario: Web application with public and private subnets

VPC: 10.0.0.0/16

Public Subnet: 10.0.1.0/24
- Web servers (EC2)
- Internet-facing load balancer
- Route to Internet Gateway

Private Subnet: 10.0.2.0/24
- Database servers (RDS)
- Application servers
- Route to NAT Gateway (for updates)

Public Subnet Route Table:

Destination      |  Target
-----------------|------------------
10.0.0.0/16      |  local
0.0.0.0/0        |  igw-xxxxx

Web servers can:

Talk to anything in VPC (10.0.0.0/16 → local)
Access internet (0.0.0.0/0 → Internet Gateway)

Private Subnet Route Table:

Destination      |  Target
-----------------|------------------
10.0.0.0/16      |  local
0.0.0.0/0        |  nat-xxxxx

Database servers can:

Talk to anything in VPC (10.0.0.0/16 → local)
Access internet through NAT (0.0.0.0/0 → NAT Gateway)
Cannot receive inbound internet traffic (NAT is one-way)

Traffic Flow: User → Web Server → Database

User (internet) → Internet Gateway → Public subnet web server
Web server (10.0.1.50) → Local route → Private subnet database (10.0.2.100)
Database response → Local route → Web server
Web server response → Internet Gateway → User

Each hop uses the routing table to determine next destination.

Key Takeaways

Switches (Layer 2):

Operate within networks
Use MAC Address Table
Three actions: Learn, Flood, Forward
AWS equivalent: Traffic within subnets

Routers (Layer 3):

Operate between networks
Use Routing Table and ARP Table
Forward packets based on destination network
AWS equivalent: VPC Route Tables

Layer 2 changes every hop. Layer 3 stays constant.

The three tables:

MAC Address Table (switches)
ARP Table (hosts and routers)
Routing Table (routers)

AWS VPC Route Tables work exactly like router routing tables.

What Comes Next: Part 3

You now understand how switches and routers move data. But what about the protocols that make it all work?

In Part 3, I will explain:

IP addresses and subnet masks
ARP, DNS, DHCP in detail
The four things every host needs
Network protocols (HTTP, HTTPS, TCP, UDP)
How it all works together in AWS

Your Turn

What networking concept still confuses you?

Drop a comment. I am building this series based on real questions from people studying AWS.

Following this series? You will also like:

Part 1: The OSI Model Explained
Part 3: IP Addresses and Protocols
Part 4: Complete Data Flow Example

I share daily AWS learning on Twitter/X, code examples on GitHub, and weekly deep dives on Substack.

Let me learn cloud networking with you.

Resources

AWS Documentation:

Hands-On Practice:

My Resources:

Part 1: OSI Model

This is Part 2 of a 4-part series on Networking Fundamentals for Cloud Engineers.

The OSI Model Explained: How Data Really Flows Through the Internet

Stella Achar Oiro — Thu, 06 Nov 2025 09:09:56 +0000

I am studying for my AWS certifications.

Everyone said: "Learn networking first."

So I dove into the OSI model. The concept clicked when I stopped trying to memorize layers and started understanding what problem each layer solves.

The OSI model is not something you memorize. It provides a framework for understanding how data moves from your laptop to AWS servers and back.

Here is what I wish someone told me on day one.

Why This Actually Matters for AWS

Before we dive in, let me explain why networking is not just theory.

You cannot configure AWS VPCs without understanding Layer 3 (IP addresses). You cannot write Security Group rules without understanding Layer 4 (ports). You cannot troubleshoot connectivity without understanding all 7 layers.

When you run this Python code:

import boto3

ec2 = boto3.client('ec2')
response = ec2.describe_instances()

That simple call uses all 7 layers of the OSI model. Let me show you how.

The Problem Networking Solves

Imagine two computers in the same room. How do they share data?

Before networking:

Walk to Computer A
Plug in USB drive
Copy files
Walk to Computer B
Plug in USB drive
Copy files

With networking:

Computers share data automatically across the room, building, city, or world. No walking required.

But how? That is where the OSI model comes in.

The OSI Model: 7 Layers, 7 Solutions

OSI = Open Systems Interconnection

Think of it like the human body. The skeletal system handles structure. The respiratory system handles breathing. The cardiovascular system handles blood flow. Each has a specific function. All work together and the human lives.

Networking is the same. Seven layers, each with specific function. All work together and data flows across the internet.

Let me show you each layer by explaining the problem it solves.

Layer 1: Physical Layer

The Problem: How do we transport bits?

Data on computers equals 1s and 0s (bits). Something must physically transport those bits from one place to another.

The Solution: Physical medium

What operates at Layer 1:

Ethernet cables (copper or fiber)
Wi-Fi (radio waves)
Bluetooth
Repeaters (amplify signals)
Hubs (multi-port repeaters)

Key Concept: Do not get hung up on "physical" in the name. Layer 1 equals anything that moves bits.

Cables are physical. Wi-Fi uses radio waves. Both accomplish the same goal: Move 1s and 0s from here to there.

AWS Example:

When you use AWS DirectConnect, you establish a dedicated physical connection (Layer 1) between your data center and AWS.

Layer 2: Data Link Layer

The Problem: How do we deliver data hop-to-hop?

Layer 1 moves bits on a wire. But data often travels through multiple devices:

Your Computer → Switch → Router → Another Router → Server

Each jump from one device to another equals one "hop."

The Solution: MAC addresses

MAC Address = 48-bit identifier

Every network card (NIC) has a unique MAC address.

Format: AA:BB:CC:DD:EE:FF

What operates at Layer 2:

Network Interface Cards (NICs)
Switches (forward data within networks)
Wi-Fi Access Cards

How Layer 2 Works

When your computer sends data to a router:

Layer 2 Header:
- Source MAC: AA:AA:AA:AA:AA:AA (your computer)
- Destination MAC: E5:E5:E5:E5:E5:E5 (router)

This header gets the data from your NIC to the router's NIC (one hop).

At the router, this Layer 2 header is removed and replaced with a new one for the next hop:

Layer 2 Header (new):
- Source MAC: E5:E5:E5:E5:E5:E5 (router)  
- Destination MAC: E6:E6:E6:E6:E6:E6 (next router)

Layer 2 changes at every hop.

AWS Example:

Your EC2 instance has an Elastic Network Interface (ENI). That is a Layer 2 network card with a MAC address.

Layer 3: Network Layer

The Problem: How do we deliver data end-to-end?

If Layer 2 handles each hop, what handles the complete journey from your laptop to a server across the internet?

The Solution: IP addresses

IP Address = 32-bit identifier (IPv4)

Format: 192.168.1.100 (4 octets, each 0-255)

What operates at Layer 3:

Routers (move data between networks)
Hosts (anything with an IP address)
Layer 3 switches

How Layer 3 Works

Your laptop accessing Google's server:

Your Computer: 192.168.1.100
Google Server: 8.8.8.8

Path: Your Computer → 5 routers → Google Server

Layer 3 header stays constant throughout the entire journey:

Layer 3 Header (constant):
- Source IP: 192.168.1.100 (you)
- Destination IP: 8.8.8.8 (Google)

This header never changes from start to finish. That is end-to-end delivery.

AWS Example:

When you create a VPC, you define Layer 3 addressing:

import boto3

ec2 = boto3.client('ec2')

vpc = ec2.create_vpc(CidrBlock='10.0.0.0/16')
print(f"VPC created with IP range: 10.0.0.0/16")

That 10.0.0.0/16 equals Layer 3 addressing for your entire VPC.

The Critical Question: Why Both?

"If Layer 3 handles end-to-end with IP addresses, why do we need Layer 2 MAC addresses?"

This confused me for weeks. Here is the answer.

They serve different purposes:

Layer 3 (IP addresses): End-to-end delivery
- Stays constant throughout journey
- Like destination address on envelope
Layer 2 (MAC addresses): Hop-to-hop delivery
- Changes at every router
- Like the truck driver who changes at each distribution center

Example journey: Your Laptop → Web Server

Your Laptop (IP: 192.168.1.100)
  ↓
Router 1 (IP: 192.168.1.1)
  ↓  
Router 2 (IP: 10.20.30.1)
  ↓
Web Server (IP: 142.250.80.46)

Layer 3 header (constant):

Source: 192.168.1.100
Destination: 142.250.80.46
[NEVER CHANGES]

Layer 2 headers (change at each hop):

Hop 1: Your Laptop → Router 1

Source MAC: [Your NIC]
Dest MAC: [Router 1's NIC]

Hop 2: Router 1 → Router 2

Source MAC: [Router 1's NIC]
Dest MAC: [Router 2's NIC]

Hop 3: Router 2 → Web Server

Source MAC: [Router 2's NIC]  
Dest MAC: [Server's NIC]

Both are necessary for different parts of the journey.

Layer 4: Transport Layer

The Problem: How do we distinguish different data streams?

Your computer runs multiple programs simultaneously:

Your Computer (IP: 192.168.1.100)
├── Web Browser (browsing)
├── Slack (chatting)
├── Spotify (music)
└── Email Client

All these programs use the same network card and the same IP address. They all send and receive data.

Question: When data arrives at your computer, how does it know which program gets it?

The Solution: Port numbers

Layer 4 uses port numbers to distinguish data streams.

Port number = 16-bit number (0-65,535)

Two types:

TCP ports: Reliable transmission (confirms delivery)
UDP ports: Fast transmission (no confirmation)

How Ports Work

Well-known server ports:

HTTP (web):         TCP port 80
HTTPS (secure web): TCP port 443
SSH (remote login): TCP port 22
DNS (name lookup):  UDP port 53

Client ports (random):

When you connect to a server:

Destination port = Server's well-known port
Source port = Random port your computer picks

Example: Browsing to aws.amazon.com

Your Computer → AWS Web Server

Source: 192.168.1.100:54321 (random port)
Destination: 142.250.80.46:443 (HTTPS)

Server's response:

Source: 142.250.80.46:443
Destination: 192.168.1.100:54321 (same random port)

Why random ports? This allows multiple connections to same server.

Tab 1 → aws.amazon.com (port 54321)
Tab 2 → aws.amazon.com (port 54322)
Tab 3 → aws.amazon.com (port 54323)

Different ports keep data streams separate.

AWS Example:

Security Group rules are Layer 4 rules:

# Allow HTTPS traffic (Layer 4: TCP port 443)
security_group_rule = {
    'IpProtocol': 'tcp',
    'FromPort': 443,
    'ToPort': 443,
    'IpRanges': [{'CidrIp': '0.0.0.0/0'}]
}

You are saying: "Allow TCP (Layer 4) on port 443 (Layer 4) from any IP (Layer 3)."

Layers 5-7: Application Layers

The Reality

The OSI model defines Layer 5 (Session Layer), Layer 6 (Presentation Layer), and Layer 7 (Application Layer).

In practice, modern networking combines these into one "Application Layer."

Why? Every application implements them differently. There is no strict separation anymore.

What You Need to Know

Layer 5: Session Management

Example: HTTP cookies that keep you logged in even when your IP changes

Layer 6: Data Formatting

Example: Encoding data as ASCII, JSON, or base64

Layer 7: Application Protocols

Example: HTTP, FTP, SMTP, DNS

AWS Example:

Application Load Balancer operates at Layer 7 (HTTP/HTTPS):

# Create Layer 7 load balancer
elb = boto3.client('elbv2')

load_balancer = elb.create_load_balancer(
    Name='my-application-lb',
    Type='application',  # Layer 7
    Scheme='internet-facing',
    IpAddressType='ipv4'
)

It can route based on HTTP headers (Layer 7), URL paths (Layer 7), and HTTP methods (Layer 7).

Encapsulation: How Layers Stack

When your application sends data, each layer adds its header:

APPLICATION:
  [DATA]
    ↓
LAYER 4 (Transport):
  [TCP Header: Ports] + [DATA] = SEGMENT
    ↓
LAYER 3 (Network):
  [IP Header: IPs] + [SEGMENT] = PACKET
    ↓  
LAYER 2 (Data Link):
  [Ethernet Header: MACs] + [PACKET] = FRAME
    ↓
LAYER 1 (Physical):
  FRAME → 1010101010... (bits on wire)

When data arrives, the process reverses (de-encapsulation):

LAYER 1: Bits received
    ↓
LAYER 2: Check MAC address (is this for me?)
         Remove Ethernet header
    ↓
LAYER 3: Check IP address (is this for me?)
         Remove IP header
    ↓
LAYER 4: Check port number (which program?)
         Remove TCP header
    ↓
APPLICATION: Process [DATA]

Real Example: Your boto3 Call Through All 7 Layers

Remember this from the beginning?

import boto3

ec2 = boto3.client('ec2')
response = ec2.describe_instances()

Here is what actually happens:

Layer 7 (Application):

boto3 constructs HTTPS API request and formats JSON data

Layer 6 (Presentation):

Encodes data as UTF-8 and prepares for encryption

Layer 5 (Session):

Manages TLS session with AWS and handles authentication tokens

Layer 4 (Transport):

Uses TCP for reliable delivery. Destination port: 443 (HTTPS). Source port: Random (e.g., 54321)

Layer 3 (Network):

Destination IP: AWS API endpoint (e.g., 52.94.133.131). Source IP: Your computer's public IP. Routed through internet

Layer 2 (Data Link):

Source MAC: Your computer's NIC. Dest MAC: Your router's NIC (first hop). Changes at each hop through internet

Layer 1 (Physical):

Bits transmitted over Wi-Fi or Ethernet. Travels through cables and radio waves

The response comes back through all 7 layers in reverse.

AWS VPC Through the OSI Lens

Let me map AWS networking services to OSI layers:

Layer 1 (Physical):

AWS DirectConnect (dedicated fiber connection)
Physical infrastructure (AWS manages)

Layer 2 (Data Link):

ENI (Elastic Network Interface)
MAC addresses on EC2 instances

Layer 3 (Network):

VPC CIDR blocks (10.0.0.0/16)
Subnets (10.0.1.0/24, 10.0.2.0/24)
Route Tables
Internet Gateway
NAT Gateway
VPC Peering

Layer 4 (Transport):

Security Groups (port rules)
NACLs (port-based filtering)

Layer 7 (Application):

Application Load Balancer
API Gateway
CloudFront (CDN)

Example VPC configuration:

import boto3

ec2 = boto3.client('ec2')

# Layer 3: Create VPC with IP range
vpc = ec2.create_vpc(CidrBlock='10.0.0.0/16')
vpc_id = vpc['Vpc']['VpcId']

# Layer 3: Create subnet  
subnet = ec2.create_subnet(
    VpcId=vpc_id,
    CidrBlock='10.0.1.0/24'
)
subnet_id = subnet['Subnet']['SubnetId']

# Layer 2: Create network interface (ENI)
eni = ec2.create_network_interface(
    SubnetId=subnet_id,
    Description='My application ENI'
)

# Layer 4: Create security group with port rules
sg = ec2.create_security_group(
    GroupName='web-server-sg',
    Description='Allow HTTPS',
    VpcId=vpc_id
)

# Allow Layer 4 (TCP port 443)
ec2.authorize_security_group_ingress(
    GroupId=sg['GroupId'],
    IpPermissions=[{
        'IpProtocol': 'tcp',
        'FromPort': 443,
        'ToPort': 443,
        'IpRanges': [{'CidrIp': '0.0.0.0/0'}]
    }]
)

Every AWS networking service maps to OSI layers.

Troubleshooting with OSI Layers

The OSI model provides your debugging framework. When something breaks, check layer by layer.

Problem: "I cannot reach my EC2 instance"

Layer 1: Is there network connectivity?

$ ip link show

Layer 2: Can you reach your default gateway?

$ arp -a

Layer 3: Can you route to the destination IP?

$ ping 10.0.1.50
$ traceroute 10.0.1.50

Layer 4: Is the port open?

$ telnet 10.0.1.50 443
$ nc -zv 10.0.1.50 443

Layer 7: Is the application responding?

$ curl -v https://your-instance.com

Most common AWS issues and their layers:

Cannot SSH to EC2: Layer 4 (Security Group blocking port 22)
VPC peering not working: Layer 3 (Route Table missing routes)
Load balancer failing: Layer 7 (Health check configuration)
Slow API responses: Layer 4 and 7 (Connection limits, timeouts)

Key Takeaways

Layer 1 (Physical): Transports bits (cables, Wi-Fi, DirectConnect)

Layer 2 (Data Link): Hop-to-hop delivery (MAC addresses, switches, ENIs)

Layer 3 (Network): End-to-end delivery (IP addresses, routers, VPCs)

Layer 4 (Transport): Service-to-service (ports, TCP and UDP, Security Groups)

Layers 5-7 (Application): Application protocols (HTTP, DNS, Load Balancers)

Layer 2 changes every hop. Layer 3 stays constant.

Both MAC and IP addresses are necessary for different parts of the journey.

Every AWS service maps to these fundamental networking concepts.

What Comes Next: Part 2

Now you understand the OSI model conceptually. But how do switches and routers actually work?

In Part 2, I will show you:

How switches learn MAC addresses and forward frames
How routers use routing tables to forward packets
The three critical tables that make networking work
Real examples with AWS VPC Route Tables

Your Turn

Learning networking for AWS? What confuses you most?

Drop a comment below. I am documenting my entire journey to AWS certifications, and I want to help you with concepts that are not clicking.

Found this helpful? Follow me for:

Part 2: Switches and Routers
Part 3: IP Addresses and Protocols
Part 4: Complete data flow from browser to AWS

I am also sharing daily AWS learning on Twitter/X, code examples on GitHub, and weekly deep dives on Substack.

Let me learn AWS networking with you.

Resources

Official Specs:

My Learning Resources:

This is Part 1 of a 4-part series on Networking Fundamentals for Cloud Engineers.

I Benchmarked 3 Go Concurrency Patterns. The "Fastest" One Would Destroy Production

Stella Achar Oiro — Tue, 04 Nov 2025 05:57:23 +0000

I spent this weekend building a benchmark suite to test Go concurrency patterns for healthcare APIs. I ran three different approaches through realistic load tests and collected real performance data.

The results shocked me.

The "naive" pattern—spawning a new goroutine for every request—was 4-5x faster than the "proper" worker pool pattern. It handled 11,000 requests per second while the worker pool managed only 2,100.

My first thought: "Did I break something?"

My second thought: "Wait... this is actually the problem."

Here's what I learned about Go concurrency, production systems, and why the fastest solution is often the worst choice.

🔗 Full code and benchmarks: github.com/Stella-Achar-Oiro/healthcare-api-benchmark

Why This Matters (Especially in Healthcare)

Healthcare APIs have unique constraints that make concurrency patterns critical:

Predictability over performance. When a nurse queries patient medication history during an emergency, the system needs to respond consistently. A response that takes 200ms 99% of the time but occasionally spikes to 5 seconds isn't acceptable. Lives depend on these milliseconds.

Resource control is compliance. HIPAA requires demonstrable control over patient data access. Uncontrolled goroutine spawning makes it nearly impossible to audit resource usage, track access patterns, or enforce rate limits properly.

Graceful degradation over catastrophic failure. A healthcare system that rejects 20% of requests during a spike is better than one that accepts all requests, runs out of memory, and crashes—taking down every connected system with it.

These requirements forced me to dig deeper into Go's concurrency patterns. What I found applies to any production system where reliability matters more than raw speed.

The Three Patterns I Tested

Pattern 1: Naive (The Anti-Pattern)

The simplest approach: spawn a goroutine for every incoming request.

func (h *NaiveHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    patientID := extractPatientID(r)

    // Spawn a new goroutine for EVERY request
    go h.processRequest(w, r, patientID)
}

func (h *NaiveHandler) processRequest(w http.ResponseWriter, r *http.Request, patientID string) {
    // Query database
    patient, err := h.db.QueryPatient(r.Context(), patientID)

    // Send response
    json.NewEncoder(w).Encode(patient)
}

Why developers write this:

It's dead simple
Feels "concurrent" and "Go-like"
Works perfectly in demos
Benchmarks show amazing numbers

Why it's dangerous:

Unbounded concurrency: No limit on goroutine count
Memory bomb: Each goroutine consumes ~2KB+ of stack space
Database exhaustion: Can spawn more goroutines than your database connection pool
Scheduler overhead: The Go scheduler struggles with thousands of competing goroutines
Cascading failures: One slow database query blocks resources for everyone

I've seen this pattern in production codebases. Usually written by developers coming from async/await backgrounds who treat goroutines like they're free. They're not.

Pattern 2: Worker Pool (The Production Pattern)

Fixed number of workers pulling jobs from a queue.

type WorkerPoolHandler struct {
    jobQueue    chan *job
    workers     int
    wg          sync.WaitGroup
}

func (h *WorkerPoolHandler) worker(id int) {
    for {
        select {
        case job := <-h.jobQueue:
            // Process job
            patient, err := h.db.QueryPatient(job.ctx, job.patientID)
            job.resultChan <- patient
        case <-h.ctx.Done():
            return
        }
    }
}

func (h *WorkerPoolHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    job := &job{
        ctx:        r.Context(),
        patientID:  extractPatientID(r),
        resultChan: make(chan *PatientResponse, 1),
    }

    // Try to enqueue
    select {
    case h.jobQueue <- job:
        // Queued successfully
    default:
        // Queue full - reject request
        http.Error(w, "service overloaded", http.StatusServiceUnavailable)
        return
    }

    // Wait for result
    response := <-job.resultChan
    json.NewEncoder(w).Encode(response)
}

Why this is better:

Bounded concurrency. You control exactly how many operations run simultaneously. If you set 20 workers, you get 20 goroutines. No surprises.

Graceful backpressure. When the system is overloaded, requests wait in the queue. If the queue fills up, you can reject new requests cleanly with a 503 status code. The client knows to retry later.

Predictable resource usage. You can calculate exactly how much memory the system needs. 20 workers × 2KB/goroutine + queue size × job size = predictable memory footprint.

Better database behavior. With 20 workers, you'll never open more than 20 database connections simultaneously. Your database connection pool can be sized appropriately.

Proper shutdown. You can wait for in-flight work to complete during deployments. Close the job queue, drain remaining jobs, then shutdown cleanly.

Pattern 3: Optimized (Worker Pool + sync.Pool)

Same worker pool but with object pooling to reduce allocations.

type OptimizedHandler struct {
    WorkerPoolHandler
    responsePool sync.Pool
}

func (h *OptimizedHandler) getResponse() *PatientResponse {
    resp := h.responsePool.Get().(*PatientResponse)

    // CRITICAL: Clear previous data (HIPAA compliance!)
    resp.Patient = nil
    resp.Error = ""

    return resp
}

func (h *OptimizedHandler) putResponse(resp *PatientResponse) {
    // Clear sensitive data before returning to pool
    resp.Patient = nil
    h.responsePool.Put(resp)
}

func (h *OptimizedHandler) processJob(job *job) {
    // Get pooled response object instead of allocating
    response := h.getResponse()
    defer h.putResponse(response)

    patient, err := h.db.QueryPatient(job.ctx, job.patientID)
    response.Patient = patient

    job.resultChan <- response
}

What sync.Pool does:

sync.Pool maintains a cache of reusable objects. Instead of allocating a new PatientResponse struct for every request, we reuse them. This reduces:

Heap allocations
Garbage collection pressure
Memory allocation latency
GC pause times

Healthcare-specific note: You MUST clear sensitive data before returning objects to the pool. Imagine pooling a response object that still contains patient data from the previous request. That's a HIPAA violation waiting to happen.

The Benchmark Setup

I built a load testing tool that simulates realistic healthcare API usage:

Database simulation: 50-100ms query latency (typical for indexed patient lookups) with a 5% random error rate (network timeouts, lock conflicts, etc.)

Load patterns:

Low load: 1,000 requests, 100 concurrent clients
High load: 10,000 requests, 1,000 concurrent clients
Sustained load: 50,000 requests, 500 concurrent clients

Metrics collected:

Throughput (requests/second)
Latency (min, mean, median, P95, P99, max)
Error rates
Memory allocations

Worker pool configuration: Intentionally small (20 workers, 100 job queue) to demonstrate behavior under pressure.

Test 1: Low Load (1,000 Requests)

The first test: 1,000 total requests with 100 concurrent clients.

Pattern	Throughput	Mean Latency	P99 Latency	Error Rate
Naive	1,115 req/s	75.87ms	100.06ms	5.80%
Worker Pool	260 req/s	364.94ms	423.70ms	5.30%
Optimized	261 req/s	363.06ms	417.51ms	4.70%

Naive wins. And it's not even close—4.3x higher throughput!

At this load, the naive pattern shines. It spawned ~100 goroutines to handle 100 concurrent clients. The system had plenty of resources, so everything just... worked.

The worker pools were slower because only 20 requests could process simultaneously. The other 80 waited in the queue. Queue wait time added latency.

But here's what the numbers don't show: The naive pattern used 5x more goroutines and had no mechanism to reject requests if the system was overloaded.

Test 2: High Load (10,000 Requests)

Now let's crank it up: 10,000 requests with 1,000 concurrent clients.

Pattern	Throughput	Mean Latency	P99 Latency	Error Rate	Goroutines
Naive	11,104 req/s	75.47ms	100.04ms	5.24%	~1,000
Worker Pool	2,124 req/s	148.47ms	568.99ms	88.29%	20
Optimized	2,248 req/s	144.95ms	565.86ms	88.75%	20

Wait... what?

The naive pattern got faster (10x higher throughput than low load). The worker pools had 88% error rates. Did I break something?

Nope. This is exactly what should happen.

Understanding the "Errors" (Plot Twist: They're Features)

Those 88% "errors" in the worker pool patterns aren't failures. They're rejections.

What happened:

1,000 concurrent clients started sending requests
Worker pool: 20 workers, 100 job queue = 120 requests can be "in flight"
Request #121 arrives → queue is full → rejected immediately
Result: 880 out of 1,000 requests rejected = 88% "error" rate

This is not a bug. This is the feature.

The worker pool said: "I can't handle this load safely. I'm returning 503 Service Unavailable. Please retry later."

The naive pattern said: "Sure! I'll spawn 1,000 goroutines to handle all of this!"

In production, which behavior do you want?

The Hidden Costs of "Winning"

The naive pattern handled all 10,000 requests and maintained low latency. But at what cost?

Goroutine count: 1,000 concurrent goroutines

Memory usage: ~2-4 MB just for goroutine stacks

Database connections: Potentially 1,000 simultaneous queries

Context switches: The Go scheduler juggling 1,000 competing goroutines

In my benchmark environment, this worked fine. The system had resources to spare.

But in production:

Scenario 1: Traffic Spike

Black Friday sale. 10,000 concurrent users. Naive pattern spawns 10,000 goroutines. Your 100-connection database pool is exhausted in milliseconds. Connections time out. Requests fail. Users see errors.

Scenario 2: Slow Query

A poorly-optimized patient search takes 30 seconds instead of 100ms. With naive pattern, each slow request holds a goroutine for 30 seconds. Soon you have 10,000 goroutines waiting. Memory exhausted. OOMKilled. Service down.

Scenario 3: Cascading Failure

Your API spawns 5,000 goroutines. Uses all database connections. Database starts rejecting new connections. Other services sharing that database start failing. Now your patient monitoring system is down. Your lab results service is down. Everything crashes because one service didn't implement backpressure.

Worker pools prevent all of these scenarios.

Test 3: Sustained Load (50,000 Requests)

One more test: 50,000 requests with 500 concurrent clients over ~30 seconds.

Pattern	Throughput	Mean Latency	Error Rate	Notes
Naive	6,179 req/s	75.75ms	4.92%	500 goroutines
Worker Pool	1,593 req/s	164.50ms	84.50%	Steady rejection
Optimized	1,547 req/s	167.09ms	83.95%	Steady rejection

Same pattern. Naive "wins" on throughput by spawning 500 goroutines. Worker pools maintain bounded concurrency by rejecting excess load.

sync.Pool effectiveness: 51% hit rate. About half the response objects came from the pool instead of fresh allocations. In a sustained production workload, this would significantly reduce GC pressure.

The Configuration Question

"But you only used 20 workers! What if you used 100 or 500?"

Exactly.

Worker pools require configuration. You need to choose:

Number of workers
Queue size
Timeout behavior
Rejection strategy

I intentionally undersized the pool to demonstrate the behavior. In production, you'd size it based on:

For I/O-bound work (database queries):

workers = num_cpu_cores × 2 to 4
queue_size = workers × 5

For CPU-bound work:

workers = num_cpu_cores
queue_size = workers × 2

For our healthcare API:
With 8 cores, I'd start with 30 workers and a queue of 150. Monitor queue depth in production. Adjust based on observed traffic patterns.

The naive pattern has no knobs to turn. It just spawns goroutines until something breaks.

When to Use Each Pattern

Never Use Naive in Production

I'm saying this explicitly: Don't use the naive pattern in production systems.

"But it's so much faster!"

It's faster until it's not. And when it fails, it fails catastrophically.

The only acceptable use cases:

Prototypes and demos
Scripts that process finite, small datasets
CLI tools with known upper bounds

Use Worker Pools for Most Services

Worker pools should be your default for any production service:

REST APIs
Background job processors
Message queue consumers
gRPC services
WebSocket handlers

The configuration overhead is worth it for:

Predictable resource usage
Graceful degradation
Proper monitoring
Clean shutdown behavior

⚡ Use Optimized Pattern for High-Throughput Services

Add sync.Pool when:

You're processing >1,000 requests/second
P99 latency matters for SLAs
You have hot objects allocated repeatedly
Profiling shows allocation pressure

Healthcare-specific guidance:

Patient-facing APIs → Optimized pattern
Internal admin tools → Worker pool
Batch reporting jobs → Worker pool with larger queue
Real-time monitoring → Optimized pattern

Key Takeaways

1. Raw throughput isn't everything.

The naive pattern had 4-5x higher throughput but spawned 1,000 goroutines. In production, that's a memory bomb waiting to explode.

2. Errors can be features.

The 88% "error rate" was the system correctly rejecting load it couldn't handle safely. Better to reject requests than crash the entire service.

3. Configuration is control.

Worker pools require tuning. That's not a weakness—it's a feature. You get to decide your system's limits instead of discovering them during an outage.

4. Test under realistic load.

At low load, the naive pattern looked perfect. At high load, the problems became obvious. Always benchmark at the scale you expect in production.

5. Healthcare systems need predictability.

Fast response times with unpredictable spikes are worse than consistent, controlled behavior. Patient care depends on reliability.

6. sync.Pool isn't magic.

My 51% hit rate shows the pool was working but not optimal. In sustained production load with proper warmup, you'd see 80-90% hit rates. But it's not worth the complexity unless you're handling high throughput.

7. The Go scheduler is amazing... to a point.

Go can handle thousands of goroutines efficiently. But "can handle" doesn't mean "should use." Bounded concurrency is still the right pattern for production systems.

Try It Yourself

All the code, benchmarks, and documentation are open source:

Repository: github.com/Stella-Achar-Oiro/healthcare-api-benchmark

Run the benchmarks on your machine:

git clone https://github.com/Stella-Achar-Oiro/healthcare-api-benchmark.git
cd healthcare-api-benchmark
go run cmd/loadtest/main.go -requests=10000 -concurrency=1000

Try different configurations:

# Test with more workers
go run cmd/loadtest/main.go -workers=100 -queue-size=500

# Test with different load patterns
go run cmd/loadtest/main.go -requests=50000 -concurrency=500

Final Thoughts

Building this benchmark taught me that engineering isn't about finding the "best" solution. It's about understanding tradeoffs.

The naive pattern isn't wrong because it's slow—it's wrong because it's unpredictable. The worker pool pattern isn't better because it's faster—it's better because you control what happens under load.

In healthcare technology, and in production systems generally, predictable failure beats unpredictable catastrophe every single time.

Choose your concurrency pattern based on what you need your system to do when things go wrong. Because in production, things always go wrong.

What concurrency patterns do you use? Have you been burned by unlimited goroutine spawning? Drop a comment below—I'd love to hear your war stories.

If you found this useful, follow me for more Go, Kubernetes, and healthcare tech content. I'm building in public and sharing what I learn.

Stella Achar Oiro is a software developer combining clinical healthcare experience with cloud-native development. She builds healthcare technology with Go, Kubernetes, and AWS, and writes about the intersection of medicine and code.

Connect: GitHub | LinkedIn | DEV.to

[Boost]

Stella Achar Oiro — Sun, 03 Aug 2025 16:13:46 +0000

How to Build a Production Flask API CI/CD Pipeline on AWS with GitHub Actions

Stella Achar Oiro for AWS Community Builders ・ Aug 3 '25

How to Build a Production Flask API CI/CD Pipeline on AWS with GitHub Actions

Stella Achar Oiro — Sun, 03 Aug 2025 16:13:29 +0000

When I built my first Flask API, I wanted to automate everything, tests, builds, deployments.

But Jenkins was overwhelming.

Too many plugins. Too much setup. Too much YAML.

When you’re building your first production CI/CD pipeline, sometimes the simplest path forward is the best one.

That’s why I built my pipeline using GitHub Actions + AWS CodeDeploy, no Jenkins, no headaches.

This guide demonstrates how to build a fully functional Flask API with complete AWS deployment automation using a hybrid approach, AWS native deployment tools combined with GitHub Actions for the build pipeline. You will learn to set up automated testing, deployment, and production-ready infrastructure that scales efficiently.

Prerequisites

Before following this guide, ensure you have:

An AWS account with administrative access
A GitHub account for repository hosting
Basic knowledge of Git, AWS Console, and command line tools
Python 3.9 or later installed locally

Understanding the Architecture

The pipeline uses a hybrid approach that combines GitHub Actions for building and testing with AWS services for deployment:

GitHub Repository → GitHub Actions (Build/Test) → AWS CodeDeploy → EC2 Instance

This architecture provides GitHub's reliable build environment while leveraging AWS native deployment tools for production infrastructure.

Set Up IAM Permissions

Proper IAM configuration prevents most AWS deployment failures. Create an IAM user with these managed policies:

AWSCodeCommitFullAccess
AWSCodeDeployFullAccess
AWSCodePipelineFullAccess
AmazonEC2FullAccess

Configure Git credentials for CodeCommit:

$ aws configure set region us-east-1
$ git config --global credential.helper '!aws codecommit credential-helper $@'
$ git config --global credential.UseHttpPath true

Create the Flask Application

Build a production-ready Flask API with proper structure:

# app.py
from flask import Flask, jsonify

app = Flask(__name__)

@app.route('/health')
def health():
    return jsonify({'status': 'healthy', 'version': '1.0.0'})

@app.route('/api/users')
def users():
    return jsonify({'users': [{'id': 1, 'name': 'John'}, {'id': 2, 'name': 'Jane'}]})

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

Create a requirements file:

Flask==2.3.3
gunicorn==21.2.0

Configure GitHub Actions for CI/CD

Create the GitHub Actions workflow file:

# .github/workflows/deploy.yml
name: Deploy Flask API to AWS
on:
  push:
    branches: [main]

jobs:
  test-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'

      - name: Install dependencies and test
        run: |
          pip install -r requirements.txt
          python -m pytest tests/ || echo "No tests found, skipping"

      - name: Deploy to AWS CodeDeploy
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_DEFAULT_REGION: us-east-1
        run: |
          aws deploy create-deployment \
            --application-name flask-api \
            --deployment-group-name production \
            --github-location repository=${{ github.repository }},commitId=${{ github.sha }}

This workflow runs tests and triggers AWS CodeDeploy automatically on every push to the main branch.

Test your GitHub Actions workflow locally using act before pushing to catch configuration errors early and save debugging time.

Set Up AWS CodeDeploy Configuration

Create the application specification file:

# appspec.yml
version: 0.0
os: linux
files:
  - source: /
    destination: /var/www/api
    overwrite: yes
permissions:
  - object: /var/www/api
    pattern: "**"
    owner: www-data
    group: www-data
    mode: 755
hooks:
  BeforeInstall:
    - location: scripts/install_dependencies.sh
      timeout: 300
      runas: root
  ApplicationStart:
    - location: scripts/start_server.sh
      timeout: 300
      runas: root
  ApplicationStop:
    - location: scripts/stop_server.sh
      timeout: 300
      runas: root

Create Deployment Scripts

Install Dependencies Script

#!/bin/bash
# scripts/install_dependencies.sh
yum update -y
yum install -y python3 python3-pip nginx

# Install CodeDeploy agent
yum install -y ruby wget
cd /home/ec2-user
wget https://aws-codedeploy-us-east-1.s3.us-east-1.amazonaws.com/latest/install
chmod +x ./install
./install auto

# Install Python dependencies
cd /var/www/api
pip3 install -r requirements.txt

Start Server Script

#!/bin/bash
# scripts/start_server.sh
cd /var/www/api

# Start the API server
nohup python3 app.py > /var/log/api.log 2>&1 &
echo $! > /var/run/api.pid

# Configure and start nginx
cp nginx.conf /etc/nginx/conf.d/api.conf
systemctl start nginx
systemctl enable nginx

Stop Server Script

#!/bin/bash
# scripts/stop_server.sh
# Stop the API server
if [ -f /var/run/api.pid ]; then
    kill $(cat /var/run/api.pid)
    rm /var/run/api.pid
fi

# Stop nginx
systemctl stop nginx

Configure Nginx Reverse Proxy

Create the Nginx configuration:

# nginx.conf
server {
    listen 80;
    server_name _;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

This configuration routes incoming requests through Nginx to your Flask application running on port 5000.

Deploy the Application

Set Up CodeDeploy Application

Create a CodeDeploy application in the AWS Console
Create a deployment group targeting your EC2 instances
Configure deployment settings for rolling deployments

Configure GitHub Secrets

Add these secrets to your GitHub repository:

AWS_ACCESS_KEY_ID: Your IAM user access key
AWS_SECRET_ACCESS_KEY: Your IAM user secret key

Test the Pipeline

Push your code to the main branch. GitHub Actions will automatically:

Install Python dependencies
Run tests (if present)
Trigger AWS CodeDeploy
Deploy the application to EC2

Troubleshoot Common Issues

GitHub Actions Failures

Verify AWS credentials in GitHub Secrets
Check IAM permissions for CodeDeploy access
Review GitHub Actions logs for specific error messages

CodeDeploy Failures

Ensure CodeDeploy agent is installed on EC2 instances
Verify file permissions in appspec.yml
Check CloudWatch logs for detailed deployment errors

Application Issues

Confirm Flask application listens on 0.0.0.0, not 127.0.0.1
Verify Nginx configuration syntax
Check security groups allow HTTP traffic on port 80

Monitor and Maintain the Pipeline

Use CloudWatch logs to monitor application performance and deployment status. Set up CloudWatch alarms for key metrics like response time and error rates.

Regular maintenance tasks include:

Updating dependencies in requirements.txt
Reviewing deployment logs for optimization opportunities
Testing deployment scripts on staging environments before production changes

Alternative: CodeBuild Integration

You can achieve similar results with AWS CodeBuild by following the CodeBuild documentation. The deployment scripts and architecture remain identical regardless of your build tool choice.

Cost Considerations

You can monitor and estimate costs using the AWS Pricing Calculator and track actual usage in the AWS Cost Explorer.

Free Tier Benefits

AWS Free Tier provides generous allowances for learning and small projects:

EC2: 750 hours per month of t2.micro instances for 12 months
CodeDeploy: Always free for EC2 deployments
Data Transfer: 15 GB of bandwidth out aggregated across all services
CloudWatch: 10 custom metrics and 10 alarms

Post-Free Tier Costs

After the free tier expires, expect monthly costs:

You can view detailed pricing for all AWS services at AWS Pricing. The free tier makes this approach highly cost-effective for learning, development, and small production workloads.

Conclusion

You have successfully built a production-ready CI/CD pipeline that combines GitHub Actions for reliable building and testing with AWS CodeDeploy for scalable deployment. This hybrid approach provides the best of both platforms: GitHub's developer-friendly build environment and AWS native deployment capabilities.

The pipeline automatically tests and deploys your Flask API whenever you push code changes, enabling rapid iteration while maintaining production stability. You can extend this foundation by adding multiple environments, implementing blue-green deployments, and integrating monitoring tools.

This approach demonstrates that effective CI/CD does not require complex tool chains. Focus on building working software that solves real problems, and choose tools based on your specific requirements rather than vendor lock-in considerations.

Getting Started with FastAPI + Docker: A Beginner-Friendly Cloud Setup

Stella Achar Oiro — Sun, 03 Aug 2025 10:19:29 +0000

Are you getting into cloud-native development and looking for a real-world project to sharpen your skills? Most FastAPI tutorials show you the basics, but miss the production considerations that matter in actual deployments.

In this guide, I'll walk you through building and containerizing a FastAPI app with Docker—including the production best practices I learned while building healthcare applications and preparing for cloud certifications.

I used this exact approach in my sepsis prediction application and other healthcare systems where reliability and security aren't optional.

Why FastAPI + Docker?

FastAPI paired with Docker gives you:

Asynchronous performance for handling multiple requests
Automatic API documentation (crucial for team collaboration)
Type safety with Python type hints
Consistent environments across development, testing, and production
Easy scaling in cloud platforms like AWS ECS or Kubernetes

What You'll Build

A production-ready FastAPI application with:

Health checks for monitoring
Environment-based configuration
Proper logging
Security headers
Optimized Docker image

Project Structure

fastapi-docker-app/
│
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── config.py
│   └── health.py
├── requirements.txt
├── Dockerfile
└── .env.example

1. Environment Configuration (`app/config.py`)

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    app_name: str = "FastAPI Docker App"
    debug: bool = False
    log_level: str = "INFO"

    class Config:
        env_file = ".env"

settings = Settings()

2. Health Check Module (`app/health.py`)

from fastapi import APIRouter
import psutil
import time

router = APIRouter()

@router.get("/health")
def health_check():
    return {
        "status": "healthy",
        "timestamp": time.time(),
        "memory_usage": f"{psutil.virtual_memory().percent}%",
        "cpu_usage": f"{psutil.cpu_percent()}%"
    }

@router.get("/ready")
def readiness_check():
    # Add database connectivity checks here in real apps
    return {"status": "ready"}

3. Main Application (`app/main.py`)

from fastapi import FastAPI, Request
from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import JSONResponse
import logging
import time

from .config import settings
from .health import router as health_router

# Configure logging
logging.basicConfig(level=settings.log_level)
logger = logging.getLogger(__name__)

app = FastAPI(
    title=settings.app_name,
    description="A production-ready FastAPI application",
    version="1.0.0",
    docs_url="/docs" if settings.debug else None,
    redoc_url="/redoc" if settings.debug else None
)

# Add CORS middleware
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"] if settings.debug else ["https://yourdomain.com"],
    allow_credentials=True,
    allow_methods=["GET", "POST"],
    allow_headers=["*"],
)

# Include health check routes
app.include_router(health_router, prefix="/api/v1")

@app.middleware("http")
async def add_security_headers(request: Request, call_next):
    response = await call_next(request)
    response.headers["X-Content-Type-Options"] = "nosniff"
    response.headers["X-Frame-Options"] = "DENY"
    response.headers["X-XSS-Protection"] = "1; mode=block"
    return response

@app.middleware("http")
async def log_requests(request: Request, call_next):
    start_time = time.time()
    response = await call_next(request)
    process_time = time.time() - start_time
    logger.info(f"{request.method} {request.url} - {response.status_code} - {process_time:.3f}s")
    return response

@app.get("/")
def read_root():
    return {
        "message": "Hello from FastAPI + Docker!",
        "app_name": settings.app_name,
        "environment": "development" if settings.debug else "production"
    }

@app.exception_handler(Exception)
async def global_exception_handler(request: Request, exc: Exception):
    logger.error(f"Global exception: {exc}")
    return JSONResponse(
        status_code=500,
        content={"message": "Internal server error"}
    )

4. Dependencies (`requirements.txt`)

fastapi
uvicorn[standard]
pydantic-settings
psutil

5. Multi-Stage Dockerfile

# Build stage
FROM python:3.11-slim as builder

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    gcc \
    && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir --user -r requirements.txt

# Production stage
FROM python:3.11-slim

# Create non-root user
RUN groupadd -r appuser && useradd -r -g appuser appuser

WORKDIR /app

# Copy Python dependencies from builder stage
COPY --from=builder /root/.local /home/appuser/.local

# Copy application code
COPY ./app /app

# Change ownership and switch to non-root user
RUN chown -R appuser:appuser /app
USER appuser

# Add local Python packages to PATH
ENV PATH=/home/appuser/.local/bin:$PATH

# Health check
HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8000/api/v1/health || exit 1

EXPOSE 8000

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

6. Environment Variables (`.env.example`)

APP_NAME=FastAPI Docker App
DEBUG=false
LOG_LEVEL=INFO

Build & Run

# Copy environment file
cp .env.example .env

# Build optimized image
docker build -t fastapi-app:latest .

# Run with environment variables
docker run -d \
  --name fastapi-container \
  -p 8000:8000 \
  --env-file .env \
  fastapi-app:latest

Test Your Application

# Basic endpoint
curl http://localhost:8000/

# Health check
curl http://localhost:8000/api/v1/health

# API documentation (if debug=true)
open http://localhost:8000/docs

Common Issues & Solutions

Issue: Container exits immediately

# Check logs
docker logs fastapi-container

# Common fix: Check your environment variables
docker run --env-file .env fastapi-app:latest

Issue: Permission denied errors

Make sure you're using the non-root user in Dockerfile
Check file permissions on your host system

Issue: Health check failing

# Install curl in container if needed
RUN apt-get update && apt-get install -y curl

Production Deployment Tips

AWS ECS:

Use the health check endpoint for load balancer health checks
Set appropriate CPU/memory limits
Use secrets manager for sensitive environment variables

Kubernetes:

Configure liveness and readiness probes using /health and /ready
Use ConfigMaps for non-sensitive configuration
Implement horizontal pod autoscaling

Docker Compose:

version: '3.8'
services:
  api:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DEBUG=false
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/api/v1/health"]
      interval: 30s
      timeout: 10s
      retries: 3

What You've Learned

Multi-stage Docker builds for smaller, secure images
Health checks and monitoring for production reliability
Security headers and middleware for protection
Structured logging for debugging
Environment-based configuration for different deployment stages
Non-root containers for security best practices

Next Steps

Add a database (PostgreSQL with async drivers)
Implement authentication (JWT tokens)
Add rate limiting for API protection
Set up CI/CD with GitHub Actions
Monitor with Prometheus and Grafana

Connect With Me

I'm a software engineer prepping for KCNA and AWS certifications, building healthcare and cloud-native systems using Golang, FastAPI, and Docker. Let's connect.

LinkedIn | GitHub | Substack | More Projects