|
| 1 | +# Codebreaker Backend |
| 2 | + |
| 3 | +Codebreaker Backend is a .NET 9 microservices solution using .NET Aspire orchestration for a game platform. The solution includes game APIs, clients, analyzers, and multiple service components with Azure integrations. |
| 4 | + |
| 5 | +Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here. |
| 6 | + |
| 7 | +## Working Effectively |
| 8 | + |
| 9 | +### Prerequisites |
| 10 | +- Install .NET 9 SDK: `curl -sSL https://dot.net/v1/dotnet-install.sh | bash /dev/stdin --channel 9.0` |
| 11 | +- Install .NET 8 runtime for multi-targeted tests: `curl -sSL https://dot.net/v1/dotnet-install.sh | bash /dev/stdin --channel 8.0 --runtime dotnet` |
| 12 | +- Set PATH: `export PATH="$HOME/.dotnet:$PATH"` |
| 13 | +- Verify installation: `dotnet --version` should show 9.0.103 or later |
| 14 | + |
| 15 | +### Build Individual Solutions |
| 16 | +The repository contains multiple solution files that can be built independently: |
| 17 | + |
| 18 | +- `dotnet build src/Codebreaker.Analyzers.sln` -- takes 9 seconds. NEVER CANCEL. Set timeout to 20+ seconds. |
| 19 | +- `dotnet build src/Codebreaker.Backend.Models.sln` -- takes 7 seconds. NEVER CANCEL. Set timeout to 20+ seconds. |
| 20 | +- `dotnet build src/Codebreaker.Backend.slnx` -- main solution |
| 21 | +- `dotnet build src/Codebreaker.GameAPIs.Client.sln` -- takes 10 seconds. NEVER CANCEL. Set timeout to 20+ seconds. |
| 22 | +- `dotnet build src/Codebreaker.Backend.Cosmos.sln` -- library solution |
| 23 | +- `dotnet build src/Codebreaker.Backend.SqlServer.sln` -- library solution |
| 24 | +- `dotnet build src/Codebreaker.Backend.Postgres.sln` -- library solution |
| 25 | + |
| 26 | +### Test Individual Solutions |
| 27 | +- `dotnet test src/Codebreaker.Analyzers.sln` -- takes 4 seconds, runs 53 tests. NEVER CANCEL. Set timeout to 15+ seconds. |
| 28 | +- `dotnet test src/Codebreaker.Backend.Models.sln` -- requires .NET 8 runtime for net8.0 tests |
| 29 | +- `dotnet test src/Codebreaker.GameAPIs.Client.sln` -- takes 8 seconds, runs 11 tests. NEVER CANCEL. Set timeout to 20+ seconds. |
| 30 | + |
| 31 | +### Build Individual Projects |
| 32 | +Individual projects build faster than full solutions: |
| 33 | +- `dotnet build src/services/gameapis/Codebreaker.GameAPIs/Codebreaker.GameAPIs.csproj` -- takes 3.5 seconds |
| 34 | + |
| 35 | +### Run Individual Services |
| 36 | +Services can be run independently for development: |
| 37 | +- Game APIs: `cd src/services/gameapis/Codebreaker.GameAPIs && dotnet run` -- runs on http://localhost:9400 |
| 38 | +- Services start quickly but require proper database configuration for full functionality |
| 39 | + |
| 40 | +### Full Solution Build Limitations |
| 41 | +- The main solution `src/Codebreaker.Backend.slnx` is in .slnx format |
| 42 | +- Building the AppHost project requires private Azure DevOps feeds: `dotnet build src/services/host/Codebreaker.AppHost/Codebreaker.AppHost.csproj` -- takes 45+ minutes and requires Azure DevOps authentication. NEVER CANCEL. Set timeout to 60+ minutes. |
| 43 | +- Azure deployment requires `azd` CLI and Azure authentication |
| 44 | + |
| 45 | +## Central Package Management |
| 46 | +The repository uses Central Package Management with `src/Directory.Packages.props`. When adding PackageReference items: |
| 47 | +- Do NOT specify versions in .csproj files |
| 48 | +- Add package versions to `src/Directory.Packages.props` |
| 49 | +- Build will fail if PackageReference has version but package not in Directory.Packages.props |
| 50 | +- Common packages already configured: Microsoft.NET.Test.Sdk, xunit, Moq, coverlet.collector |
| 51 | + |
| 52 | +## Validation |
| 53 | +- Always run `dotnet format --verify-no-changes src/[solution].sln` before committing -- takes 10 seconds with detailed formatting analysis. NEVER CANCEL. Set timeout to 30+ seconds. |
| 54 | +- Always build and test changes on individual solutions before attempting full stack |
| 55 | +- Individual Game APIs service can be tested by running on localhost:9400 |
| 56 | +- Test health endpoint: `curl http://localhost:9400/health` (expects 500 error without database) |
| 57 | +- Test Swagger: `curl http://localhost:9400/swagger` (expects 301 redirect) |
| 58 | + |
| 59 | +## Architecture Overview |
| 60 | +**Key Projects:** |
| 61 | +- **AppHost**: .NET Aspire orchestration host (src/services/host/Codebreaker.AppHost) |
| 62 | +- **Game APIs**: Core game service (src/services/gameapis/Codebreaker.GameAPIs) |
| 63 | +- **Analyzers**: Game logic analyzers (src/services/common/Codebreaker.GameAPIs.Analyzers) |
| 64 | +- **Client Libraries**: API clients (src/clients/Codebreaker.GameAPIs.Client) |
| 65 | +- **Blazor App**: Web UI (src/services/Codebreaker.Blazor) |
| 66 | +- **Gateway**: API Gateway with YARP (src/services/gateway) |
| 67 | +- **Live Service**: SignalR service (src/services/live) |
| 68 | +- **Ranking Service**: Game ranking (src/services/ranking) |
| 69 | +- **User Service**: User management (src/services/user) |
| 70 | +- **Bot Services**: Game bots (src/services/bot) |
| 71 | + |
| 72 | +**Data Access:** |
| 73 | +- Cosmos DB library: src/services/common/Codebreaker.Data.Cosmos |
| 74 | +- SQL Server library: src/services/common/Codebreaker.Data.SqlServer |
| 75 | +- PostgreSQL library: src/services/common/Codebreaker.Data.Postgres |
| 76 | + |
| 77 | +## Azure Services Integration |
| 78 | +The solution integrates with: |
| 79 | +- Azure Container Apps |
| 80 | +- Azure Cosmos DB |
| 81 | +- Azure Active Directory B2C |
| 82 | +- Azure SignalR Services |
| 83 | +- Azure App Configuration |
| 84 | +- Azure Event Hub |
| 85 | +- Azure Storage |
| 86 | +- Azure Key Vault |
| 87 | + |
| 88 | +## Common Tasks |
| 89 | +Use these outputs instead of running commands to save time: |
| 90 | + |
| 91 | +### Repository Structure |
| 92 | +``` |
| 93 | +src/ |
| 94 | +├── Codebreaker.*.sln # Individual solution files |
| 95 | +├── Codebreaker.Backend.slnx # Main solution (.slnx format) |
| 96 | +├── Directory.Build.props # Common build properties |
| 97 | +├── Directory.Packages.props # Central package management |
| 98 | +├── clients/ # Client libraries |
| 99 | +├── services/ |
| 100 | +│ ├── bot/ # Game bot services |
| 101 | +│ ├── common/ # Shared libraries (analyzers, data, models) |
| 102 | +│ ├── gameapis/ # Core game service |
| 103 | +│ ├── gateway/ # API gateway |
| 104 | +│ ├── host/ # Aspire AppHost |
| 105 | +│ ├── live/ # SignalR service |
| 106 | +│ ├── ranking/ # Ranking service |
| 107 | +│ ├── user/ # User service |
| 108 | +│ └── Codebreaker.Blazor/ # Web UI |
| 109 | +``` |
| 110 | + |
| 111 | +### Target Frameworks |
| 112 | +- Primary: net9.0 |
| 113 | +- Multi-targeting: net8.0;net9.0 (for libraries) |
| 114 | +- Test projects: primarily net9.0 |
| 115 | + |
| 116 | +### Known Build Issues |
| 117 | +- Central Package Management requires proper setup |
| 118 | +- Private Azure DevOps feeds with anonymous access needed for full solution |
| 119 | +- Some test projects may need package reference fixes |
| 120 | +- Docker/container builds require Azure authentication |
| 121 | + |
| 122 | +### Development Workflow |
| 123 | +1. Make code changes to individual projects |
| 124 | +2. Build individual solutions: `dotnet build src/[specific].sln` |
| 125 | +3. Run tests: `dotnet test src/[specific].sln` |
| 126 | +4. Format code: `dotnet format src/[specific].sln` |
| 127 | +5. Test individual services with `dotnet run` |
| 128 | +6. Use AppHost for full stack development (requires Azure setup) |
| 129 | + |
| 130 | +### Performance Expectations |
| 131 | +- Individual solution builds: 3-10 seconds |
| 132 | +- Individual solution tests: 4-8 seconds |
| 133 | +- Code formatting: 10 seconds |
| 134 | +- Full AppHost build: 5+ minutes (requires private feeds) |
| 135 | +- Service startup: 2-5 seconds |
0 commit comments