ehoandClaude Opus 5
d31e054504
Section 6a cited line numbers and two paths from before the monorepo split (WP-67). A line number goes stale on the next edit; a symbol survives it. Replace every L<n> citation in the section with the named symbol, fix the two dead paths (environment.ts now lives under libs/shared, proxy.conf.json is now one file per app), and point the read walkthrough at mijn-registratie.section.ts, where the RD-03 split moved the dashboard's <app-async> block. Mark RD-31 done and update its README row. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
94 lines
5.2 KiB
Markdown
94 lines
5.2 KiB
Markdown
# RD-31 — `ARCHITECTURE.md` §6a cites lines that moved
|
|
|
|
Status: done
|
|
Phase: 5 — fix the docs that describe this flow
|
|
|
|
## Why
|
|
|
|
Section 6a, "The request lifecycle today"
|
|
(`docs/reference/architecture/ARCHITECTURE.md:564`), is the best onboarding artifact in the
|
|
repo. It walks one read and one write from the template to the backend and back. It has rotted.
|
|
|
|
A line citation is only true until the next commit. Two of the cited paths belong to the tree
|
|
from before the monorepo (WP-67). A reader who follows them meets a comment about ZGW client
|
|
timeouts and two files that do not exist. That is worse than no citation, because the reader
|
|
does not know which half to trust.
|
|
|
|
## Read first
|
|
|
|
- `docs/project/readable-codebase/PLAN.md`, phase 5 item 2 (line 822).
|
|
- `docs/reference/architecture/ARCHITECTURE.md:564-608` — the whole section.
|
|
|
|
## Decisions (pre-made, do not relitigate)
|
|
|
|
1. **Cite symbols, not lines.** Write "`Program.cs`, `api.MapGet("/dashboard-view")`", never
|
|
"`Program.cs` L80". A symbol survives an edit above it; a line number does not. Apply this
|
|
to all 15 citations in the section, including the ones that happen to be correct today.
|
|
2. **Keep the Markdown links to the files.** The link tells the reader where to look; the
|
|
symbol tells them what to look for. Both, not one.
|
|
3. **Keep the `RemoteData<DashboardView>` statement.** `PLAN.md` withdrew the claim that it is
|
|
wrong. `DashboardView` is a pair of `BigProfile` and `HerregistratieDecisions`, not a second
|
|
name for either. Do not collapse it.
|
|
4. **Do not rewrite the section.** It is accurate in structure and good prose. This ticket
|
|
corrects addresses, not the argument.
|
|
|
|
## The facts, measured against the current tree
|
|
|
|
| The section says | The tree says |
|
|
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `src/environments/environment.ts` | `libs/shared/src/environments/environment.ts` (plus `environment.prod.ts`) |
|
|
| `proxy.conf.json` | `apps/ssp/proxy.conf.json`, and `apps/behandelportal/proxy.conf.json` |
|
|
| `Program.cs` `/dashboard-view` L80 | L80 is `builder.Services.AddSingleton(zgw)`. The endpoint is `api.MapGet("/dashboard-view")`, L172 today |
|
|
| `Program.cs` `/change-requests` L120 | L120 is the correlation-id middleware. The endpoint is `api.MapPost("/change-requests")`, L238 today |
|
|
| `app.config.ts` L37 | L37 is inside a view-transition comment. `provideApiClient()` is L63 today |
|
|
| `api-client.provider.ts` L47-82, L86-92 | Correct today (`httpClientFetch` L47, `provideApiClient` L86). Cite the symbols anyway |
|
|
| the read starts at the dashboard page | `<app-async [data]="store.profile()">` now lives in `mijn-registratie.section.ts:25`, after the RD-03 split. `wat-moet-ik-regelen.section.ts:24` reads the same store |
|
|
|
|
The proxy bullet also needs one addition: each app now carries its own `proxy.conf.json`, and
|
|
both point at `http://localhost:5000`.
|
|
|
|
## Files
|
|
|
|
- `docs/reference/architecture/ARCHITECTURE.md` — section 6a only.
|
|
|
|
Check the rest of the document for the same two dead paths before you stop:
|
|
|
|
```bash
|
|
grep -rn "src/environments\|proxy.conf.json\|L[0-9][0-9]" docs/reference/architecture/
|
|
```
|
|
|
|
## Steps
|
|
|
|
1. Fix the two dead paths.
|
|
2. Replace every `L<n>` citation in §6a with a symbol.
|
|
3. Correct the read walkthrough's entry point to the section component.
|
|
4. Run the grep above. Fix any hit outside §6a that is wrong for the same reason.
|
|
5. `npm run ci`.
|
|
|
|
## Acceptance criteria
|
|
|
|
- [x] No `L<n>` citation remains in §6a.
|
|
- [x] Every path in §6a resolves. Verify by following each link.
|
|
- [x] The read walkthrough names `mijn-registratie.section.ts`.
|
|
- [x] The `RemoteData<DashboardView>` statement is unchanged.
|
|
- [x] `npm run ci` is green.
|
|
|
|
## Verification
|
|
|
|
1. `npm run ci` — the format check covers the file.
|
|
2. For each Markdown link in §6a, run `ls <path>`. Every one must exist.
|
|
3. For each symbol cited, `grep -n "<symbol>" <file>`. Every one must return a hit.
|
|
|
|
## Out of scope
|
|
|
|
- Sections 1 to 6 and section 7. RD-32 and RD-33 own the other documents.
|
|
- The `backend/README.md` and the ADRs.
|
|
|
|
## Risks
|
|
|
|
1. **A symbol that is not unique.** `runSubmit` and `toDomain` appear in more than one file.
|
|
Cite the file with the symbol, never the symbol alone.
|
|
2. **Line citations elsewhere in the document.** The grep in Files finds them. Fix only the
|
|
ones that are wrong; a correct citation outside §6a is not this ticket's work, but a wrong
|
|
one that you leave behind makes the ticket a half measure.
|