Cpnucleo

A .NET 10 architecture laboratoryOpen source, MIT licence

One project tracker, built several ways.

Cpnucleo is a .NET 10 laboratory. The same project-management domain is served over REST and gRPC, stored through EF Core and Dapper, guarded by its own OpenID Connect provider and used from a plain Astro client, so each choice can be read, run and compared.

Read the documentation Inspect the sourceOpen the live demo
Service map: the WebClient calls IdentityApi and, through NGINX, two WebApi instances; gRPC clients call GrpcServer; IdentityApi, WebApi and GrpcServer share PostgreSQL.sign-inRESTgRPC clientsWebClientAstro, staticIdentityApiOpenID ConnectNGINXleast_connGrpcServerRemote MessagingWebApi × 2FastEndpoints RESTPostgreSQLEF Core · Dapper
Fig. 1. Request paths in production. The WebClient is static; its scripts sign in through IdentityApi and call the REST API through NGINX. GrpcServer is an independent host on the same database.

§1What it compares

Built to be compared, not admired.

Each entry names the code behind it and the chapter that explains it.

  1. 1.1REST and gRPC over one model

    WebApi serves FastEndpoints REST and GrpcServer answers FastEndpoints Remote Messaging. Both expose the same CRUD operations, with a verified parity example.

    API reference →
  2. 1.2EF Core beside Dapper

    REST shows EF Core, an explicit Dapper repository and a generic Dapper unit of work; gRPC uses Dapper. PostgreSQL triggers keep soft deletes consistent for every writer.

    Database →
  3. 1.3Boundaries that fail the build

    Architecture tests load the real assemblies and fail when the Domain reaches for infrastructure or one transport host references the other.

    Testing →
  4. 1.4Its own OpenID Connect provider

    IdentityApi signs RS256 access tokens through the authorization code flow with PKCE. The APIs hold no keys; they read the published key set.

    Architecture →
  5. 1.5Tested images, then Hostinger

    GitHub Actions tests immutable amd64 images, deploys through Hostinger Docker Manager, smoke-tests production and only then publishes multi-arch manifests.

    Deployment →

§2Contents

Eleven chapters, read in any order.

Start with the overview or the learning lab. The rest work as reference.

Part IStart

  1. 01Project OverviewProject overview, maturity levels and repository entry points.
  2. 02Learning LabGuided exercises, verified examples, experiments, benchmarks and recovery.

Part IIOverview

  1. 03ArchitectureLayer boundaries, persistence comparisons and the service split.
  2. 04API ReferenceREST endpoints, the OpenID Connect provider and gRPC command contracts.
  3. 05WebClient CRUDAstro and native TypeScript forms, relation search, concurrency and live updates.
  4. 06DatabasePostgreSQL, EF Core, Dapper, migrations, integrity triggers and seed tools.

Part IIIDevelop

  1. 07Getting StartedPrerequisites, the minimal Docker lab, seed data and source development.
  2. 08Project StructureRepository tree: source projects, tests, labs and documentation.
  3. 09TechnologiesRuntime, libraries, infrastructure, observability and where versions live.
  4. 10TestingWhat each test suite proves and how to run it.
  5. 11DeploymentImages, GitHub Actions, NGINX, Hostinger and the release gates.

§3Run it

Run the lab on your own machine.

You need Docker. The seed step loads disposable example data and never touches production.

  1. Clone the repository and start the minimal lab profile.
  2. Seed it with example projects, people and time records.
  3. Sign in as demo@cpnucleo.local with the password from Getting Started.
Listing 1. The minimal labterminal
$ git clone https://github.com/jonathanperis/cpnucleo
$ cd cpnucleo
$ docker compose -f compose.lab.yaml up --build -d
$ docker compose -f compose.lab.yaml run --rm seed
# then open http://localhost:5400

Profiles for the full stack and observability, and the settings for running from source, are in Getting Started.