feat: update documentation to include .NET Aspire architecture and Redis caching strategy

Author: csharpfritz

.github/copilot-instructions.md

@@ -10,11 +10,74 @@ This is "Copilot That Jawn" - a comprehensive ASP.NET Core web application that
 
 ## Technology Stack
 - **Framework**: ASP.NET Core 9.0+ with Razor Pages
-- **Architecture**: Razor Pages application with MVC controllers for complex operations
+- **Architecture**: .NET Aspire cloud-native application stack with Razor Pages application and MVC controllers for complex operations
+- **Orchestration**: .NET Aspire AppHost for service orchestration and configuration
 - **Content Storage**: Markdown files in Content/ directory for tips, tutorials, and guides
 - **Database**: Entity Framework Core (SQL Server or SQLite for development) for dynamic data
 - **Frontend**: Bootstrap 5, modern responsive design with CSS Grid/Flexbox
 - **JavaScript**: Vanilla JS with modern ES6+ features, minimal dependencies
+- **Cloud Services**: Azure integration through .NET Aspire service defaults and components
+
+## .NET Aspire Architecture
+
+This application is built using .NET Aspire, Microsoft's cloud-native application stack that provides a consistent, opinionated set of tools and patterns for building observable, production-ready apps.
+
+### Aspire Project Structure
+```
+├── AppHost/                 # .NET Aspire orchestration project
+│   ├── AppHost.cs          # Application composition and service configuration
+│   ├── appsettings.json    # Aspire host configuration
+│   └── infra/              # Infrastructure templates for deployment
+├── Web/                    # Main web application project
+├── ServiceDefaults/        # Shared service configuration and extensions
+├── ContentLoader/          # Background service for content processing
+└── Shared/                 # Shared models and utilities
+```
+
+### Key Aspire Components Used
+- **Service Discovery**: Automatic service discovery and configuration
+- **Service Defaults**: Shared telemetry, health checks, and service configuration
+- **Resource Management**: Simplified resource provisioning and management
+- **Observability**: Built-in logging, metrics, and distributed tracing
+- **Development Dashboard**: Real-time monitoring and debugging during development
+
+### Aspire Development Best Practices
+
+#### AppHost Configuration
+- Define all services and their dependencies in `AppHost.cs`
+- Use environment-specific configuration for different deployment targets
+- Leverage Aspire's built-in resource templates for databases, caching, messaging
+- Configure service-to-service communication through Aspire's service discovery
+
+#### Service Defaults Integration
+- All projects should reference the `ServiceDefaults` project
+- Use `builder.AddServiceDefaults()` in each service's `Program.cs`
+- Implement consistent logging, health checks, and telemetry across services
+- Follow Aspire's conventions for configuration and dependency injection
+
+#### Running the Application
+- **Primary Development Command**: `dotnet run --project AppHost` 
+- **Alternative**: Use `dotnet watch run --project AppHost` for development with hot reload
+- **Aspire Dashboard**: Access the development dashboard at the URL shown in console output
+- **Service Monitoring**: Use the Aspire dashboard to monitor service health, logs, and metrics
+
+#### Resource Management
+- Define infrastructure requirements in the AppHost project
+- Use Aspire's resource provisioning for local development dependencies
+- Leverage infrastructure templates in `infra/` directory for cloud deployment
+- Configure connection strings and service endpoints through Aspire's configuration system
+
+#### Testing with Aspire
+- Use Aspire's testing utilities for integration tests
+- Test service communication through Aspire's service discovery
+- Validate configuration and resource dependencies
+- Implement health checks for all services
+
+### Deployment Considerations
+- Aspire applications can be deployed to various cloud platforms
+- Infrastructure templates generate appropriate deployment artifacts
+- Service configuration is managed through Aspire's configuration system
+- Observability and monitoring are built-in through Aspire's telemetry
 
 ## Project Structure Guidelines
 
@@ -198,22 +261,30 @@ Content/
 ### Development Workflow Best Practices
 
 #### Running and Testing the Application
