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

- [x] No path in the file starts with a bare `src/app/`.
- [x] Every cited path resolves. Verify each with `ls`.
- [x] The §1 anchor matches the current heading.
- [x] `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.