diff --git a/README.md b/README.md
index 5977e3d..d21b159 100644
--- a/README.md
+++ b/README.md
@@ -45,17 +45,15 @@ NLWebNet/
 │   ├── Endpoints/             # Minimal API endpoints (/ask, /mcp)
 │   ├── MCP/                   # Model Context Protocol integration
 │   ├── Extensions/            # DI and middleware extensions
-│   ├── Middleware/            # Request processing middleware
-│   ├── Middleware/            # ASP.NET Core middleware
-│   └── Extensions/            # Dependency injection extensions
+│   └── Middleware/            # Request processing middleware
 ├── samples/                   # 🎯 Sample applications and usage examples
 │   ├── Demo/                  # 🎮 .NET 9 Blazor Web App demo application  
 │   └── AspireHost/            # 🏗️ .NET Aspire orchestration host  
-│   ├── Components/            # Modern Blazor components
-│   │   ├── Layout/            # Layout components (MainLayout, etc.)
-│   │   └── Pages/             # Page components (Home, NLWebDemo, Error)
-│   ├── wwwroot/               # Static assets (app.css, favicon, etc.)
-│   └── Properties/            # Launch settings and configuration
+├── deployment/                # 🚀 Deployment and infrastructure files
+│   ├── azure/                 # Azure deployment (Bicep templates)
+│   ├── kubernetes/            # Kubernetes manifests and Helm charts
+│   ├── docker/                # Docker and Docker Compose files
+│   └── scripts/               # Deployment and validation scripts
 ├── doc/                       # 📚 Documentation
 └── tests/                     # 🧪 Unit and integration tests
     └── NLWebNet.Tests/        # 📋 xUnit test project
@@ -411,28 +409,28 @@ NLWebNet supports multiple deployment options for different environments:
 # Quick start with Docker Compose
 git clone https://github.com/jongalloway/NLWebNet.git
 cd NLWebNet
-docker-compose up --build
+cd deployment/docker && docker-compose up --build
 ```
 
 ### ☁️ Azure Cloud Deployment
 ```bash
 # Deploy to Azure Container Apps
-./scripts/deploy/deploy-azure.sh -g myResourceGroup -t container-apps
+./deployment/scripts/deploy/deploy-azure.sh -g myResourceGroup -t container-apps
 
 # Deploy to Azure App Service
-./scripts/deploy/deploy-azure.sh -g myResourceGroup -t app-service
+./deployment/scripts/deploy/deploy-azure.sh -g myResourceGroup -t app-service
 ```
 
 ### ⚙️ Kubernetes Deployment
 ```bash
 # Deploy to any Kubernetes cluster
-kubectl apply -f k8s/
+kubectl apply -f deployment/kubernetes/manifests/
 ```
 
 ### 📦 Container Registry
 Pre-built images available soon. For now, build locally:
 ```bash