-- **Prefer `dotnet watch`**: Always use `dotnet watch run` for development instead of manually building, running, stopping, and restarting the application
-- **Hot Reload Benefits**: `dotnet watch` provides automatic rebuilding and browser refresh when files change, significantly improving development efficiency
-- **Recommended Commands**:
-  - `dotnet watch run` - Start the application with hot reload
-  - `dotnet watch test` - Run tests with automatic re-execution on file changes
-  - `dotnet watch build` - Build with automatic rebuilding on changes
-
-#### File Monitoring
-- `dotnet watch` automatically monitors C# files, Razor pages, CSS, JavaScript, and other static assets
-- Changes trigger automatic compilation and browser refresh
-- Reduces context switching and speeds up the development cycle
+- **Primary Development Command**: `dotnet run --project AppHost` - Starts the entire Aspire application stack
+- **With Hot Reload**: `dotnet watch run --project AppHost` - Starts with automatic rebuilding and browser refresh
+- **Aspire Dashboard**: Monitor services, logs, and metrics through the Aspire development dashboard
+- **Individual Service Testing**: Use `dotnet test` in specific project directories for unit tests
+- **Integration Testing**: Run full stack tests using Aspire's testing framework
+
+#### Aspire-Specific Development Workflow
+- **Service Orchestration**: All services are managed through the AppHost project
+- **Configuration Management**: Use Aspire's configuration system for service settings and connection strings
+- **Service Discovery**: Services communicate through Aspire's built-in service discovery
+- **Observability**: Monitor application performance through the Aspire dashboard during development
+
+#### File Monitoring and Hot Reload
+- Aspire's `dotnet watch` automatically monitors all projects in the application stack
+- Changes to any service trigger appropriate rebuilds and restarts
+- The Aspire dashboard provides real-time feedback on service status during development
+- Static assets (CSS, JS) are monitored and trigger browser refresh automatically
 
 #### Development Environment Setup
-- Ensure the development environment is configured for optimal `dotnet watch` performance
-- Use the `--verbose` flag for debugging watch issues: `dotnet watch run --verbose`
-- Configure file exclusions in `.csproj` if needed to avoid unnecessary rebuilds
+- Ensure .NET 9.0+ SDK is installed for Aspire support
+- Use `dotnet run --project AppHost` as the primary development command
+- Configure the Aspire dashboard for optimal monitoring during development
+- Set up appropriate logging levels in `appsettings.Development.json` for each service
+- Use environment variables through Aspire's configuration system rather than direct file configuration
 
 ## Content Strategy
 

docs/README.md

@@ -6,6 +6,7 @@ Welcome to the documentation for "Copilot That Jawn"! This documentation explain
 
 - [Project Overview](overview.md): General information about the project, its purpose, and structure
 - [Technical Architecture](technical-architecture.md): Detailed explanation of the application architecture and technology stack
+- [Redis and Caching](redis-caching.md): Comprehensive guide to Redis configuration and caching strategy
 - [Content Management](content-management.md): How content is organized, stored, and processed
 - [Development Workflow](development-workflow.md): Guide to setting up a development environment and contributing
 - [Markdown Format](markdown-format.md): Detailed guide to the Markdown format used for content
@@ -17,8 +18,9 @@ If you're new to the project, we recommend reading the documentation in this ord
 1. [Project Overview](overview.md)
 2. [Development Workflow](development-workflow.md)
 3. [Technical Architecture](technical-architecture.md)
-4. [Content Management](content-management.md)
-5. [Markdown Format](markdown-format.md)
+4. [Redis and Caching](redis-caching.md)
+5. [Content Management](content-management.md)
+6. [Markdown Format](markdown-format.md)
 
 ## Contributing
 
