atomic-design-poc/docs/project/readable-codebase/RD-32-fp-tea-paths.md

RD-32 — fp-tea-atomic-design.md cites the pre-monorepo tree

Status: done Phase: 5 — fix the docs that describe this flow

Why

docs/reference/fp-tea-atomic-design.md is the learning guide. CLAUDE.md names it as one of the three documents that hold the why. It still addresses the tree from before the monorepo (WP-67): every path starts src/app/, which no directory has done since that work landed.

A reader learning the codebase from this guide cannot open a single file it names. The prose is correct; only the addresses are wrong.

Read first

• docs/project/readable-codebase/PLAN.md, phase 5 item 3 (line 833).
• docs/reference/fp-tea-atomic-design.md — the whole file.

Decisions (pre-made, do not relitigate)

1. Two mapping rules cover all 11 paths. A context path becomes apps/ssp/src/app/<context>/…. A shared path becomes libs/shared/src/… — note that app/shared/ collapses to libs/shared/src/, it does not become libs/shared/src/app/.
2. Follow the file's own precedent. Line 338 already reads libs/shared/src/application/store.ts. Line 223 names the same file the old way. Make 223 match 338, not the reverse.
3. Fix the broken anchor at line 435. It reads #1-the-big-picture-three-contexts-four-layers. The heading is now "1. The big picture: two apps, cross-app libraries, "contexts", "layers"", so the anchor is #1-the-big-picture-two-apps-cross-app-libraries-contexts-layers.
4. Correct line 513's "Where" guidance. It says shared/ui/. After RD-27 a shared block lands in libs/shared/src/ui/<atoms|molecules|organisms>/. Name the layer folder; the whole point of RD-27 is that the folder is the layer.
5. Change addresses only. Do not rewrite the teaching. This guide's prose survived the refactor because it teaches ideas, not file layout.

The facts, measured against the current tree

All 11 occurrences of src/app/, and where each file lives now:

Line	Cited	Actual
72	src/app/registratie/domain/value-objects/uren.ts	apps/ssp/src/app/registratie/domain/value-objects/uren.ts
98, 255	src/app/herregistratie/domain/herregistratie.machine.ts	apps/ssp/src/app/herregistratie/domain/herregistratie.machine.ts
223	src/app/shared/application/store.ts	libs/shared/src/application/store.ts
299	src/app/shared/kernel/fp.ts	libs/shared/src/kernel/fp.ts
305	src/app/herregistratie/ui/herregistratie-wizard/…	apps/ssp/src/app/herregistratie/ui/herregistratie-wizard/…
381	src/app/showcase/concepts.page.ts	apps/ssp/src/app/showcase/concepts.page.ts
388	src/app/shared/infrastructure/scenario.ts	libs/shared/src/infrastructure/scenario.ts
414, 523	src/app/registratie/ui/address-fields/…	apps/ssp/src/app/registratie/ui/address-fields/…
588	src/app/herregistratie/domain/intake.machine.ts	apps/ssp/src/app/herregistratie/domain/intake.machine.ts

Every target exists. This is a rename, not a hunt.

One correction to PLAN.md. It says one path points at a deleted file, submit-herregistratie.ts. That reference is no longer in the document — grep -n submit-herregistratie docs/reference/fp-tea-atomic-design.md returns nothing. Do not go looking for it. Record the correction in the ticket; leave PLAN.md itself alone, because it is a design record of what was true when it was written.

Line 523 sits inside a code comment, not prose. Update it anyway; a stale path in an example is read as a real path.

Files

• docs/reference/fp-tea-atomic-design.md.

Steps

1. Rewrite the 11 paths per the table.
2. Fix the anchor at line 435.
3. Fix the "Where" guidance at line 513.
4. grep -n "src/app/" docs/reference/fp-tea-atomic-design.md — every remaining hit must start apps/ssp/src/app/.
5. npm run ci.

Acceptance criteria

• No path in the file starts with a bare src/app/.
• Every cited path resolves. Verify each with ls.
• The §1 anchor matches the current heading.
• npm run ci is green.

Verification

1. npm run ci — the format check covers the file.
2. grep -oE '\[^`]src/[^`].ts`' docs/reference/fp-tea-atomic-design.md | tr -d '`' | sort -u | xargs ls` — every path must resolve, with no error.
3. Open ARCHITECTURE.md and confirm the §1 heading text still produces the anchor you wrote. The slug is the heading in lower case, with punctuation removed and spaces turned into hyphens.

Out of scope

• ARCHITECTURE.md. RD-31 owns it.
• CLAUDE.md and atomic-design.mdx. RD-33 owns them.
• The teaching content, the diagrams, and the code examples.

Risks

1. app/shared/ is not libs/shared/src/app/. The app segment disappears for the library. Getting this wrong produces a path that looks right and resolves to nothing.
2. The anchor is easy to half-fix. GitHub drops the quotation marks around "contexts" and "layers" and the colon, and turns each space into one hyphen. Verify by clicking, not by reasoning.