-./scripts/deploy/build-docker.sh -t latest
+./deployment/scripts/deploy/build-docker.sh -t latest
 ```
 
 📖 **[Complete Deployment Guide](doc/deployment/README.md)** - Comprehensive instructions for all deployment scenarios.
diff --git a/deploy/azure/app-service.bicep b/deployment/azure/app-service.bicep
similarity index 100%
rename from deploy/azure/app-service.bicep
rename to deployment/azure/app-service.bicep
diff --git a/deploy/azure/container-apps.bicep b/deployment/azure/container-apps.bicep
similarity index 100%
rename from deploy/azure/container-apps.bicep
rename to deployment/azure/container-apps.bicep
diff --git a/deploy/azure/container-apps.parameters.json b/deployment/azure/container-apps.parameters.json
similarity index 100%
rename from deploy/azure/container-apps.parameters.json
rename to deployment/azure/container-apps.parameters.json
diff --git a/Dockerfile b/deployment/docker/Dockerfile
similarity index 100%
rename from Dockerfile
rename to deployment/docker/Dockerfile
diff --git a/docker-compose.yml b/deployment/docker/docker-compose.yml
similarity index 97%
rename from docker-compose.yml
rename to deployment/docker/docker-compose.yml
index 568a446..2dd72f4 100644
--- a/docker-compose.yml
+++ b/deployment/docker/docker-compose.yml
@@ -4,8 +4,8 @@ services:
   # NLWebNet Demo Application
   nlwebnet-demo:
     build:
-      context: .
-      dockerfile: Dockerfile
+      context: ../../
+      dockerfile: deployment/docker/Dockerfile
       target: final
     container_name: nlwebnet-demo
     ports:
diff --git a/helm/nlwebnet/Chart.yaml b/deployment/kubernetes/helm/Chart.yaml
similarity index 100%
rename from helm/nlwebnet/Chart.yaml
rename to deployment/kubernetes/helm/Chart.yaml
diff --git a/helm/nlwebnet/README.md b/deployment/kubernetes/helm/README.md
similarity index 100%
rename from helm/nlwebnet/README.md
rename to deployment/kubernetes/helm/README.md
diff --git a/helm/nlwebnet/templates/_helpers.tpl b/deployment/kubernetes/helm/templates/_helpers.tpl
similarity index 100%
rename from helm/nlwebnet/templates/_helpers.tpl
rename to deployment/kubernetes/helm/templates/_helpers.tpl
diff --git a/helm/nlwebnet/templates/deployment.yaml b/deployment/kubernetes/helm/templates/deployment.yaml
similarity index 100%
rename from helm/nlwebnet/templates/deployment.yaml
rename to deployment/kubernetes/helm/templates/deployment.yaml
diff --git a/helm/nlwebnet/templates/hpa.yaml b/deployment/kubernetes/helm/templates/hpa.yaml
similarity index 100%
rename from helm/nlwebnet/templates/hpa.yaml
rename to deployment/kubernetes/helm/templates/hpa.yaml
diff --git a/helm/nlwebnet/templates/ingress.yaml b/deployment/kubernetes/helm/templates/ingress.yaml
similarity index 100%
rename from helm/nlwebnet/templates/ingress.yaml
rename to deployment/kubernetes/helm/templates/ingress.yaml
diff --git a/helm/nlwebnet/templates/secret.yaml b/deployment/kubernetes/helm/templates/secret.yaml
similarity index 100%
rename from helm/nlwebnet/templates/secret.yaml
rename to deployment/kubernetes/helm/templates/secret.yaml
diff --git a/helm/nlwebnet/templates/service.yaml b/deployment/kubernetes/helm/templates/service.yaml
similarity index 100%
rename from helm/nlwebnet/templates/service.yaml
rename to deployment/kubernetes/helm/templates/service.yaml
diff --git a/helm/nlwebnet/templates/serviceaccount.yaml b/deployment/kubernetes/helm/templates/serviceaccount.yaml
similarity index 100%
rename from helm/nlwebnet/templates/serviceaccount.yaml
rename to deployment/kubernetes/helm/templates/serviceaccount.yaml
diff --git a/helm/nlwebnet/values.yaml b/deployment/kubernetes/helm/values.yaml
similarity index 100%
rename from helm/nlwebnet/values.yaml
rename to deployment/kubernetes/helm/values.yaml
diff --git a/k8s/configmap.yaml b/deployment/kubernetes/manifests/configmap.yaml
similarity index 100%
rename from k8s/configmap.yaml
rename to deployment/kubernetes/manifests/configmap.yaml
diff --git a/k8s/deployment.yaml b/deployment/kubernetes/manifests/deployment.yaml
similarity index 100%
rename from k8s/deployment.yaml
rename to deployment/kubernetes/manifests/deployment.yaml
diff --git a/k8s/ingress.yaml b/deployment/kubernetes/manifests/ingress.yaml
similarity index 100%
rename from k8s/ingress.yaml
rename to deployment/kubernetes/manifests/ingress.yaml
diff --git a/k8s/service.yaml b/deployment/kubernetes/manifests/service.yaml
similarity index 100%
rename from k8s/service.yaml
rename to deployment/kubernetes/manifests/service.yaml
diff --git a/scripts/deploy/build-docker.sh b/deployment/scripts/deploy/build-docker.sh
similarity index 93%
rename from scripts/deploy/build-docker.sh
rename to deployment/scripts/deploy/build-docker.sh
index 24ef4b8..da81f6a 100755
--- a/scripts/deploy/build-docker.sh
+++ b/deployment/scripts/deploy/build-docker.sh
@@ -9,7 +9,8 @@ set -e  # Exit on any error
 IMAGE_NAME="nlwebnet-demo"
 DEFAULT_TAG="latest"
 REGISTRY=""
-DOCKERFILE="Dockerfile"
+DOCKERFILE="deployment/docker/Dockerfile"
+BUILD_CONTEXT="../../../"
 
 # Colors for output
 RED='\033[0;31m'
@@ -95,8 +96,8 @@ print_status "Image name: $FULL_IMAGE_NAME"
 print_status "Dockerfile: $DOCKERFILE"
 
 # Check if Dockerfile exists
-if [[ ! -f "$DOCKERFILE" ]]; then
-    print_error "Dockerfile not found: $DOCKERFILE"
+if [[ ! -f "$BUILD_CONTEXT$DOCKERFILE" ]]; then
+    print_error "Dockerfile not found: $BUILD_CONTEXT$DOCKERFILE"
     exit 1
 fi
 
@@ -107,7 +108,7 @@ if [[ "$NO_CACHE" == true ]]; then
     BUILD_CMD="$BUILD_CMD --no-cache"
 fi
 
-BUILD_CMD="$BUILD_CMD -t $FULL_IMAGE_NAME -f $DOCKERFILE ."
+BUILD_CMD="$BUILD_CMD -t $FULL_IMAGE_NAME -f $DOCKERFILE $BUILD_CONTEXT"
 
 print_status "Running: $BUILD_CMD"
 
diff --git a/scripts/deploy/deploy-azure.sh b/deployment/scripts/deploy/deploy-azure.sh
similarity index 96%
rename from scripts/deploy/deploy-azure.sh
rename to deployment/scripts/deploy/deploy-azure.sh
index b5e15df..f1b944f 100755
--- a/scripts/deploy/deploy-azure.sh
+++ b/deployment/scripts/deploy/deploy-azure.sh
@@ -80,11 +80,11 @@ while [[ $# -gt 0 ]]; do
         -t|--template)
             case "$2" in
                 container-apps)
-                    TEMPLATE_FILE="deploy/azure/container-apps.bicep"
-                    PARAMETERS_FILE="deploy/azure/container-apps.parameters.json"
+                    TEMPLATE_FILE="../../../deployment/azure/container-apps.bicep"
+                    PARAMETERS_FILE="../../../deployment/azure/container-apps.parameters.json"
                     ;;
                 app-service)
-                    TEMPLATE_FILE="deploy/azure/app-service.bicep"
+                    TEMPLATE_FILE="../../../deployment/azure/app-service.bicep"
                     ;;
                 *)
                     print_error "Invalid template: $2. Use 'container-apps' or 'app-service'"
diff --git a/scripts/validate-package.ps1 b/deployment/scripts/validate-package.ps1
similarity index 96%
rename from scripts/validate-package.ps1
rename to deployment/scripts/validate-package.ps1
index 109a16c..31dd21f 100644
--- a/scripts/validate-package.ps1
+++ b/deployment/scripts/validate-package.ps1
@@ -18,7 +18,7 @@ function Test-Command($command) {
 
 # 1. Build and Test
 Write-Host "`n📦 Step 1: Building and Testing..." -ForegroundColor Yellow