@@ -28,7 +30,8 @@ We welcome contributions to both the codebase and content. Please refer to the [
 
 "Copilot That Jawn" is built with:
 
-- **ASP.NET Core 9.0+** with Razor Pages
+- **ASP.NET Core 9.0+** with .NET Aspire cloud-native stack
+- **Redis** distributed caching for performance and scalability
 - **Markdown** content files with YAML frontmatter
 - **Bootstrap 5** for styling
 - **Modern JavaScript** for interactive features

docs/development-workflow.md

@@ -13,36 +13,93 @@ This guide explains the recommended development workflow for contributing to the
 ### Getting Started
 
 1. Clone the repository:
-   ```
+   ```bash
    git clone https://github.com/yourusername/CopilotThatJawn.git
    cd CopilotThatJawn
    ```
 
 2. Restore packages:
-   ```
+   ```bash
    dotnet restore
    ```
 
-3. Run the application with hot reload:
-   ```
-   dotnet watch run --project Web
+3. Run the application using .NET Aspire:
+   ```bash
+   dotnet run --project AppHost
    ```
 
-4. Access the site at `https://localhost:5001` (or the port configured in your environment)
+4. Access the Aspire dashboard at the URL shown in the console output (typically `https://localhost:15888`)
+5. Access the main application at `https://localhost:5001` (or the port shown in the Aspire dashboard)
+
+## .NET Aspire Development
+
+The project uses .NET Aspire for service orchestration, which manages Redis, Azure Storage, and the web application.
+
+### Aspire Dashboard
+
+The Aspire dashboard provides:
+- **Service Status**: Monitor all running services (Web, Redis, Azure Storage)
+- **Logs**: Centralized logging from all services
+- **Metrics**: Performance metrics and health checks
+- **Resource Management**: View connection strings and service endpoints
+
+### Redis Development
+
+#### Local Redis Setup
+
+Redis runs automatically through Aspire orchestration:
+
+```bash
+# Start the full application stack (includes Redis)
+dotnet run --project AppHost
+
+# Redis will be available at localhost:6379 (default port)
+# RedisInsight dashboard available through Aspire dashboard
+```
+
+#### Redis Cache Management
+
+The application provides several ways to interact with the Redis cache:
+
+1. **Through the Application**: Content is automatically cached during normal operation
+2. **RedisInsight**: Visual Redis management tool accessible through Aspire dashboard
+3. **Cache Refresh API**: Manual cache refresh endpoint
+
+#### Cache Refresh API
+
+```bash
+# Refresh cache via API (requires API key in production)
+curl -X POST https://localhost:5001/api/cache/refresh \
+  -H "X-API-Key: your-api-key"
+```
+
+#### Monitoring Redis
+
+- **Aspire Dashboard**: View Redis logs and metrics
+- **RedisInsight**: Inspect keys, values, and performance
+- **Application Logs**: ContentService logs cache hits/misses
 
 ## Using Hot Reload
 
-The project is configured to take advantage of ASP.NET Core's hot reload capabilities:
+The project is configured to take advantage of ASP.NET Core's hot reload capabilities through .NET Aspire:
 
 - **Automatic Rebuilding**: When you modify C# files, the application automatically rebuilds
 - **Browser Refresh**: Changes to Razor pages, CSS, and JavaScript trigger automatic browser refresh
 - **Content Updates**: Adding or modifying content files will be reflected in the application
+- **Service Orchestration**: All services (Web, Redis, Storage) are managed together
 
 ### Commands
 
-- `dotnet watch run --project Web`: Start the application with hot reload
-- `dotnet watch test`: Run tests with automatic re-execution when code changes
-- `dotnet watch build`: Build with automatic rebuilding when code changes
+- `dotnet run --project AppHost`: Start the full application stack
+- `dotnet watch run --project AppHost`: Start with enhanced hot reload monitoring
+- `dotnet test`: Run tests for the entire solution
+
+### Service Dependencies
+
+The Aspire orchestration ensures proper startup order:
+1. Redis container starts and becomes ready
+2. Azure Storage emulator starts and becomes ready  
+3. Web application starts and connects to dependencies
 
 ## Code Organization
 

docs/overview.md

@@ -36,8 +36,10 @@ As the name suggests, "Copilot That Jawn" incorporates Philadelphia terminology
 
 ## Technology Stack
 
-- **Framework**: ASP.NET Core 9.0+ with Razor Pages
-- **Architecture**: Razor Pages application with MVC controllers for complex operations
+- **Framework**: ASP.NET Core 9.0+ with .NET Aspire cloud-native stack
+- **Service Orchestration**: .NET Aspire AppHost for managing Redis, Azure Storage, and web application
+- **Caching**: Redis distributed caching with multi-layer caching strategy
 - **Content Storage**: Markdown files in Content/ directory processed with Markdig
 - **Frontend**: Bootstrap 5, modern responsive design with CSS Grid/Flexbox
 - **JavaScript**: Vanilla JS with modern ES6+ features, minimal dependencies
+- **Observability**: Built-in logging, metrics, and distributed tracing through Aspire