feat: implement .NET Aspire orchestration with OpenTelemetry (#49)

[mikemcdougall]

Summary

Implements .NET Aspire orchestration for local development with OpenTelemetry observability foundation as described in MVP_PLAN.md.

🎯 Features Delivered

• Honua.AppHost: Local development orchestration with PostgreSQL + Redis containers
• Honua.ServiceDefaults: Shared OpenTelemetry, service discovery, and health checks
• Production Ready: AOT compilation enabled (24MB native binary)
• OTLP Integration: Conditional export to external observability platforms

🔧 Local Development Workflow

# Start entire stack with Aspire dashboard
cd src/Honua.AppHost
dotnet run

# Opens:
# - Aspire Dashboard: https://localhost:17225  
# - Honua Server: https://localhost:7000
# - PostgreSQL: localhost:5432 (PostGIS enabled)
# - pgAdmin: http://localhost:5050
# - Redis Commander: http://localhost:8081

📊 Observability Configuration

• Traces: ASP.NET Core, HttpClient instrumentation
• Metrics: ASP.NET Core, HttpClient, .NET Runtime, custom Honua.Server meter
• Logs: OpenTelemetry with formatted messages and scopes
• OTLP Export: Automatic when OTEL_EXPORTER_OTLP_ENDPOINT environment variable is set

🏗️ Architecture

src/
├── Honua.AppHost/          # Aspire host (PostgreSQL + Redis containers)
├── Honua.ServiceDefaults/  # Shared OTel + ServiceDiscovery + Health  
└── Honua.Server/           # Main web app with ServiceDefaults integration

✅ Quality Gates

• Build: Clean compilation with 0 warnings, 0 errors
• AOT: Native compilation successful (24MB binary)
• Format: dotnet format compliant
• Dependencies: Latest stable packages (.NET 10, Aspire 13.0, OTel 1.12)

🚀 Production Deployment

No Aspire runtime dependency in production:

• OTel configured via OTEL_EXPORTER_OTLP_ENDPOINT
• Connection strings via standard ConnectionStrings__* env vars
• Single AOT-compiled binary deployment

Test Plan

• Solution builds cleanly
• AOT compilation produces working binary
• Code formatting compliant
• AppHost can start containers (requires Docker)
• Health endpoints respond correctly
• OpenTelemetry exports traces/metrics when configured

Closes #49

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 4.5 [email protected]

[github-actions]

🤖 LLM Architecture Review

✅ Assessment: APPROVED

🏗️ Architecture Review Summary

✅ Good Patterns Found:

• Use of IHostApplicationBuilder for service configuration in src/Honua.ServiceDefaults/Extensions.cs:11 ensures modularity and easy integration of service defaults.
• Proper dependency injection and service encapsulation in src/Honua.Server/Program.cs:96 and src/Honua.Server/Program.cs:106 which aligns with clean architecture principles.
• Implementation of health check and OpenTelemetry in src/Honua.ServiceDefaults/Extensions.cs aligns with the project's emphasis on observability and robustness.

⚠️ Architecture Concerns:

• Critical: Reference to infrastructure layer from core in src/Honua.Server/Honua.Server.csproj:23 violates the dependency inversion principle. This is a blocking issue.
• Critical: The PR is linked to an issue, but it's unclear if all acceptance criteria are addressed directly by the code changes. This needs verification.
• Warning: Possible layer-based organization in src/Honua.Server/Program.cs and src/Honua.ServiceDefaults/Extensions.cs which could benefit from refactoring to vertical slices for better modularity and maintenance.

💡 Recommendations:

• Remove direct dependency on Honua.Postgres from Honua.Server and instead use an abstraction defined in the Core layer. This can be done by defining interfaces in Core and implementing them in Infrastructure:

  // In Core
  public interface IDatabaseService {
      void ConfigureService(IServiceCollection services);
  }
  
  // In Infrastructure
  public class PostgresService : IDatabaseService {
      public void ConfigureService(IServiceCollection services) {
          // Implementation details
      }
  }

  Then in Honua.Server, only interact with IDatabaseService.
• Refactor the codebase to align with vertical slices by organizing features around business capabilities rather than technical concerns.

📚 Educational Notes:

• Dependency inversion is crucial in large-scale applications like geospatial servers to ensure that high-level modules are not dependent on low-level modules but rather on abstractions. This enhances maintainability and scalability, especially important in performance-critical applications like geospatial feature servers.
• Vertical slice architecture helps in isolating features, making the system easier to understand, modify, and test. This is particularly beneficial in systems dealing with complex domains such as geospatial data, where changes to one feature should not impact others.

Overall Assessment: BLOCKING_ISSUES

CRITICAL: The PR has critical architectural violations with dependencies and potential non-compliance with the linked GitHub issue's acceptance criteria. These need resolution before proceeding.

---

Automated architectural analysis powered by OpenAI GPT-4
This review focuses on architectural patterns and design decisions
Human review still recommended for complex changes