You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Proof of Concept for a RESTful API built with .NET 10 (LTS) and ASP.NET Core. Manage football player data with SQLite, Entity Framework Core, Swagger documentation, and in-memory caching.
- 🧪 **High test coverage** - xUnit tests with automated reporting to Codecov and SonarCloud
41
-
- 📖 **Token-efficient documentation** - Custom instructions with coding guidelines, architecture rules, and agent workflows for AI-assisted development
Layered architecture with dependency injection via constructors and interface-based contracts.
@@ -196,31 +131,9 @@ graph RL
196
131
class AspNetCore,EFCore,MemoryCache feat;
197
132
```
198
133
199
-
### Arrow Semantics
200
-
201
-
Arrows follow the injection direction: `A --> B` means A is injected into B. Solid arrows (`-->`) represent active ASP.NET Core dependencies — services registered with the IoC container and invoked at runtime. Dotted arrows (`-.->`) represent test dependencies — test classes reference the types they exercise but are not injected into them.
202
-
203
-
### Composition Root Pattern
204
-
205
-
`Program` is the composition root: it registers all services, repositories, DbContext, mappers, validators, and middleware with the ASP.NET Core IoC container, which resolves them at runtime via constructor injection.
206
-
207
-
### Layered Architecture
208
-
209
-
Four layers: Initialization (`Program`), HTTP (`Controllers`, `Validators`), Business (`Services`, `Mappings`), and Data (`Repositories`, `Data`).
210
-
211
-
Framework and third-party packages are placed inside the subgraph of the layer that uses them — `Serilog` and `Swashbuckle` in Initialization, `ASP.NET Core` and `FluentValidation` in HTTP, `AutoMapper` in Business, `EF Core` in Data.
212
-
213
-
`Models` is a cross-cutting type concern — shared entities and DTOs consumed across all layers, with no logic of its own.
214
-
215
-
### Color Coding
216
-
217
-
Blue = core application packages, yellow = Microsoft platform packages, red = third-party libraries, green = tests.
218
-
219
-
*Simplified, conceptual view — not all components or dependencies are shown.*
220
-
221
-
## Architecture Decisions
222
-
223
-
See [Architecture Decision Records (ADRs)](adr/README.md) for documented decisions about this project's architecture, technology choices, and development practices.
134
+
> *Arrows follow the injection direction (A → B means A depends on B). Solid = runtime dependency, dotted = structural. Blue = core domain, red = third-party, green = tests.*
135
+
>
136
+
> *Significant design decisions are documented as ADRs in [`adr/`](adr/README.md).*
224
137
225
138
## API Reference
226
139
@@ -238,6 +151,17 @@ Interactive API documentation is available via Swagger UI at `https://localhost:
238
151
-`DELETE /players/squadNumber/{squadNumber:int}` - Remove player
239
152
-`GET /health` - Health check
240
153
154
+
**Response Codes:**
155
+
156
+
| Code | Description |
157
+
| ---- | ----------- |
158
+
|`200 OK`| Successful GET/PUT |
159
+
|`201 Created`| Successful POST |
160
+
|`204 No Content`| Successful DELETE |
161
+
|`400 Bad Request`| Validation failed |
162
+
|`404 Not Found`| Player not found |
163
+
|`409 Conflict`| Duplicate squad number on POST |
164
+
241
165
For complete endpoint documentation with request/response schemas, explore the [interactive Swagger UI](https://localhost:9000/swagger/index.html).
242
166
243
167
## Prerequisites
@@ -275,24 +199,6 @@ The server will start on `https://localhost:9000`.
Tests are located in the `test/` directory and use xUnit for unit testing. Coverage reports are generated for controllers and services only.
295
-
296
202
## Containers
297
203
298
204
This project includes full Docker support with multi-stage builds and Docker Compose for easy deployment.
@@ -327,56 +233,7 @@ docker compose down -v
327
233
328
234
The containerized application runs on port 9000 and includes health checks that monitor the `/health` endpoint.
329
235
330
-
## Releases
331
-
332
-
This project uses **stadium-themed release names** inspired by famous football stadiums that hosted FIFA World Cup matches. Each release is named after a stadium (A-Z alphabetically), making versions memorable and fun.
333
-
334
-
### Release Naming Convention
335
-
336
-
Releases follow the pattern: `v{SEMVER}-{STADIUM}` (e.g., `v1.0.0-azteca`)
337
-
338
-
-**Semantic Version**: Standard versioning (MAJOR.MINOR.PATCH)
339
-
-**Stadium Name**: Alphabetically ordered codename from the [stadium list](CHANGELOG.md#stadium-release-names)
340
-
341
-
### Create a Release
342
-
343
-
To create a new release, follow this workflow:
344
-
345
-
#### 1. Update CHANGELOG.md
346
-
347
-
First, create a `release/` branch and document your changes in [CHANGELOG.md](CHANGELOG.md):
348
-
349
-
```bash
350
-
git checkout -b release/1.0.0-azteca
351
-
# Move items from [Unreleased] to new release section
352
-
# Example: [1.0.0 - azteca] - 2026-01-22
353
-
git add CHANGELOG.md
354
-
git commit -m "docs: prepare changelog for v1.0.0-azteca release"
355
-
git push origin release/1.0.0-azteca
356
-
# Open a PR, get it reviewed, and merge into master
357
-
```
358
-
359
-
#### 2. Create and Push Tag
360
-
361
-
Then create and push the version tag:
362
-
363
-
```bash
364
-
git tag -a v1.0.0-azteca -m "Release 1.0.0 - Azteca"
365
-
git push origin v1.0.0-azteca
366
-
```
367
-
368
-
#### 3. Automated CD Workflow
369
-
370
-
This triggers the CD workflow which automatically:
371
-
372
-
1. Validates the stadium name
373
-
2. Builds and tests the project in Release configuration
374
-
3. Publishes Docker images to GitHub Container Registry with three tags
375
-
4. Creates a GitHub Release with auto-generated changelog from commits
376
-
377
-
> 💡 Always update CHANGELOG.md before creating the tag. See [CHANGELOG.md](CHANGELOG.md#how-to-release) for detailed release instructions.
378
-
379
-
### Pull Docker Images
236
+
### Pull Docker images
380
237
381
238
Each release publishes multiple tags for flexibility:
> 💡 Additional environment variables (`ASPNETCORE_ENVIRONMENT=Production` and `ASPNETCORE_URLS=http://+:9000`) are set in the `Dockerfile`.
429
284
285
+
## Contributing
286
+
287
+
Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on the code of conduct and the process for submitting pull requests.
288
+
289
+
**Key guidelines:**
290
+
291
+
- Follow [Conventional Commits](https://www.conventionalcommits.org/) for commit messages
292
+
- Ensure all tests pass (`dotnet test`)
293
+
- Keep changes small and focused
294
+
- Review [.github/copilot-instructions.md](.github/copilot-instructions.md) for architectural patterns
295
+
296
+
**Testing:**
297
+
298
+
Run the test suite with xUnit:
299
+
300
+
```bash
301
+
# Run all tests
302
+
dotnet test
303
+
304
+
# Run tests with coverage report
305
+
dotnet test --results-directory "coverage" --collect:"XPlat Code Coverage" --settings .runsettings
|`docker compose down -v`| Stop and remove Docker volume |
446
-
447
-
## Contributing
448
-
449
-
Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on the code of conduct and the process for submitting pull requests.
450
-
451
-
**Key guidelines:**
452
-
453
-
- Follow [Conventional Commits](https://www.conventionalcommits.org/) for commit messages
454
-
- Ensure all tests pass (`dotnet test`)
455
-
- Keep changes small and focused
456
-
- Review [.github/copilot-instructions.md](.github/copilot-instructions.md) for architectural patterns
324
+
|**AI Commands**||
325
+
|`/pre-commit`| Runs linting, tests, and quality checks before committing |
Releases follow the pattern `v{SEMVER}-{STADIUM}` (e.g., `v1.0.0-azteca`). Codenames are drawn alphabetically from the [stadium list](CHANGELOG.md#stadium-release-names) of famous football stadiums that hosted FIFA World Cup matches.
4
+
5
+
## Workflow
6
+
7
+
### 1. Create a Release Branch
8
+
9
+
Branch protection prevents direct pushes to `master`, so all release prep goes through a PR:
10
+
11
+
```bash
12
+
git checkout master && git pull
13
+
git checkout -b release/v1.0.0-azteca
14
+
```
15
+
16
+
### 2. Update CHANGELOG.md
17
+
18
+
Move items from `[Unreleased]` to a new release section in [CHANGELOG.md](CHANGELOG.md):
19
+
20
+
```bash
21
+
# Move items from [Unreleased] to new release section
22
+
# Example: [1.0.0 - azteca] - 2026-01-22
23
+
git add CHANGELOG.md
24
+
git commit -m "docs: prepare changelog for v1.0.0-azteca release"
25
+
git push origin release/v1.0.0-azteca
26
+
# Open a PR, get it reviewed, and merge into master
27
+
```
28
+
29
+
### 3. Create and Push Tag
30
+
31
+
After the PR is merged, create and push the version tag from `master`:
32
+
33
+
```bash
34
+
git checkout master && git pull
35
+
git tag -a v1.0.0-azteca -m "Release 1.0.0 - Azteca"
36
+
git push origin v1.0.0-azteca
37
+
```
38
+
39
+
### 4. Automated CD Workflow
40
+
41
+
Pushing the tag triggers the CD workflow which automatically:
42
+
43
+
1. Validates the stadium name
44
+
2. Builds and tests the project in Release configuration
45
+
3. Publishes Docker images to GitHub Container Registry with three tags
46
+
4. Creates a GitHub Release with auto-generated changelog from commits
47
+
48
+
> 💡 Always update CHANGELOG.md before creating the tag. See [CHANGELOG.md](CHANGELOG.md) for the complete stadium list (A-Z) and release history.
49
+
50
+
## Docker Pull
51
+
52
+
Each release publishes multiple tags for flexibility:
53
+
54
+
```bash
55
+
# By semantic version (recommended for production)
0 commit comments