atomic-design-poc/docs/ARCHITECTURE.md

Architecture guide

A walkthrough of how this app is organised and, especially, how state is managed — written for a developer who has not done functional programming before. No prior FP knowledge assumed. Where we use an FP idea, we explain it in plain language first.

This is a demo of a Dutch BIG-register self-service portal (a healthcare professional logs in, sees their registration, and can apply for re-registration — "herregistratie").

---

1. The big picture: three "contexts", four "layers"

The code is split first by business area (a "bounded context" in DDD terms), then inside each area by layer.

src/app/
  shared/            things every context reuses (no business logic of its own)
  auth/              logging in / the current session
  registratie/       the user's BIG registration + personal data
  herregistratie/    the re-registration application flow
  showcase/          a teaching page; not a real feature

Inside a context you'll see the same four folders. They answer four different questions:

Layer	Answers…	May import Angular?	Example here
domain/	What are the business rules and data?	No (pure TS)	registration.ts, registration.policy.ts
application/	How do we coordinate a task / state?	Yes (signals)	big-profile.store.ts
infrastructure/	Where does data come from?	Yes (HTTP)	big-register.adapter.ts, brp.adapter.ts
ui/	How does it look?	Yes (components)	dashboard.page.ts

The one rule that keeps it sane: dependencies only point inward. UI may use application, application may use domain, everyone may use shared. Never the other way around. The domain/ layer imports nothing from Angular, so the business rules are plain functions you can read and test in isolation.

Allowed direction: herregistratie → registratie → shared, auth → shared.

Why the shared/ kernel is split too

• shared/kernel/ — tiny generic helpers (no Angular).
• shared/application/ — generic state tools (RemoteData, the store).
• shared/ui/ — the atomic-design building blocks (buttons, inputs, the async renderer). These know nothing about BIG-register.
• shared/layout/ — page chrome (header, footer, shells).
• shared/infrastructure/ — the demo HTTP interceptor.

Imports use path aliases so they read as direction statements: @shared/*, @auth/*, @registratie/*, @herregistratie/*.

---

2. The state-management ideas (the important part)

Most UI bugs come from state that can lie — two booleans that disagree, data that's shown while an error is also showing, a "submit" that fires while a field is invalid. The whole strategy here is: make those impossible by choosing better types. Three tools do the work.

2a. RemoteData — one value instead of three booleans

The naive way to track a network call:

isLoading = signal(true);
error = signal<string | null>(null);
data = signal<Thing | null>(null);

Three signals = eight combinations, and most are nonsense (loading and has data and has an error?). You end up writing defensive ifs everywhere.

Instead we use one value that is exactly one of four shapes (shared/application/remote-data.ts):

type RemoteData<E, T> =
  | { tag: 'Loading' }
  | { tag: 'Empty' }
  | { tag: 'Failure'; error: E }   // only this shape has an error
  | { tag: 'Success'; value: T };  // only this shape has a value

This is called a discriminated union (a.k.a. "tagged union" or "sum type"): a value that is one of several labelled shapes, where the tag tells you which. Notice the data lives on the shape — you literally cannot read .value unless you're in the Success case, so "loaded but no data" can't be written down.

To use it, you handle every case once. The <app-async> component (shared/ui/async/async.component.ts) does this for you: you give it a RemoteData (or a raw httpResource) and four templates, and it shows exactly one. There's also foldRemote(rd, { loading, empty, failure, success }) for doing the same in TypeScript — the compiler makes you cover all four.

FP term: a pure function is one whose output depends only on its inputs and which changes nothing else (no network, no writing to variables outside it). Pure functions are easy to test and reason about. We push impure things (HTTP, timers) to the edges.

2b. Combining sources with map2 — two services, one state

The dashboard needs data from two services: the BIG-register (status, specialisms) and the BRP (name, address). Each is its own RemoteData. Tracking both by hand means juggling two loading flags, two errors…

map2 folds them into one RemoteData (big-profile.store.ts):

profile = computed(() =>
  map2(
    fromResource(this.registrationRes),  // RemoteData from service A
    fromResource(this.personRes),        // RemoteData from service B
    (registration, person) => ({ registration, person }),  // runs only if BOTH succeeded
  ),
);

The rule baked into map2: the combined result is a Failure if either failed, Loading if either is still loading, and only Success when both succeeded. So the page renders one state and the combiner callback only runs when it's safe. (map, map3, andThen are variations on the same idea.)

2c. The store — "all state changes go through one pure function"

This is the "Elm-style" pattern. The idea in one sentence:

Keep all state in one value (the Model). The only way to change it is to send a message (Msg) to a pure function update(model, msg) that returns the next Model.

Why bother? Because to understand every way the screen can change, you read one function. No state is mutated anywhere else.

The wizard (herregistratie/domain/herregistratie.machine.ts) is the clearest example. Its Model is a discriminated union:

type WizardState =
  | { tag: 'Editing'; step: 1 | 2; draft: Draft; errors: {...} }
  | { tag: 'Submitting'; data: Valid }   // carries ONLY validated data
  | { tag: 'Submitted';  data: Valid }
  | { tag: 'Failed';     data: Valid; error: string };

Because step and errors exist only on Editing, and the other states carry already-validated data, "submitting with validation errors showing" is not expressible. The messages and the pure reducer:

type WizardMsg =
  | { tag: 'SetField'; key; value } | { tag: 'Next' } | { tag: 'Back' }
  | { tag: 'Submit' } | { tag: 'Retry' }
  | { tag: 'SubmitConfirmed' } | { tag: 'SubmitFailed'; error };

function reduce(state, msg) { /* returns the next state; no side effects */ }

