Skip to content

Commit b3c3f99

Browse files
Copilotchristiannagel
Copilot
and
christiannagel
committed
Add comprehensive Copilot instructions for the repository
Co-authored-by: christiannagel <1908285+christiannagel@users.noreply.github.com>
1 parent 3989068 commit b3c3f99

1 file changed

Lines changed: 134 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

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

0 commit comments

Comments
 (0)