PoSnakeGame - Modern Snake Battle Royale

A modern take on the classic Snake game, built with Blazor WebAssembly and .NET 9. Battle against AI-controlled snakes in a fast-paced arena where survival is key! This project demonstrates modern web application architecture using Vertical Slice Architecture, Azure cloud integration, comprehensive testing, and production-ready DevOps practices.

🎮 Features

Gameplay

• Multi-Snake Battle Arena: Compete against AI-controlled snakes with unique personalities and behaviors
• Time-Limited Matches: Fast-paced 30-second rounds with increasing difficulty
• Cross-Platform Controls:
  • Desktop: Arrow keys or WASD for movement
  • Mobile: Touch-based virtual joystick
• High Score System: Enter your 3-letter initials to immortalize your achievements
• Game Statistics: Track total games, average score, longest snake, and more

Technical Features

• Azure Integration: High scores and statistics stored in Azure Table Storage
• Real-time Telemetry: Application Insights monitoring with custom metrics
• Health Monitoring: Built-in health checks and diagnostics pages
• Responsive Design: Optimized for both desktop and mobile play
• Modern Architecture: Vertical Slice Architecture with Clean Architecture principles
• Comprehensive Testing: 89 passing tests (Unit, Integration, Functional)
• CI/CD Pipeline: Automated testing and deployment with GitHub Actions

🚀 Getting Started

Prerequisites

• .NET 9.0 SDK - Download
• Visual Studio 2022 (17.8+) or Visual Studio Code with C# extension
• Azurite - Azure Storage emulator for local development
• Azure Developer CLI (azd) - For Azure deployment (Install)
• Git - Version control

Quick Start (5 minutes)

1. Clone the repository

   git clone https://github.com/punkouter26/PoSnakeGame.git
   cd PoSnakeGame

2. Start Azurite (local storage emulator)

   # Install globally (one-time)
   npm install -g azurite
   
   # Start Azurite with dedicated storage directory
   azurite --location ./.azurite --debug ./.azurite/debug.log

3. Build and run the application

   # Restore dependencies
   dotnet restore PoSnakeGame.sln
   
   # Build solution
   dotnet build PoSnakeGame.sln
   
   # Run the API (includes hosting the Blazor WASM client)
   dotnet run --project PoSnakeGame.Api

4. Access the application

   • Open browser to https://localhost:7066 (or URL shown in console)
   • Try /swagger for API documentation
   • Access /diag for diagnostics and health status
   • Start playing Snake Battle Royale at /

5. Run tests

   dotnet test --filter "FullyQualifiedName!~E2ETests"

🏗️ Project Architecture

This project follows Vertical Slice Architecture with Clean Architecture principles:

PoSnakeGame/
├── PoSnakeGame.Api/          # ASP.NET Core Web API
│   ├── Controllers/          # REST API endpoints
│   ├── Middleware/           # Custom middleware (telemetry enrichment)
│   ├── HealthChecks/         # Health check implementations
│   └── Models/               # API models and DTOs
├── PoSnakeGame.Core/         # Domain models and business logic
│   ├── Models/               # Domain entities (Snake, Arena, HighScore)
│   ├── Services/             # Business logic (GameService, CpuSnakeAI)
│   └── Interfaces/           # Service abstractions
├── PoSnakeGame.Infrastructure/ # Data access and external services
│   ├── Services/             # Table Storage implementation
│   └── Configuration/        # Configuration models
├── PoSnakeGame.Wa/           # Blazor WebAssembly frontend
│   ├── Pages/                # Blazor pages/components
│   ├── Services/             # Client-side services
│   └── wwwroot/              # Static assets
├── PoSnakeGame.Tests/        # Comprehensive test suite
│   ├── Unit Tests            # Business logic tests
│   ├── Integration Tests     # Database integration tests
│   └── Functional Tests      # API endpoint tests
├── infra/                    # Azure Bicep infrastructure
│   ├── main.bicep            # Main deployment template
│   └── core/                 # Reusable Bicep modules
├── docs/                     # Documentation
│   ├── DEPLOYMENT.md         # Deployment guide
│   ├── TELEMETRY.md          # Monitoring guide
│   └── queries/              # KQL queries for monitoring
└── .github/                  # GitHub configuration
    ├── workflows/            # CI/CD pipelines
    └── copilot-agents.md     # AI assistant instructions

Architecture Principles

• Vertical Slice Architecture: Features organized as self-contained slices
• Clean Architecture: Business logic independent of infrastructure
• Dependency Injection: All services registered with proper lifetimes
• SOLID Principles: Clean, maintainable, testable code
• Test-Driven Development: Tests written before implementation

🔧 Configuration

Local Development (appsettings.Development.json)

{
  "TableStorage": {
    "ConnectionString": "UseDevelopmentStorage=true",
    "HighScoresTableName": "PoSnakeGameHighScores",
    "GameStatisticsTableName": "PoSnakeGameGameStatistics",
    "IsUsingLocalStorage": true
  },
  "ApplicationInsights": {
    "ConnectionString": "InstrumentationKey=..."
  }
}

Azure Production (Environment Variables)

• APPLICATIONINSIGHTS_CONNECTION_STRING - Application Insights
• TableStorage__ConnectionString - Azure Table Storage
• TableStorage__HighScoresTableName - High scores table
• TableStorage__GameStatisticsTableName - Statistics table
• TableStorage__IsUsingLocalStorage - Set to false

This prevents conflicts when multiple applications share the same storage account.

📊 Documentation & Diagrams

Comprehensive technical documentation is available in the /Diagrams folder:

Architecture Diagrams

📊 API Endpoints

Health & Diagnostics

• GET /api/health - Basic health check
• GET /api/diagnostics/health - Detailed system health
• GET /api/diagnostics/tablestorage - Table Storage connectivity