-dotnet build src/NLWebNet --configuration Release
+dotnet build ../../src/NLWebNet --configuration Release
 if ($LASTEXITCODE -ne 0) { throw "Build failed" }
 
 dotnet test --configuration Release --no-build
@@ -26,9 +26,9 @@ if ($LASTEXITCODE -ne 0) { throw "Tests failed" }
 
 # 2. Create Package
 Write-Host "`n📦 Step 2: Creating Package..." -ForegroundColor Yellow
-$outputDir = ".\packages-validation"
+$outputDir = "..\..\packages-validation"
 Remove-Item $outputDir -Recurse -Force -ErrorAction SilentlyContinue
-dotnet pack src/NLWebNet --configuration Release --output $outputDir
+dotnet pack ../../src/NLWebNet --configuration Release --output $outputDir
 if ($LASTEXITCODE -ne 0) { throw "Pack failed" }
 
 # Find the created package
@@ -121,7 +121,7 @@ Write-Host "`n📦 Step 5: Analyzing Dependencies..." -ForegroundColor Yellow
 if (-not $SkipDependencyCheck) {
     # Check for vulnerable dependencies
     Write-Host "Checking for vulnerable dependencies..."
-    $vulnerableOutput = dotnet list src/NLWebNet package --vulnerable --include-transitive 2>&1
+    $vulnerableOutput = dotnet list ../../src/NLWebNet package --vulnerable --include-transitive 2>&1
     if ($vulnerableOutput -match "has the following vulnerable packages") {
         Write-Host "❌ Vulnerable dependencies found:" -ForegroundColor Red
         Write-Host $vulnerableOutput -ForegroundColor Red
@@ -132,7 +132,7 @@ if (-not $SkipDependencyCheck) {
     
     # Check for deprecated dependencies
     Write-Host "Checking for deprecated dependencies..."
-    $deprecatedOutput = dotnet list src/NLWebNet package --deprecated 2>&1
+    $deprecatedOutput = dotnet list ../../src/NLWebNet package --deprecated 2>&1
     if ($deprecatedOutput -match "has the following deprecated packages") {
         Write-Host "⚠️ Deprecated dependencies found:" -ForegroundColor Yellow
         Write-Host $deprecatedOutput -ForegroundColor Yellow
diff --git a/scripts/validate-package.sh b/deployment/scripts/validate-package.sh
similarity index 86%
rename from scripts/validate-package.sh
rename to deployment/scripts/validate-package.sh
index 4af8d87..93757f6 100644
--- a/scripts/validate-package.sh
+++ b/deployment/scripts/validate-package.sh
@@ -9,14 +9,14 @@ echo "====================================="
 
 # 1. Build and Test
 echo -e "\n📦 Step 1: Building and Testing..."
-dotnet build src/NLWebNet --configuration Release
+dotnet build ../../src/NLWebNet --configuration Release
 dotnet test --configuration Release --no-build
 
 # 2. Create Package  
 echo -e "\n📦 Step 2: Creating Package..."
-OUTPUT_DIR="./packages-validation"
+OUTPUT_DIR="../../packages-validation"
 rm -rf "$OUTPUT_DIR"
-dotnet pack src/NLWebNet --configuration Release --output "$OUTPUT_DIR"
+dotnet pack ../../src/NLWebNet --configuration Release --output "$OUTPUT_DIR"
 
 # Find the created package
 NUPKG_FILE=$(find "$OUTPUT_DIR" -name "*.nupkg" ! -name "*.symbols.nupkg" | head -n 1)
@@ -73,18 +73,18 @@ fi
 # 5. Dependency Analysis
 echo -e "\n📦 Step 5: Analyzing Dependencies..."
 echo "Checking for vulnerable dependencies..."
-if dotnet list src/NLWebNet package --vulnerable --include-transitive 2>&1 | grep -q "has the following vulnerable packages"; then
+if dotnet list ../../src/NLWebNet package --vulnerable --include-transitive 2>&1 | grep -q "has the following vulnerable packages"; then
     echo "❌ Vulnerable dependencies found"
-    dotnet list src/NLWebNet package --vulnerable --include-transitive
+    dotnet list ../../src/NLWebNet package --vulnerable --include-transitive
     exit 1
 else
     echo "✅ No vulnerable dependencies found"
 fi
 
 echo "Checking for deprecated dependencies..."
-if dotnet list src/NLWebNet package --deprecated 2>&1 | grep -q "has the following deprecated packages"; then
+if dotnet list ../../src/NLWebNet package --deprecated 2>&1 | grep -q "has the following deprecated packages"; then
     echo "⚠️ Deprecated dependencies found"
-    dotnet list src/NLWebNet package --deprecated
+    dotnet list ../../src/NLWebNet package --deprecated
 else
     echo "✅ No deprecated dependencies found"
 fi
@@ -99,7 +99,7 @@ dotnet new web -n TestConsumer -o "$TEST_CONSUMER_DIR" --force
 cd "$TEST_CONSUMER_DIR"
 
 # Add the local package
-dotnet add package NLWebNet --source ../packages-validation --prerelease --prerelease
+dotnet add package NLWebNet --source ../../packages-validation --prerelease --prerelease
 
 # Create test Program.cs
 cat > Program.cs << 'EOF'
diff --git a/doc/deployment/README.md b/doc/deployment/README.md
index dc2fa15..d8137e8 100644
--- a/doc/deployment/README.md
+++ b/doc/deployment/README.md
@@ -29,7 +29,7 @@ git clone https://github.com/jongalloway/NLWebNet.git
 cd NLWebNet
 
 # Run with Docker Compose
-docker-compose up --build
+cd deployment/docker && docker-compose up --build
 
 # Or run locally (requires .NET 9)
 cd samples/Demo
@@ -46,13 +46,13 @@ Use the provided build script for easy Docker image creation:
 
 ```bash
 # Build with default settings
-./scripts/deploy/build-docker.sh
+./deployment/scripts/deploy/build-docker.sh
 
 # Build with specific tag
-./scripts/deploy/build-docker.sh -t v1.0.0
+./deployment/scripts/deploy/build-docker.sh -t v1.0.0
 
 # Build and push to registry
-./scripts/deploy/build-docker.sh -t v1.0.0 -r myregistry.azurecr.io -p
+./deployment/scripts/deploy/build-docker.sh -t v1.0.0 -r myregistry.azurecr.io -p
 ```
 
 ### Manual Docker Build
@@ -75,7 +75,7 @@ For local development with dependencies:
 
 ```bash
 # Start all services
-docker-compose up -d
+cd deployment/docker && docker-compose up -d
 
 # View logs
 docker-compose logs -f nlwebnet-demo
@@ -105,7 +105,7 @@ Key environment variables for Docker deployment:
 
 ```bash
 # Deploy all resources
-kubectl apply -f k8s/
+kubectl apply -f deployment/kubernetes/manifests/
 
 # Check deployment status
 kubectl get pods -l app=nlwebnet-demo
@@ -129,14 +129,14 @@ kubectl get ingress
      --from-literal=azure-search-api-key="your-key"
    
    # Apply configuration
-   kubectl apply -f k8s/configmap.yaml
+   kubectl apply -f deployment/kubernetes/manifests/configmap.yaml
    ```
 
 3. **Deploy application**:
    ```bash
-   kubectl apply -f k8s/deployment.yaml
-   kubectl apply -f k8s/service.yaml
-   kubectl apply -f k8s/ingress.yaml
+   kubectl apply -f deployment/kubernetes/manifests/deployment.yaml
+   kubectl apply -f deployment/kubernetes/manifests/service.yaml
+   kubectl apply -f deployment/kubernetes/manifests/ingress.yaml
    ```
 
 4. **Verify deployment**:
@@ -185,25 +185,25 @@ az account set --subscription "your-subscription-id"
 
 ```bash
 # Deploy using script
-./scripts/deploy/deploy-azure.sh -g myResourceGroup -t container-apps
+./deployment/scripts/deploy/deploy-azure.sh -g myResourceGroup -t container-apps
 
 # Or manual deployment
 az deployment group create \
   --resource-group myResourceGroup \
-  --template-file deploy/azure/container-apps.bicep \
-  --parameters @deploy/azure/container-apps.parameters.json
+  --template-file deployment/azure/container-apps.bicep \
+  --parameters @deployment/azure/container-apps.parameters.json
 ```
 
 ### App Service Deployment
 
 ```bash
 # Deploy to App Service
-./scripts/deploy/deploy-azure.sh -g myResourceGroup -t app-service -e prod
+./deployment/scripts/deploy/deploy-azure.sh -g myResourceGroup -t app-service -e prod
 
 # Manual deployment
 az deployment group create \
   --resource-group myResourceGroup \
-  --template-file deploy/azure/app-service.bicep \
+  --template-file deployment/azure/app-service.bicep \
   --parameters appName=nlwebnet environment=prod
 ```
 
@@ -225,7 +225,7 @@ az deployment group create \
 
 3. **Deploy application**:
    ```bash
-   kubectl apply -f k8s/
+   kubectl apply -f deployment/kubernetes/manifests/
    ```
 
 ## Production Considerations
@@ -323,7 +323,7 @@ kubectl get events --sort-by=.metadata.creationTimestamp
 
 ```bash
 # Docker logs
-docker-compose logs -f nlwebnet-demo
+cd deployment/docker && docker-compose logs -f nlwebnet-demo
 
 # Kubernetes logs
 kubectl logs -f -l app=nlwebnet-demo
diff --git a/doc/package-validation.md b/doc/package-validation.md
index a21717b..63b94e3 100644
--- a/doc/package-validation.md
+++ b/doc/package-validation.md
@@ -11,7 +11,7 @@ This guide outlines the comprehensive validation process for the NLWebNet NuGet
 
 ### Linux/macOS (Bash)
 ```bash
-./scripts/validate-package.sh
+./deployment/scripts/validate-package.sh
 ```
 
 ## 📋 Manual Validation Checklist
diff --git a/doc/todo.md b/doc/todo.md
index fd85321..4b2f56f 100644
--- a/doc/todo.md
+++ b/doc/todo.md
@@ -511,7 +511,7 @@ Comprehensive testing and validation infrastructure has been implemented coverin
   - [x] ✅ **VALIDATED**: Minimal API endpoint registration works correctly
 - [x] **Production Readiness**:
   - [x] ✅ **RESOLVED**: ModelContextProtocol prerelease dependency - NLWebNet marked as 0.1.0-alpha.1  - [x] ✅ **Final package validation before publication**:
-    - [x] ✅ Run comprehensive validation script (`scripts/validate-package.ps1`) - ALL CHECKS PASSED
+    - [x] ✅ Run comprehensive validation script (`deployment/scripts/validate-package.ps1`) - ALL CHECKS PASSED
     - [x] ✅ Verify package content and assembly metadata - Confirmed correct structure
     - [x] ✅ Confirm no vulnerable or deprecated dependencies - Clean
     - [x] ✅ Test integration with fresh consumer project - Successful compilation