GridRunners

In Short

• Real-time multiplayer maze-racing web app showcasing full‑stack delivery, secure APIs, cloud integrations, and resilient front-end UX.
• Stack: .NET 8 (REST API + SignalR), React + TypeScript, EF Core, Azure SQL/Blob/Key Vault, optional OpenAI, Swagger, GitHub Actions (Azure Static Web Apps).
• Highlights: JWT + refresh tokens, policy-based rate limiting, API versioning, server-side image processing, move validation, disconnect handling, auto-reconnect.

Key Skills Demonstrated

• Real‑time systems: SignalR groups, server‑side move validation, disconnect/reconnect flows.
• Secure APIs: JWT + refresh tokens, CORS, API versioning, rate limiting, SHA‑256 password hashing.
• Cloud/Azure: SQL Database with EF Core, Blob Storage (ImageSharp processing), Key Vault via DefaultAzureCredential.
• AI integration: Optional OpenAI‑driven maze generation with graceful local fallback.
• Frontend engineering: React + TypeScript, guarded routes, axios interceptors with token refresh, keyboard + mobile swipe controls.
• DevOps: GitHub Actions CI/CD deploying frontend to Azure Static Web Apps.

Keywords

ASP.NET Core · SignalR · Entity Framework Core · Azure SQL Database · Azure Key Vault · Azure Blob Storage · JWT · Refresh Tokens · API Versioning · Rate Limiting · CORS · Swagger · React · TypeScript · Axios Interceptors · OpenAI · ImageSharp · GitHub Actions · Azure Static Web Apps

---

GridRunners is a multiplayer maze racing experience for the web. The project pairs a .NET 8 backend (REST API + SignalR hub) with a React 19 frontend so players can authenticate, gather in lobbies, and race through procedurally generated mazes. The stack leans on Azure services (SQL Database, Blob Storage, Key Vault, OpenAI) but falls back to local generation when cloud integrations are unavailable.

Project Structure

• Backend/GridRunners.Core/ – shared models, entity configurations, DTOs, and the maze generation abstractions used by every service.
• Backend/GridRunners.Api/ – ASP.NET Core Web API that exposes authentication, user profile, and maze lobby endpoints.
• Backend/GridRunners.SignalR/ – ASP.NET Core SignalR host that streams real-time gameplay updates and optionally drives maze creation through Azure OpenAI.
• frontend/ – React + TypeScript client that manages auth, lobby flows, and the live maze UI (keyboard + swipe).

Backend API (GridRunners.Api)

Key capabilities

• JWT authentication with refresh tokens. User accounts are provisioned on first-login and secured with SHA-256 password hashing.
• Rate limiting policies: /Auth/login capped at 5 requests per 5 minutes per IP, authenticated routes at 100 requests/min per user.
• API versioning (url segments or ?api-version=), swagger UI enabled in Development.
• SQL Server persistence via Entity Framework Core, including many-to-many relationships between users and games.
• Azure Blob Storage integration for profile images (images resized to a max 1024px before upload).
• Azure Key Vault + DefaultAzureCredential to hydrate secrets (JWT signing key, storage credentials).

Primary routes (/api/v1/…)

• POST Auth/login, POST Auth/refresh, POST Auth/logout.
• POST MazeGame (create), GET MazeGame/available, POST MazeGame/{id}/join, DELETE MazeGame/{id}.
• PUT User/display-name, POST User/profile-image, GET User/profile.

Run locally

1. Install .NET SDK 8.0 and ensure SQL Server (local or remote) is reachable.
2. Configure secrets (environment variables or dotnet user-secrets):
   • ConnectionStrings__DefaultConnection
   • KeyVault__Url (if skipping Key Vault, provide Auth__Secret directly in appsettings)
   • AzureStorage__AccountName, AzureStorage__ContainerName, AzureStorage__UserImagesPath
   • Auth__Issuer, Auth__Audience, Auth__ExpirationHours, Auth__SecretKeyName
3. Apply migrations: dotnet ef database update --project Backend/GridRunners.Api
4. Run: dotnet run --project Backend/GridRunners.Api (listens on https://localhost:7119 by default).

Real-Time Hub (GridRunners.SignalR)

Highlights

• Shares the same SQL database so hub events reflect REST mutations instantly.
• Authenticates via the same JWT issuer/audience; tokens are accepted via query string for WebSocket handshakes.
• MazeGameHub keeps players in SignalR groups, broadcasts movement, detects disconnects, and tears down empty lobbies.
• Optional Azure OpenAI integration (OpenAI.Enabled=true) generates balanced mazes; when disabled or failing, the fallback generator in MazeGame runs server-side.

Run locally

1. Mirror the API configuration for ConnectionStrings, KeyVault, and Authentication.
2. Set OpenAI keys (if used) in Key Vault entries referenced by OpenAI configuration.
3. Launch with dotnet run --project Backend/GridRunners.SignalR (default https://localhost:7092).

Shared Core Library

• MazeGame domain model enforces lobby limits, winner tracking, grid validation, and supports both AI-generated and locally generated mazes.
• User entity encapsulates password rules, refresh-token lifecycle, and profile metadata.
• DTOs (AuthDto, MazeGameDtos, UserDtos) define the serialized contracts consumed by both API and frontend.

Frontend (React + TypeScript)

Key capabilities

• Auth context that stores tokens in localStorage, auto-refreshes on 401 responses, and drives guarded routes.
• REST clients (axios with interceptors) for Auth/User/MazeGame endpoints, using process.env.BACKEND_API_URL (defaults to https://localhost:7119/api/v1).
• SignalR service that reconnects with backoff and handles move, start, and game-over events.
• Pages: login with live validation, profile & match history, lobby join/manage, real-time game board with keyboard + touch controls.

Run locally

1. Install Node.js 18+.
2. In frontend/, create .env entries as needed:
   • BACKEND_API_URL=https://localhost:7119/api/v1
   • REACT_APP_API_URL=https://localhost:7092
3. Install dependencies: npm install
4. Start the dev server: npm start (served at http://localhost:3000).

Configuration Reference

Component	Keys	Purpose
API	ConnectionStrings__DefaultConnection	SQL Server connection string
API	Auth__Issuer, Auth__Audience, Auth__ExpirationHours, Auth__Secret or Auth__SecretKeyName	JWT issuance settings
API	AzureStorage__AccountName, AzureStorage__ContainerName, AzureStorage__UserImagesPath	Blob storage for profile images
API & SignalR	KeyVault__Url / Authentication__SecretKeyName	Azure Key Vault endpoint to pull secrets
SignalR	OpenAI__Enabled plus secret key names (ModelIdKeyName, etc.)	Toggle AI maze generation and point to Key Vault secrets
Frontend	BACKEND_API_URL, REACT_APP_API_URL	REST base URL and SignalR hub URL

Gameplay Flow

1. Player logs in (new usernames are auto-created) and lands on the profile page.
2. Lobby view lists joinable games; creating a lobby immediately registers the creator as the first participant.
3. When ready, players signal the hub to start—the hub generates/loads the maze, assigns colors/positions, and emits GameStarted with the grid state.
4. Clients send discrete move requests via SignalR; the server validates collisions, finishes, and broadcasts PlayerMoved and GameOver events.
5. Disconnect handling removes idle players and, if everyone leaves, cleans up the lobby/game records.