English
Architecture
The system as a whole
In production Chatex runs on one Ubuntu server (Fig. 1.3). The browser talks only to Nginx, a web server that terminates HTTPS. Nginx returns the files of the Angular app (index.html, JavaScript, CSS) and forwards two kinds of requests to the ASP.NET Core application Chatex.Api, which listens only on the local address 127.0.0.1:5000:
/api/...— ordinary HTTP requests: sign in, load the chat list, send a message, upload a file;/hubs/chat— one long-lived WebSocket connection per browser tab, through which the server pushes events (a new message, someone is typing) the moment they happen.
Chatex.Api stores data in PostgreSQL and uploaded files in a folder on disk.
Fig. 1.3. System architecture
During development the picture is the same, only without Nginx: the Angular development server on port 4200 forwards /api and /hubs to the API on port 5214 (topic 15), and PostgreSQL runs in a Docker container (topic 2).
Three backend layers
The backend is split into three projects — layers — and each layer references only the layer below it (Fig. 1.4).
Fig. 1.4. The layers of Chatex
Why not put everything into one project? Because each layer has one reason to change and can be understood, replaced and tested on its own:
- Chatex.Data knows how data is stored: tables, indexes, SQL queries through EF Core. It knows nothing about HTTP or about who is allowed to do what.
- Chatex.Core knows the rules of the messenger: a channel subscriber cannot post, an edited message must belong to its sender, a refresh token can be used once. It works with repository interfaces and never touches the database context directly, and it knows nothing about HTTP.
- Chatex.Api knows the web: routes, status codes, tokens in headers and cookies, WebSocket connections. Each endpoint is a few lines that read the request, call one service method and turn the result into an HTTP response.
The direction of the references makes the rules hard to break: the compiler simply does not let Chatex.Data call a service, or Chatex.Core return an HTTP status code.
Dependency inversion
Sometimes a lower layer must trigger something in a higher one: after a message is saved, Chatex.Core must notify the connected browsers, which is the job of SignalR in Chatex.Api. Chatex.Core cannot reference Chatex.Api, so it declares an interface IChatNotifier, and Chatex.Api implements it. The lower layer owns the abstraction, the higher layer supplies the implementation through dependency injection. This is the D of SOLID — the dependency inversion principle (see Dependency injection in the C# course). We build it in topics 7 and 14.
How a request flows
Let us follow one request through the layers: Alice sends a message (Fig. 1.5).
Fig. 1.5. Sending a message through the layers
- The endpoint in Chatex.Api reads the user id from the access token and calls one service method.
- The service in Chatex.Core validates the command (the text is not empty and not too long).
- It loads the chat and the caller's membership through
ChatAccess, which applies the visibility rules, and checks the permissions: may this member post in this chat? - It changes entities through repositories and saves them with the Unit of Work in Chatex.Data, inside a transaction when several writes must succeed together.
- After the commit it calls
IChatNotifier, and the SignalR implementation pushes the event to every connected member. - The service returns a
Result: either the created message or an error such ascannot_post. The endpoint turns it into201 Createdor into an error response in the standard Problem Details format.
Every feature of the backend follows this path, so once you have built it for one feature, the others look familiar.
The technology stack
Table 1.2 lists the main technologies and why each one was chosen. You do not need to know them in advance: each one is introduced in the topic where it first appears.
Table 1.2. The technology stack
| Area | Choice | Why |
|---|---|---|
| Runtime | .NET 10, C# 14 | a long-term support release; one language for all backend layers |
| Database | PostgreSQL 18; EF Core 10 with Npgsql | a free, reliable relational database; EF Core maps C# classes to tables and generates migrations |
| HTTP API | ASP.NET Core Minimal APIs, Problem Details, OpenAPI with Scalar | little ceremony per endpoint; standard error format; an interactive API reference |
| Real time | ASP.NET Core SignalR | WebSocket with automatic fallback, groups and reconnection out of the box |
| Authentication | ASP.NET Core Identity, JWT bearer tokens, an HttpOnly refresh cookie | proven password hashing and lockout; stateless access tokens; a refresh token that JavaScript cannot read |
| Validation | FluentValidation | validation rules as small, testable classes |
| Tests | xUnit v3, Shouldly, Testcontainers, Respawn, WebApplicationFactory | tests run against a real PostgreSQL in Docker and against the real HTTP pipeline |
| Frontend | Angular 22 (standalone components, signals, zoneless), Tailwind CSS v4, Angular CDK, @microsoft/signalr, Vitest | a complete framework with TypeScript, routing, forms and HTTP; utility-first styling |
| CI/CD | GitHub Actions | checks every push; builds a release and deploys it to the server |
| Server | Ubuntu 26.04, Nginx, systemd, certbot | the standard Linux toolbox: a reverse proxy, a service manager and free HTTPS certificates |
The repository layout
The finished repository looks like this. You will create these folders one by one; for now, just get a feeling for where things live.
Chatex.slnx the solution
global.json the .NET SDK version and the test runner
Directory.Build.props build settings shared by every project
Directory.Packages.props the versions of all NuGet packages
compose.yaml PostgreSQL 18 for development
Run.ps1 developer commands
Source/
Chatex.Data/ Entities, Configurations, Repositories, Migrations, Storage
Chatex.Core/ Auth, Users, Chats, Messages, Attachments, Common
Chatex.Api/ Endpoints, Hubs, Infrastructure, Maintenance, Program.cs
Chatex.Web/ the Angular app
Tests/
Chatex.Testing/ a shared PostgreSQL container for the tests
Chatex.Data.Tests/ repository and storage tests
Chatex.Core.Tests/ service tests
Chatex.Api.Tests/ HTTP and SignalR tests against the running app
Deploy/ server files: systemd unit, Nginx site, activation script
Docs/ documentation
.github/workflows/ CI and deploymentCheck
Open the reference repository in your IDE (Chatex.slnx in Visual Studio or Rider, the folder in VS Code). Find the four projects of Source/ and, for each of them, open one file and say which layer it belongs to and why. For example, Source/Chatex.Data/Entities/Message.cs describes how a message is stored, so it belongs to the data layer.