The component (herregistratie-wizard.component.ts) wires it to a signal with the tiny helper in shared/application/store.ts:

private store = createStore(initial, reduce);
state = this.store.model;        // a read-only signal of the current Model
dispatch = this.store.dispatch;  // send a Msg

In the template you don't mutate anything — you send messages: (click)="dispatch({ tag: 'Back' })".

2d. Side effects (HTTP) without polluting the reducer

reduce is pure — it must not call the network. So how does a submit happen? The component has a small command method that does the impure work and then sends messages describing the outcome:

async runIfSubmitting() {
  if (this.state().tag !== 'Submitting') return;
  this.profile.beginHerregistratie();              // 1. optimistic (see below)
  const r = await submitHerregistratie(s.data);    // 2. the actual call
  if (r.ok) { this.dispatch({ tag: 'SubmitConfirmed' }); this.profile.confirmHerregistratie(); }
  else      { this.dispatch({ tag: 'SubmitFailed', error: r.error }); this.profile.rollbackHerregistratie(); }
}

So the split is: reducer = "what the new state is", command = "go do the thing, then tell the reducer what happened."

2e. Optimistic update + rollback, and shared state across pages

BigProfileStore is marked providedIn: 'root', which means Angular creates one instance for the whole app. Every page that injects it sees the same signals. That single shared instance is our cross-page state — no extra library needed.

When the user submits a herregistratie:

1. Optimistic: beginHerregistratie() flips a pendingHerregistratie signal before the server answers. The dashboard already reads that signal, so it instantly shows "in behandeling" (in progress). The UI feels fast.
2. On success: confirmHerregistratie() clears the flag and calls resource.reload() — that re-fetches the registration so the screen shows the real, updated server data. ("Invalidation": throw away the stale copy, fetch fresh.)
3. On failure: rollbackHerregistratie() clears the flag, undoing the optimistic guess so the UI matches reality again.

2f. Auth/session + the route guard

SessionStore (auth/application/session.store.ts) holds Session | null, also a root singleton. login() is a command that calls the (mock) DigiD adapter and stores the result. The route guard (auth/auth.guard.ts) just reads store.isAuthenticated() and redirects to /login if you're not signed in. Protected routes list canActivate: [authGuard] in app.routes.ts.

---

3. "Parse, don't validate" — value objects

A raw string could be anything. After you've checked a postcode is valid, the type should remember that. So we have a Postcode type that can only be created by parsePostcode, which returns a Result (success-or-error) (registratie/domain/value-objects/):

const r = parsePostcode(userInput);
if (r.ok) save(r.value);     // r.value is a Postcode — guaranteed well-formed
else showError(r.error);     // r.error is the message

Once something hands you a Postcode, you never re-check it. The validity is baked into the type. Same idea for Uren and BigNummer.

FP term: Result<E, T> is "either an error E or a value T" — a discriminated union with { ok: true, value } or { ok: false, error }. It's how a function reports failure without throwing.

---

4. How to add a new feature (recipe)

1. Domain first. Add the types and pure rules in the right context's domain/. No Angular. Write a .spec.ts next to it.
2. Infrastructure. If you need data, add an adapter in infrastructure/ returning an httpResource (or a command function returning a Result).
3. Application. If there's state to coordinate, add/extend a store (providedIn: 'root' if it must be shared across pages). Model state as a discriminated union; change it only through a pure update/reduce.
4. UI last. Build the page/organism from shared/ui atoms. Render async state through <app-async>. Send messages; don't mutate.

If you're tempted to add a third boolean to track state — stop and model it as a discriminated union instead.

---

5. Mini-glossary

• Pure function — output depends only on inputs; no side effects. Easy to test.
• Discriminated / tagged union (sum type) — a value that is exactly one of several labelled shapes ({ tag: 'A'; ... } | { tag: 'B'; ... }). The tag says which; each shape carries only the data that makes sense for it.
• RemoteData — a tagged union for an async value: Loading / Empty / Failure / Success.
• Result<E,T> — a tagged union for success-or-error.
• Value object — a small type whose validity is guaranteed by its constructor (e.g. Postcode).
• Reducer (update/reduce) — the one pure function that maps (state, message) → next state.
• Command — an impure function that does I/O (HTTP, timer) and then dispatches messages with the outcome.
• Optimistic update — show the expected result immediately, then confirm or roll back when the server answers.
• Bounded context — a self-contained business area with its own language and folder (auth, registratie, herregistratie).
• signal / computed — Angular's reactive values; computed recalculates automatically when the signals it reads change.