English
How to follow the tutorial
The route
Chatex has about 15 000 lines of C# and TypeScript. Nobody writes such a project from top to bottom in one go, and nobody should read it that way either. The tutorial builds it in six modules and 24 topics, in the order in which the parts depend on each other (Fig. 1.6).
Fig. 1.6. The route of the tutorial
Why this order — from the database up — and not, for example, from the screens down?
- Every layer is built on something that already works. A service needs repositories, an endpoint needs a service, an Angular page needs an endpoint. Building bottom-up means you never write code against something imaginary.
- Every layer can be checked on its own. The data layer is checked with tests against a real PostgreSQL; the business layer with tests of its services; the API with Scalar,
.httprequests and HTTP tests; the client in the browser. You do not have to wait until the end to see your code work. - It matches the reference code. Each layer is a separate project, so at every checkpoint you can compare your project with the same project of the reference.
The price is that the first visible screen appears only in module 5. Until then, tests are your screen: in modules 2–4, every topic ends with tests that prove the new code works.
The step pattern
Every topic is a stage of the build. Its chapters contain numbered steps, and every step has the same three parts:
Why — the problem the step solves and the design decision behind it, with the alternatives that were rejected. Theory that deserves a closer look (patterns, SOLID principles, HTTP or security details) is in boxes like this one:
A box with background
Such boxes explain a concept and link to the C# course where it is taught in depth. You can skip them on a second pass.
Do — the files to create or change and the commands to run. Each listing is preceded by a sentence saying what it adds.
Check — how to see that the step worked: a command and its expected output, a test run, a request in Scalar or a click in the browser. Do not go on until the check passes:
Check
This is what a check looks like.
Typical mistakes are marked with a warning box:
A typical mistake
What goes wrong, how it shows itself and how to fix it.
Reading the listings
A listing is titled with the path of its file, relative to the repository root, so you always know where to put the code:
cs
namespace Chatex.Data.Entities;
public enum ChatType
{
/// <summary>One-to-one conversation between exactly two users.</summary>
Direct,
/// <summary>Many members, everyone can post.</summary>
Group,
/// <summary>Broadcast: only owner and admins post, everyone else subscribes.</summary>
Channel,
}A file often grows over several topics. When a topic adds lines to a file you created earlier, the new lines are highlighted in green, and the lines around them are shown so that you can find the place:
cs
public class ChatMember : IHasCreatedAt
{
public Guid ChatId { get; set; }
// ...
public bool IsMuted { get; set; }
public Chat Chat { get; set; } = null!;
public User User { get; set; } = null!;
}In a few listings of the Angular client, some lines are highlighted in yellow, and the title of the listing ends with (temporary lines): these lines differ from the final file only for now — for example, a placeholder that a later topic replaces — and the text says which topic changes them.
The comment // ... (<!-- ... --> in HTML, # ... in YAML and shell scripts) stands for lines that are not shown because they did not change or are not important for the step. Never type the // ... itself.
Commands are written for PowerShell 7 (pwsh), which runs on Windows, macOS and Linux. Each block contains one command; run them in the order shown, from the repository root unless the step says otherwise. Commands that run on the Ubuntu server (topics 23–24) are written for bash.
Your repository and the reference
Create your own Git repository in topic 2 and commit at every checkpoint, with the commit message the checkpoint suggests. A clean history of small commits lets you return to a working state when an experiment goes wrong:
powershell
git switch -c experimentpowershell
git switch mainThe reference code (the folder D:\Work\Chatex-Reference from Run the reference version) is the final state of the project. When a step does not work, compare your file with the reference one:
powershell
git diff --no-index Source/Chatex.Data/Entities/Chat.cs D:\Work\Chatex-Reference\Source\Chatex.Data\Entities\Chat.csLines marked - exist only in your file, lines marked + only in the reference. Remember that a reference file may already contain lines that a later topic adds; the listings in the tutorial tell you what belongs to the current step.
Every page links the files it discusses at commit 27c83c6 on GitHub, so you can also read the reference code in the browser.
How long it takes
A topic takes between one and four hours of focused work, depending on its size and on how much of the background is new to you. Plan for one or two topics a week, and do not skip the checks and the self-check questions: they are what turns a copied project into an understood one.