Skip to main content
System Overview: This document describes how Yarpie (reverse proxy) and Aspire orchestration work together in the AdminWeb ecosystem, managing traffic routing and local development environments.

​
Architecture Overview

The AdminWeb product uses a distributed microservices architecture with two key infrastructure components:
  • Aspire (Main.AppHost): Local development orchestration and service discovery
  • Yarpie: Production reverse proxy with blue/green deployment capabilities
Together, these enable seamless service communication in both development and production environments.

​
Aspire - Local Development Orchestration

​
Purpose

Main.AppHost is the .NET Aspire host project that orchestrates all services locally during development. It provides:
  • Service Discovery: Automatic registration and discovery of all microservices
  • Networking: Internal communication between services using service names
  • Configuration Management: Centralized environment variable management
  • Dependency Management: Orchestrates startup order and health checks

​
How Aspire Works

​
Key Features

Service Endpoints: Services reference each other using their project names as hostnames: 
// From Main.AppHost, each service is registered with its name
builder.AddProject<Projects.Donations_ServiceApis>("donations-api")
builder.AddProject<Projects.Donations_Web>("donations-web")
Environment Variables: Centralized in Main.AppHost/Program.cs: 
// Local development
Environment.SetEnvironmentVariable("Environment", "Development");

// These override defaults for Test/Production via CI/CD pipeline
Overrides for Test/Production are defined in /.github/container-scripts/environment_variables.py and applied during deployment.

​
Yarpie - Production Reverse Proxy

​
Purpose

Yarpie is a reverse proxy built on YARP (Yet Another Reverse Proxy) that handles production traffic routing and enables blue/green deployments.

​
Key Responsibilities

  1. Unified Entry Point: Single public endpoint for all web traffic
  2. Routing: Routes requests to appropriate Blazor frontends (Web projects)
  3. Blue/Green Deployments: Switches traffic between deployment versions with zero downtime
  4. Load Balancing: Distributes traffic across multiple instances
  5. SSL/TLS Termination: Handles HTTPS at the edge
  6. API Gateway Patterns: Can implement rate limiting, authentication, logging

​
Yarpie Architecture

​
Yarpie Configuration

Routes are configured in Yarpie’s configuration files to:
  • Map public URLs to backend Blazor applications
  • Handle SSL certificates (from AWS Secrets Manager or CloudFlare)
  • Define health check endpoints
  • Configure timeout and retry policies

​
How They Work Together

​
Local Development (with Aspire)

Development Benefits:
  • No manual URL configuration
  • Services automatically discover each other
  • Local database (LocalDB or Docker)
  • Integrated logging and debugging
  • Matches production architecture

​
Production (with Yarpie)

​
Blue/Green Deployment Flow

Deployment Process:
  1. Deploy new version to Green environment
  2. Run health checks and smoke tests
  3. Yarpie switches traffic from Blue to Green (instantaneous)
  4. Blue becomes the idle/standby environment
  5. Rollback: Switch back to Blue if issues detected

​
Communication Patterns

​
Within Aspire (Development)

Services communicate using:
  • gRPC: Service-to-service direct calls (Protobuffers for serialization)
  • RabbitMQ: Asynchronous message passing between services
  • Entity Framework: Database access via Sa.DataAccess
  • Dapper: Complex query execution (when EF is insufficient)

​
Within Yarpie (Production)

Public Internet
    ↓ (HTTPS)
Yarpie (Reverse Proxy)
    ↓ (HTTP/2 gRPC)
Blazor Web Applications
    ↓ (gRPC)
GRPC Service APIs
    ↓ (SQL/EF/Dapper)
MSSQL Database
    ↑
Background Workers (RabbitMQ consumers)

​
Key Configuration Files

​
Aspire Configuration

  • Main.AppHost/Program.cs: Orchestration and environment setup
  • Main.AppHost/appsettings.json: Local secrets and configurations
  • /.github/container-scripts/environment_variables.py: Test/Production environment overrides

​
Yarpie Configuration

  • Yarpie/config.json or Program.cs: Route definitions
  • AWS Secrets Manager / CloudFlare: Production SSL certificates and routing rules
  • /.github/workflows/: CI/CD pipeline integration for deployments

​
Service Project Structure Reference

​
Web Projects (*.Web)

  • Blazor applications (server or client)
  • Connected to Yarpie in production
  • Connected to Aspire in development
  • Call GRPC ServiceApis

​
Service APIs (*.ServiceApis)

  • GRPC endpoints
  • Business logic and validation
  • Called by Web and Worker projects
  • Access data via CoreLibs

​
Workers (*.Workers)

  • Background services
  • RabbitMQ consumers
  • Execute scheduled tasks
  • Run EF migrations (from CoreLibs)

​
Core Libraries (*.CoreLibs)

  • Data models (Entity Framework DbContext)
  • Repository patterns
  • Database migrations (executed by Workers)
  • Shared business logic

​
Development Workflow

  1. Start Aspire: dotnet run --project Main.AppHost
  2. Access Dashboard: https://localhost:port (shows all running services)
  3. Services Auto-Discover: No URL configuration needed
  4. Debug: Set breakpoints in any service
  5. Test Changes: Modify code and services reload

​
Production Workflow

  1. Build & Package: Docker images created for each service
  2. Deploy to Green: New version deployed alongside Blue
  3. Health Checks: Verify Green environment is healthy
  4. Traffic Switch: Yarpie routes 100% traffic to Green
  5. Monitor: Watch metrics, logs, error rates
  6. Rollback Option: Switch back to Blue if needed