Add ASP.NET Core backend hosting business rules; FE consumes via typed client

Move the authoritative business rules off the frontend into a real backend,
realising the BFF-lite + decision-DTO design (ADR-0001) that until now lived
only in static mock JSON.

Backend (backend/):
- ASP.NET Core (.NET 10) minimal API, contract-first, Swagger UI at /swagger.
- DDD Domain/ rules layer: profession derivation + applicable policy questions
  (DiplomaRules), herregistratie eligibility + reason (HerregistratieRule),
  scholing threshold (IntakePolicy), submit rejections + reference generation
  (SubmissionRules). In-memory seeded data, ProblemDetails (RFC 7807) errors.
- 27 xUnit tests: rule units + endpoint integration incl. BRP no-address and
  DUO not-found fallbacks and 422 submit paths.

Frontend (only infrastructure/ + contracts/ change, as the architecture promised):
- NSwag-generated typed client (api-client.ts), routed through Angular HttpClient
  via a small fetch adapter so the ?scenario= interceptor still applies.
- GET adapters use resource({ loader: client.x }); submit commands call the client
  and map ProblemDetails -> err. The hardcoded uren==0 / manual-diploma rules are
  deleted (now server-side). Domain, stores, UI and format validators unchanged.
- Deleted the now-dead public/mock/*.json.

Tooling/docs:
- npm start proxies /api -> backend; npm run gen:api regenerates the client;
  docker compose up runs both (bind mounts use :z for SELinux/Fedora).
- backend/README.md walkthrough: adding a policy question is a one-file backend
  change, no FE change, no client regen. Updated CLAUDE.md + ARCHITECTURE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

backend/src/BigRegister.Api/BigRegister.Api.csproj

@@ -0,0 +1,13 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Swashbuckle.AspNetCore" Version="10.2.3" />
+  </ItemGroup>
+
+</Project>

backend/src/BigRegister.Api/Contracts/Dtos.cs

@@ -0,0 +1,55 @@
+namespace BigRegister.Api.Contracts;
+
+// Wire contracts (the FE⇄BE seam). Field names + shapes mirror the frontend's
+// contracts/*.dto.ts 1:1; the NSwag-generated TS client is produced from these.
+
+public sealed record AdresDto(string Straat, string Postcode, string Woonplaats);
+
+public sealed record RegistrationStatusDto(
+    string Tag,
+    string? HerregistratieDatum = null,
+    string? GeschorstTot = null,
+    string? Reden = null,
+    string? DoorgehaaldOp = null);
+
+public sealed record RegistrationDto(
+    string BigNummer,
+    string Naam,
+    string Beroep,
+    string Registratiedatum,
+    string Geboortedatum,
+    RegistrationStatusDto Status);
+
+public sealed record PersonDto(string Naam, string Geboortedatum, AdresDto Adres);
+
+public sealed record HerregistratieDecisionsDto(bool EligibleForHerregistratie, string? HerregistratieReason);
+
+public sealed record DashboardViewDto(RegistrationDto Registration, PersonDto Person, HerregistratieDecisionsDto Decisions);
+
+public sealed record AantekeningDto(string Type, string Omschrijving, string Datum);
+
+public sealed record BrpAddressDto(bool Gevonden, AdresDto? Adres);
+
+public sealed record PolicyQuestionDto(string Id, string Vraag, string Type);
+
+public sealed record DuoDiplomaDto(
+    string Id,
+    string Naam,
+    string Instelling,
+    int Jaar,
+    string Beroep,
+    IReadOnlyList<PolicyQuestionDto> PolicyQuestions);
+
+public sealed record ManualDiplomaPolicyDto(IReadOnlyList<string> Beroepen, IReadOnlyList<PolicyQuestionDto> PolicyQuestions);
+
+public sealed record DuoLookupDto(IReadOnlyList<DuoDiplomaDto> Diplomas, ManualDiplomaPolicyDto Handmatig);
+
+public sealed record IntakePolicyDto(int ScholingThreshold);
+
+// Submit requests carry only the fields the server re-validates (UX-only fields
+// stay on the client). ponytail: a real submit would carry the full application.
+public sealed record RegistratieRequest(string DiplomaHerkomst);
+public sealed record IntakeRequest(int Uren);
+public sealed record HerregistratieRequest(int Uren);
+
+public sealed record ReferentieResponse(string Referentie);

backend/src/BigRegister.Api/Contracts/Mappers.cs

@@ -0,0 +1,33 @@
+using BigRegister.Domain.Diplomas;
+using BigRegister.Domain.People;
+using BigRegister.Domain.Registrations;
+
+namespace BigRegister.Api.Contracts;
+
+/// <summary>Domain → wire DTO mapping (the anti-corruption boundary, server side).</summary>
+public static class Mappers
+{
+    private static string D(DateOnly d) => d.ToString("yyyy-MM-dd");
+
+    public static RegistrationStatusDto ToDto(this RegistrationStatus s) => new(
+        Tag: s.Tag.ToString(),
+        HerregistratieDatum: s.HerregistratieDatum is { } h ? D(h) : null,
+        GeschorstTot: s.GeschorstTot is { } g ? D(g) : null,
+        Reden: s.Reden,
+        DoorgehaaldOp: s.DoorgehaaldOp is { } x ? D(x) : null);
+
+    public static RegistrationDto ToDto(this Registration r) => new(
+        r.BigNummer, r.Naam, r.Beroep, D(r.Registratiedatum), D(r.Geboortedatum), r.Status.ToDto());
+
+    public static AdresDto ToDto(this Adres a) => new(a.Straat, a.Postcode, a.Woonplaats);
+
+    public static PersonDto ToDto(this Person p) => new(p.Naam, D(p.Geboortedatum), p.Adres.ToDto());
+
+    public static PolicyQuestionDto ToDto(this PolicyQuestion q) => new(
+        q.Id, q.Vraag, q.Type == QuestionType.JaNee ? "ja-nee" : "tekst");
+
+    public static DuoDiplomaDto ToDto(this Diploma d) => new(
+        d.Id, d.Naam, d.Instelling, d.Jaar,
+        DiplomaRules.ProfessionFor(d),
+        DiplomaRules.QuestionsFor(d).Select(q => q.ToDto()).ToList());
+}

backend/src/BigRegister.Api/Data/SeedData.cs

@@ -0,0 +1,42 @@
+using BigRegister.Domain.Diplomas;
+using BigRegister.Domain.People;
+using BigRegister.Domain.Registrations;
+
+namespace BigRegister.Api.Data;
+
+/// <summary>
+/// In-memory seeded synthetic data — no DB, no real BRP/DUO. Stands in for the
+/// upstream systems so the API behaves like production for a demo.
+/// </summary>
+public static class SeedData
+{
+    public static readonly Registration Registration = new(
+        BigNummer: "19012345601",
+        Naam: "Dr. A. (Anna) de Vries",
+        Beroep: "Arts",
+        Registratiedatum: new DateOnly(2012, 9, 1),
+        Geboortedatum: new DateOnly(1985, 3, 14),
+        Status: new RegistrationStatus(StatusTag.Geregistreerd, HerregistratieDatum: new DateOnly(2027, 3, 1)));
+
+    public static readonly Person Person = new(
+        Naam: "Dr. A. (Anna) de Vries",
+        Geboortedatum: new DateOnly(1985, 3, 14),
+        Adres: new Adres("Lange Voorhout 9", "2514 EA", "Den Haag"));
+
+    /// <summary>The address BRP returns for the seeded citizen.</summary>
+    public static readonly Adres BrpAddress = Person.Adres;
+
+    public static readonly IReadOnlyList<Diploma> Diplomas = new[]
+    {
+        new Diploma("d1", "Geneeskunde", "Universiteit Leiden", 2011, "geneeskunde", Engelstalig: false),
+        new Diploma("d2", "Medicine (MBChB)", "University of Edinburgh", 2013, "geneeskunde", Engelstalig: true),
+        new Diploma("d3", "HBO-Verpleegkunde", "Hogeschool Utrecht", 2016, "verpleegkunde", Engelstalig: false),
+    };
+
+    public static readonly IReadOnlyList<(string Type, string Omschrijving, string Datum)> Notes = new[]
+    {
+        ("Specialisme", "Huisartsgeneeskunde", "2016-04-12"),
+        ("Aantekening", "Erkend opleider huisartsgeneeskunde", "2019-01-08"),
+        ("Specialisme", "Spoedeisende hulp (kaderopleiding)", "2021-06-30"),
+    };
+}

backend/src/BigRegister.Api/Domain/Diplomas/Diploma.cs

@@ -0,0 +1,22 @@
+namespace BigRegister.Domain.Diplomas;
+
+public enum QuestionType
+{
+    JaNee,
+    Tekst,
+}
+
+public sealed record PolicyQuestion(string Id, string Vraag, QuestionType Type);
+
+/// <summary>
+/// A diploma as DUO knows it. The profession and the applicable policy questions
+/// are NOT stored on the diploma — they are DERIVED by the rules below from its
+/// attributes (<see cref="Opleiding"/>, <see cref="Engelstalig"/>).
+/// </summary>
+public sealed record Diploma(
+    string Id,
+    string Naam,
+    string Instelling,
+    int Jaar,
+    string Opleiding,
+    bool Engelstalig);

backend/src/BigRegister.Api/Domain/Diplomas/DiplomaRules.cs

@@ -0,0 +1,68 @@
+namespace BigRegister.Domain.Diplomas;
+
+/// <summary>
+/// SERVER-OWNED business rules for diplomas. This is the single place a policy
+/// changes: which profession a study program maps to, and which policy questions
+/// (geldigheidsvragen) apply to a diploma. The frontend renders these; it never
+/// derives them.
+/// </summary>
+public static class DiplomaRules
+{
+    // RULE: study program → BIG profession.
+    private static readonly Dictionary<string, string> ProfessionByProgram = new(StringComparer.OrdinalIgnoreCase)
+    {
+        ["geneeskunde"] = "Arts",
+        ["verpleegkunde"] = "Verpleegkundige",
+        ["fysiotherapie"] = "Fysiotherapeut",
+        ["farmacie"] = "Apotheker",
+        ["tandheelkunde"] = "Tandarts",
+    };
+
+    public static string ProfessionFor(Diploma d) =>
+        ProfessionByProgram.TryGetValue(d.Opleiding, out var beroep) ? beroep : "Onbekend";
+
+    /// <summary>Professions a user may declare for a manual (unlisted) diploma.</summary>
+    public static IReadOnlyList<string> ManualProfessions() =>
+        ProfessionByProgram.Values.Distinct().ToList();
+
+    // --- Policy questions (geldigheidsvragen) ---
+
+    private static readonly PolicyQuestion NlTaalEngelstalig = new(
+        "nl-taalvaardigheid",
+        "Uw opleiding was Engelstalig. Beheerst u de Nederlandse taal op het vereiste niveau (B2)?",
+        QuestionType.JaNee);
+
+    private static readonly PolicyQuestion NlTaalManual = new(
+        "nl-taalvaardigheid",
+        "Beheerst u de Nederlandse taal op het vereiste niveau (B2)?",
+        QuestionType.JaNee);
+
+    private static readonly PolicyQuestion DiplomaErkend = new(
+        "diploma-erkend",
+        "Is uw diploma erkend door de Nederlandse overheid (bijv. via Nuffic)?",
+        QuestionType.JaNee);
+
+    private static readonly PolicyQuestion Toelichting = new(
+        "toelichting",
+        "Geef een korte toelichting op uw diploma en opleiding.",
+        QuestionType.Tekst);
+
+    /// <summary>
+    /// RULE: an English-language diploma requires proof of Dutch proficiency (B2).
+    /// Add a question here to apply it to a (set of) diploma(s) — a single backend
+    /// change, no frontend change.
+    /// </summary>
+    public static IReadOnlyList<PolicyQuestion> QuestionsFor(Diploma d)
+    {
+        var questions = new List<PolicyQuestion>();
+        if (d.Engelstalig)
+            questions.Add(NlTaalEngelstalig);
+        return questions;
+    }
+
+    /// <summary>
+    /// RULE: a manual diploma is unverified, so the strictest (maximal) set applies.
+    /// </summary>
+    public static IReadOnlyList<PolicyQuestion> ManualQuestions() =>
+        new[] { NlTaalManual, DiplomaErkend, Toelichting };
+}

backend/src/BigRegister.Api/Domain/Intake/IntakePolicy.cs

@@ -0,0 +1,11 @@
+namespace BigRegister.Domain.Intake;
+
+/// <summary>
+/// SERVER-OWNED config value. Below this many NL work-hours the scholing question
+/// is required. The frontend receives this value and applies it for instant UX
+/// feedback, but the backend re-validates on submit as the authority.
+/// </summary>
+public static class IntakePolicy
+{
+    public const int ScholingThreshold = 1000;
+}

backend/src/BigRegister.Api/Domain/People/Person.cs

@@ -0,0 +1,5 @@
+namespace BigRegister.Domain.People;
+
+public sealed record Adres(string Straat, string Postcode, string Woonplaats);
+
+public sealed record Person(string Naam, DateOnly Geboortedatum, Adres Adres);

backend/src/BigRegister.Api/Domain/Registrations/HerregistratieRule.cs

@@ -0,0 +1,32 @@
+namespace BigRegister.Domain.Registrations;
+
+/// <summary>
+/// SERVER-OWNED business rule (ported from the frontend reference impl
+/// registration.policy.ts:isHerregistratieEligible). A registration may apply for
+/// herregistratie only while active and within the window before its deadline.
+/// The endpoint ships the result as a decision flag + reason; the frontend renders it.
+/// </summary>
+public static class HerregistratieRule
+{
+    public const int WindowMonths = 12;
+
+    public static DateOnly? Deadline(Registration reg) =>
+        reg.Status.Tag == StatusTag.Geregistreerd ? reg.Status.HerregistratieDatum : null;
+
+    public static (bool Eligible, string? Reason) Evaluate(
+        Registration reg, DateOnly today, int windowMonths = WindowMonths)
+    {
+        var deadline = Deadline(reg);
+        if (deadline is null)
+            return (false, "Geen actieve registratie.");
+
+        var windowStart = deadline.Value.AddMonths(-windowMonths);
+        return today >= windowStart
+            ? (true, $"Registratie verloopt binnen {windowMonths} maanden ({deadline:yyyy-MM-dd}).")
+            : (false, $"Herregistratie kan vanaf {windowStart:yyyy-MM-dd}.");
+    }
+
+    /// <summary>Invariant: a non-active status must not carry a herregistratie date.</summary>
+    public static bool IsStatusConsistent(RegistrationStatus s) =>
+        s.Tag != StatusTag.Geregistreerd || s.HerregistratieDatum is not null;
+}

backend/src/BigRegister.Api/Domain/Registrations/Registration.cs

@@ -0,0 +1,28 @@
+namespace BigRegister.Domain.Registrations;
+
+/// <summary>The three states a BIG registration can be in.</summary>
+public enum StatusTag
+{
+    Geregistreerd,
+    Geschorst,
+    Doorgehaald,
+}
+
+/// <summary>
+/// Status as a flat record: only <see cref="StatusTag.Geregistreerd"/> carries a
+/// herregistratie deadline. The frontend mirrors this as a discriminated union.
+/// </summary>
+public sealed record RegistrationStatus(
+    StatusTag Tag,
+    DateOnly? HerregistratieDatum = null,
+    DateOnly? GeschorstTot = null,
+    string? Reden = null,
+    DateOnly? DoorgehaaldOp = null);
+
+public sealed record Registration(
+    string BigNummer,
+    string Naam,
+    string Beroep,
+    DateOnly Registratiedatum,
+    DateOnly Geboortedatum,
+    RegistrationStatus Status);

backend/src/BigRegister.Api/Domain/Submissions/SubmissionRules.cs

@@ -0,0 +1,23 @@
+namespace BigRegister.Domain.Submissions;
+
+/// <summary>
+/// SERVER-OWNED submit rules (ported from the frontend submit-*.ts commands, where
+/// they were hardcoded). Each method returns a rejection reason, or null when the
+/// submission is accepted. The reference is generated server-side on acceptance.
+/// </summary>
+public static class SubmissionRules
+{
+    // RULE: a manually entered diploma cannot be auto-verified.
+    public static string? RejectRegistratie(string diplomaHerkomst) =>
+        diplomaHerkomst == "handmatig"
+            ? "Een handmatig ingevoerd diploma kan niet automatisch worden geverifieerd. Uw aanvraag is doorgestuurd voor handmatige beoordeling."
+            : null;
+
+    // RULE: an application reporting zero worked hours is rejected.
+    public static string? RejectZeroUren(int uren) =>
+        uren == 0 ? "Aanvraag afgewezen: geen gewerkte uren geregistreerd." : null;
+
+    public static string NewReference() =>
+        // ponytail: random reference is fine for a demo; a real system reserves it transactionally.
+        "BIG-2026-" + Random.Shared.Next(100_000, 1_000_000);
+}

backend/src/BigRegister.Api/Program.cs

@@ -0,0 +1,94 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using BigRegister.Api.Contracts;
+using BigRegister.Api.Data;
+using BigRegister.Domain.Diplomas;
+using BigRegister.Domain.Intake;
+using BigRegister.Domain.Registrations;
+using BigRegister.Domain.Submissions;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddEndpointsApiExplorer();
+builder.Services.AddSwaggerGen(c =>
+    c.SwaggerDoc("v1", new() { Title = "BIG-register BFF", Version = "v1" }));
+builder.Services.AddProblemDetails();
+builder.Services.ConfigureHttpJsonOptions(o =>
+{
+    o.SerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
+    o.SerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
+});
+
+const string SpaCors = "spa";
+builder.Services.AddCors(o => o.AddPolicy(SpaCors, p =>
+    p.WithOrigins("http://localhost:4200").AllowAnyHeader().AllowAnyMethod()));
+
+var app = builder.Build();
+
+app.UseSwagger();
+app.UseSwaggerUI();
+app.UseCors(SpaCors);
+
+var api = app.MapGroup("/api");
+
+// --- GET: screen-shaped reads. Decisions are computed here, never on the client. ---
+
+api.MapGet("/dashboard-view", () =>
+{
+    var reg = SeedData.Registration;
+    var (eligible, reason) = HerregistratieRule.Evaluate(reg, DateOnly.FromDateTime(DateTime.Today));
+    return new DashboardViewDto(reg.ToDto(), SeedData.Person.ToDto(),
+        new HerregistratieDecisionsDto(eligible, reason));
+});
+
+api.MapGet("/notes", () =>
+    SeedData.Notes.Select(n => new AantekeningDto(n.Type, n.Omschrijving, n.Datum)).ToList());
+
+// BRP "no address" fallback would be `new BrpAddressDto(false, null)` — the seeded
+// citizen has one.
+api.MapGet("/brp/address", () => new BrpAddressDto(true, SeedData.BrpAddress.ToDto()));
+
+api.MapGet("/duo/diplomas", () => new DuoLookupDto(
+    SeedData.Diplomas.Select(d => d.ToDto()).ToList(),
+    new ManualDiplomaPolicyDto(
+        DiplomaRules.ManualProfessions(),
+        DiplomaRules.ManualQuestions().Select(q => q.ToDto()).ToList())));
+
+api.MapGet("/intake/policy", () => new IntakePolicyDto(IntakePolicy.ScholingThreshold));
+
+// --- POST: submits. The server is the authority; it re-validates and decides. ---
+
+api.MapPost("/registrations", (RegistratieRequest req) =>
+{
+    var reject = SubmissionRules.RejectRegistratie(req.DiplomaHerkomst);
+    return reject is null
+        ? Results.Ok(new ReferentieResponse(SubmissionRules.NewReference()))
+        : Results.Problem(detail: reject, statusCode: StatusCodes.Status422UnprocessableEntity);
+})
+.Produces<ReferentieResponse>()
+.ProducesProblem(StatusCodes.Status422UnprocessableEntity);
+
+api.MapPost("/herregistraties", (HerregistratieRequest req) =>
+{
+    var reject = SubmissionRules.RejectZeroUren(req.Uren);
+    return reject is null
+        ? Results.Ok(new ReferentieResponse(SubmissionRules.NewReference()))
+        : Results.Problem(detail: reject, statusCode: StatusCodes.Status422UnprocessableEntity);
+})
+.Produces<ReferentieResponse>()
+.ProducesProblem(StatusCodes.Status422UnprocessableEntity);
+
+api.MapPost("/intakes", (IntakeRequest req) =>
+{
+    var reject = SubmissionRules.RejectZeroUren(req.Uren);
+    return reject is null
+        ? Results.Ok(new ReferentieResponse(SubmissionRules.NewReference()))
+        : Results.Problem(detail: reject, statusCode: StatusCodes.Status422UnprocessableEntity);
+})
+.Produces<ReferentieResponse>()
+.ProducesProblem(StatusCodes.Status422UnprocessableEntity);
+
+app.Run();
+
+// Exposed so the integration tests can spin up the app with WebApplicationFactory.
+public partial class Program { }

backend/src/BigRegister.Api/Properties/launchSettings.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json.schemastore.org/launchsettings.json",
+  "profiles": {
+    "http": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "launchUrl": "swagger",
+      "applicationUrl": "http://localhost:5000",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    }
+  }
+}

backend/src/BigRegister.Api/appsettings.Development.json

@@ -0,0 +1,8 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  }
+}

backend/src/BigRegister.Api/appsettings.json

@@ -0,0 +1,9 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  },
+  "AllowedHosts": "*"
+}