High Scores

• GET /api/highscores - Retrieve top 10 scores
• POST /api/highscores/save - Save a new high score
• GET /api/highscores/check/{score} - Check if score qualifies
• DELETE /api/highscores/clear - Clear all scores (debug only)

Game Statistics

• GET /api/statistics - Retrieve aggregate statistics
• POST /api/statistics/save - Save game session statistics

Client Logging

• POST /api/logging/client - Single log entry from Blazor
• POST /api/logging/client/batch - Multiple log entries

See api-tests.http for request examples.

🧪 Testing

Test Suite (89 Passing Tests)

Unit Tests

• GameServiceTests.cs - Game logic and state management
• CpuSnakeAITests.cs - AI behavior and pathfinding
• ModelTests.cs - Domain model validation

Integration Tests

• TableStorageServiceIntegrationTests.cs - Database operations
• HighScoresControllerTests.cs - High score API endpoints
• StatisticsControllerTests.cs - Statistics API endpoints

Functional Tests

• StatisticsApiTests.cs - End-to-end API testing
• HealthControllerTests.cs - Health check endpoints
• StatisticsE2ETests.cs - Full workflow validation

Running Tests

# Run all tests (except E2E)
dotnet test --filter "FullyQualifiedName!~E2ETests"

# Run specific test class
dotnet test --filter "FullyQualifiedName~StatisticsApiTests"

# Run with detailed output
dotnet test --logger "console;verbosity=detailed"

# Generate coverage report
dotnet test --collect:"XPlat Code Coverage"

🚀 Deployment

Azure Deployment (Recommended)

Quick Deploy

# Install Azure Developer CLI
winget install microsoft.azd

# Login to Azure
azd auth login

# Deploy to Azure (provisions + deploys)
azd up

Manual Deployment Steps

# 1. Provision infrastructure
azd provision

# 2. Deploy application
azd deploy

# 3. Browse deployed app
azd browse

See docs/DEPLOYMENT.md for comprehensive deployment guide.

CI/CD Pipeline

GitHub Actions workflow (.github/workflows/main.yml) automatically:

1. Tests - Runs all 89 tests on every push/PR
2. Provisions - Creates/updates Azure infrastructure
3. Deploys - Deploys application to Azure App Service
4. Validates - Runs health checks and functional tests

Required GitHub Secrets:

• AZURE_CLIENT_ID - Service principal client ID
• AZURE_TENANT_ID - Azure AD tenant ID
• AZURE_SUBSCRIPTION_ID - Azure subscription ID

Azure Resources Created

• App Service - Hosts API and Blazor WASM
• Storage Account - Table Storage for data
• Application Insights - Telemetry and monitoring
• Log Analytics - Advanced log queries

Estimated Cost: ~$0-5/month (Free/Basic tiers)

� Monitoring & Observability

Logging

• Framework: Serilog with structured JSON logging
• Sinks: Console, File (logs/log.txt), Application Insights
• Client Logging: Blazor logs sent to /api/logging/client

Application Insights

• Real-time metrics and telemetry
• Custom events and metrics tracking
• Exception tracking with full stack traces
• KQL queries in docs/queries/:
  • user-activity.kql - User engagement metrics
  • slowest-requests.kql - Performance bottlenecks
  • error-rate.kql - Error tracking and trends

Health Checks

• /api/health - Basic availability
• /api/diagnostics/health - Detailed system status
• /diag - Blazor diagnostics page with connectivity tests

See docs/TELEMETRY.md for complete monitoring guide.

📚 Documentation

• DEPLOYMENT.md - Comprehensive deployment guide
• TELEMETRY.md - Monitoring and logging guide
• PRD.md - Product requirements document
• copilot-agents.md - AI assistant instructions
• api-tests.http - HTTP file for API testing

🛠️ Technology Stack

Backend

• .NET 9.0 - Latest .NET framework (preview)
• ASP.NET Core - Web API with REST endpoints
• Serilog - Structured logging
• xUnit - Testing framework
• Azure SDK - Azure service integration

Frontend

• Blazor WebAssembly - Client-side SPA framework
• Radzen.Blazor - UI component library
• .NET 9.0 - Blazor runtime

Infrastructure

• Azure App Service - Application hosting (F1 Free tier)
• Azure Table Storage - NoSQL data storage (Standard LRS)
• Azure Application Insights - APM and monitoring
• Azure Log Analytics - Advanced log queries
• Azure Bicep - Infrastructure as Code

DevOps

• GitHub Actions - CI/CD pipelines
• Azure Developer CLI (azd) - Deployment automation
• Azurite - Local storage emulator
• Git - Source control

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Follow TDD: Write tests first, then implement
4. Ensure all 89 tests pass: dotnet test --filter "FullyQualifiedName!~E2ETests"
5. Update documentation if needed
6. Commit with clear message: git commit -m 'Add amazing feature'
7. Push to branch: git push origin feature/amazing-feature
8. Open a Pull Request

Code Standards

• Follow C# coding conventions and .NET best practices
• Maintain test coverage (all features must have tests)
• Use SOLID principles and Clean Architecture
• Update relevant documentation
• Keep files under 500 lines (refactor if larger)
• Remove unused code proactively

📄 License

This project is licensed under the MIT License.

🙏 Acknowledgments

• .NET Team - For the amazing .NET 9.0 platform
• Blazor Team - For making WebAssembly development enjoyable
• Radzen - For excellent Blazor components
• Azure Team - For comprehensive cloud services
• Community - For feedback and contributions
• Classic Snake - For timeless inspiration

📞 Support & Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Repository: https://github.com/punkouter26/PoSnakeGame

---

🎮 Built with ❤️ using .NET 9.0 and Blazor WebAssembly

Last Updated: October 24, 2025