An open-source chess platform focused on playing chess against other players or the computer.
The first milestone is the core experience of playing a complete chess game against another player or a computer opponent. Additional features will be considered after this core functionality is in place.
The repository contains a .NET 10 backend scaffold, an Angular frontend, and Aspire orchestration with PostgreSQL and an EF Core migration worker.
- C# and .NET 10 for the backend, EF Core with PostgreSQL for persistence.
- Aspire for local orchestration and observability.
- xUnit v3 for tests.
- Angular for the frontend.
src/— backend and frontend application source code.src/cr-platform-web-app/— Angular frontend.tests/— automated tests.docs/— project documentation.orchestration/— application orchestration configuration.scripts/— repository development and maintenance scripts..github/— GitHub configuration and CI workflows.
Empty directories may not appear in a fresh clone until files are added.
Install the .NET SDK specified in global.json. The repository allows newer patches within the same SDK feature band.
AppHost uses DnxPinned to run the Aspire CLI version paired with its Aspire.AppHost.Sdk through .NET 10's dnx. A global Aspire CLI installation is not required. The first use can download the pinned CLI and prepare its Dashboard/orchestration bundle; --no-restore only skips the project's NuGet restore, not CLI bundle setup.
Install a Node.js version supported by Angular 22: Node.js 22.22.3+, 24.15.0+, or 26+ (see the frontend's package.json engines). npm is used for frontend dependencies; package-lock.json is checked in for reproducible installs.
Shared configuration includes:
.editorconfigfor formatting and C# style conventions..gitattributesfor Git line ending normalization.Directory.Build.propsfor shared build settings and NuGet lock file generation.Directory.Packages.propsfor central NuGet package version management.NuGet.Configfor package sources..config/dotnet-tools.jsonfor repository-local .NET tools.
All projects use the ChessRealms.Platform prefix:
src/ChessRealms.Platform.Domain— domain model; no project dependencies.src/ChessRealms.Platform.Application— application layer; references Domain.src/ChessRealms.Platform.Infrastructure— persistence and external integrations; references Application.src/ChessRealms.Platform.Api— HTTP entry point; references Application, Infrastructure, and ServiceDefaults.src/ChessRealms.Platform.MigrationWorker— console host that applies migrations and exits; references Infrastructure and ServiceDefaults.orchestration/ChessRealms.Platform.AppHost— PostgreSQL, migration worker, API, and Angular frontend orchestration.orchestration/ChessRealms.Platform.ServiceDefaults— shared telemetry, health checks, service discovery, and HTTP resilience.tests/— xUnit v3 projects referencing Api, Application, Domain, and Infrastructure respectively.
Infrastructure leaves room for integrations beyond persistence. PlatformDbContext currently has no entities. An empty InitialCreate migration establishes the migration pipeline without adding business tables.
The isolated Infrastructure/Identity module provides ASP.NET Core Identity stores
in a separate IdentityDbContext, using the identity schema in the same PostgreSQL
database. See architecture decisions for boundaries and scope.
Run from the repository root:
dotnet tool restore
dotnet restore ChessRealms.Platform.slnx --locked-mode
dotnet build ChessRealms.Platform.slnx --no-restore
dotnet test ChessRealms.Platform.slnx --no-build --no-restoreInfrastructure tests require Docker with Linux containers. Testcontainers starts a temporary PostgreSQL 18.3 container and verifies migrations and Identity persistence; it does not use the development database or AppHost. The other test projects are currently empty. Package versions are centralized and each project has a NuGet lock file.
For the frontend:
cd src/cr-platform-web-app
npm ci
npm run build
npm test -- --watch=falseThe Angular app stays outside the .NET solution; Aspire runs it directly from its directory. Use npm start there to run the frontend independently at http://localhost:4200.
The CI workflow runs on every push and pull request with separate backend and frontend jobs on Ubuntu. The backend uses the SDK from global.json, restores with --locked-mode, builds, and runs tests without restoring or rebuilding. Infrastructure tests use the runner's Docker daemon for temporary PostgreSQL containers. The frontend uses Node.js 26 and the npm version from package.json, installs with npm ci, builds the development configuration, and runs Vitest without watch mode. CI does not start AppHost.
Start Docker Desktop with Linux containers, then run:
dotnet dev-certs https --trust
dotnet run --project orchestration/ChessRealms.Platform.AppHostOpen the dashboard URL printed in the terminal. AppHost starts PostgreSQL with a persistent Docker volume, waits for database readiness, runs migrations, then starts api only if the worker exits successfully. Connection strings are supplied by Aspire; no database password is stored in source control. The API exposes /openapi/v1.json, /health (including database connectivity), and /alive in Development.
AppHost also installs the frontend's npm dependencies and starts the Angular development server as web. Open its HTTP endpoint from the dashboard. The frontend can start independently of the backend.
The worker has a two-minute timeout, configurable through Migration__Timeout (for example, 00:05:00). Failure or cancellation returns a nonzero exit code and prevents the API from starting. Restart AppHost to run migrations again after changing the model.
dotnet ef migrations add MigrationName --context PlatformDbContext --project src/ChessRealms.Platform.Infrastructure --output-dir Persistence/MigrationsFor Identity migrations, use --context IdentityDbContext --output-dir Identity/Persistence/Migrations instead.
The design-time factories allow scaffolding without starting PostgreSQL or AppHost. For EF commands that connect to a database, set ConnectionStrings__platform to the connection string shown in the Aspire dashboard. Apply migrations through MigrationWorker, which migrates both contexts; the API does not migrate the database on startup.
Documentation is maintained in English.
AGENTS.md contains concise project conventions and verification commands. Codex uses your app settings; no project-specific permission profile or command rules are required.
Contribution guidelines are maintained at the organization level. Consult those guidelines before submitting a contribution.
Licensed under the Apache License, Version 2.0.