Skip to content

Commit d45ab7b

Browse files
Astro-HanAstro-Han
committed
chore: add frontend architecture inventory
1 parent eb80bed commit d45ab7b

3 files changed

Lines changed: 633 additions & 0 deletions

File tree

‎.github/frontend-architecture-manifest.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
# Frontend Architecture Manifest
2+
3+
Canonical home for PawWork frontend architecture debt governance.
4+
5+
This manifest covers git-tracked, hand-written frontend files under `packages/app/src` and `packages/ui/src`. It replaces chat memory as the handoff surface for this work. GitHub issue bodies and PR bodies should summarize and link here instead of carrying a second backlog.
6+
7+
## Current State
8+
9+
- Manifest status: governance baseline.
10+
- Baseline commit: `eb80bed96` (`feat(ui): #642 PR1 typography role utilities`).
11+
- Default branch: `dev`.
12+
- Master owner: [#599 UI rewrite v2](https://github.com/Astro-Han/pawwork/issues/599).
13+
- Historical issue [#440](https://github.com/Astro-Han/pawwork/issues/440) is closed and must not be used as a new work entry.
14+
- Perf gate [#600](https://github.com/Astro-Han/pawwork/issues/600) is closed/completed and is required for implementation PRs.
15+
16+
## Inventory Command
17+
18+
The repeatable report command is:
19+
20+
```sh
21+
bun run frontend:inventory
22+
node script/frontend-inventory.mjs --format json
23+
bun run frontend:inventory -- --format markdown --max-rows 120
24+
```
25+
26+
The script is warn-only in this governance phase. It prints threshold warnings but exits successfully.
27+
28+
## Report Schema
29+
30+
The JSON report uses schema version `1`.
31+
32+
| Field | Meaning |
33+
| --- | --- |
34+
| `summary.schemaVersion` | Report schema version. |
35+
| `summary.command` | Reproduction command for the JSON report. |
36+
| `summary.locMetric` | Current line-count metric. |
37+
| `summary.paths` | Git pathspecs included in the inventory. |
38+
| `summary.totalTrackedTsTsx` | Total tracked `.ts` / `.tsx` frontend files. |
39+
| `summary.production` | Files in the production ratchet set. |
40+
| `summary.visibilityOnly` | Files visible to agents but excluded from default ratchet. |
41+
| `summary.approvedExceptions` | Files with an approved exception entry. |
42+
| `summary.productionOver500` | Production files above the hard warning line. |
43+
| `summary.productionOver200` | Production files above the owner-manifest line. |
44+
| `summary.visibilityOver500` | Visibility-only files above 500 LOC. |
45+
| `summary.visibilityOver200` | Visibility-only files above 200 LOC. |
46+
| `byOwnerLane` | Production counts grouped by owner lane. |
47+
| `records[].path` | Repo-relative file path. |
48+
| `records[].loc` | Physical LOC, including blank lines and comments. |
49+
| `records[].setType` | `production ratchet set` or `visibility-only inventory`. |
50+
| `records[].classifications` | `production`, `test`, `story`, `i18n`, `generated-static`, `pure-config`, `facade`, or `delivered-surface`. |
51+
| `records[].ownerLane` | Owner lane used for planning. |
52+
| `records[].ownerIssue` | Live issue URL when available. |
53+
| `records[].approvedException` | Exception entry, or `null`. |
54+
| `records[].status` | Current governance state for the file. |
55+
| `records[].reason` | Why the status was assigned. |
56+
| `records[].classificationReason` | Why the file entered its set. |
57+
| `records[].ownerReason` | Why the owner lane was selected. |
58+
59+
If this work changes from physical LOC to logical LOC or another metric, add schema version `2` and do not mix v1 and v2 baseline numbers.
60+
61+
## Baseline Summary
62+
63+
Generated with `node script/frontend-inventory.mjs --format json` at baseline commit `eb80bed96`.
64+
65+
| Metric | Count |
66+
| --- | ---: |
67+
| Tracked `.ts` / `.tsx` files | 672 |
68+
| Production ratchet set | 349 |
69+
| Visibility-only inventory | 323 |
70+
| Approved exceptions | 0 |
71+
| Production files `>500` LOC | 26 |
72+
| Production files `>200` LOC | 79 |
73+
| Visibility-only files `>500` LOC | 15 |
74+
| Visibility-only files `>200` LOC | 56 |
75+
76+
Production by owner lane:
77+
78+
| Owner lane | Files | `>200` | `>500` |
79+
| --- | ---: | ---: | ---: |
80+
| other/deferred | 128 | 24 | 5 |
81+
| #638 interface audit | 6 | 1 | 0 |
82+
| #604 settings | 21 | 9 | 3 |
83+
| #599 mainline | 2 | 0 | 0 |
84+
| #606 final shell | 44 | 13 | 6 |
85+
| #601 message flow | 55 | 9 | 5 |
86+
| #605 visual shell | 82 | 18 | 6 |
87+
| #595/#615 scroll-perf | 11 | 5 | 1 |
88+
89+
## Owner Lanes
90+
91+
| Lane | Scope | Current state |
92+
| --- | --- | --- |
93+
| [#599 mainline](https://github.com/Astro-Han/pawwork/issues/599) | UI rewrite v2 launch path and integration owner | Open. Primary sequencing source. |
94+
| [#601 message flow](https://github.com/Astro-Han/pawwork/issues/601) | Message timeline, turn shell, message shell, markdown, tool rows | Open. First launch-path implementation lane after governance. |
95+
| [#604 settings](https://github.com/Astro-Han/pawwork/issues/604) | Settings page and settings dialogs | Open. Can be independent, but avoid current #642 typography sweep overlap. |
96+
| [#605 visual shell](https://github.com/Astro-Han/pawwork/issues/605) | Shared visual shell, theme, typography, tokens, motion | Open. Starts after at least two Areas A-D first behavioral PRs. |
97+
| [#606 final shell](https://github.com/Astro-Han/pawwork/issues/606) | Layout, global shell, final assembly | Open. Last lane by issue contract. |
98+
| [#595/#615 scroll-perf](https://github.com/Astro-Han/pawwork/issues/595) | Scroll owner, perf owner, long-session responsiveness | Open. Keep independent from visual-only splits. |
99+
| [#638 interface audit](https://github.com/Astro-Han/pawwork/issues/638) | Cross-package public contracts and type/interface consistency | Open. Contract PRs only, not mixed with UI surface splits. |
100+
| `other/deferred` | No active owner lane matched, or only a closed area matched | Requires a live issue before implementation. |
101+
102+
Closed area references are allowed as background only. [#602](https://github.com/Astro-Han/pawwork/issues/602) and [#603](https://github.com/Astro-Han/pawwork/issues/603) are closed/completed; do not reopen them by implication.
103+
104+
## Ratchet Stages
105+
106+
| Stage | Rule |
107+
| --- | --- |
108+
| 1. Governance | Warn only. Establish baseline, schema, owner map, report command, and exception format. |
109+
| 2. New `>500` guard | Do not add or modify an unexplained production file above 500 LOC. |
110+
| 3. New `>200` guard | Do not add or modify a production file above 200 LOC without owner lane and manifest entry. |
111+
| 4. Tighter ratchet | Only after the launch path is stable and current exceptions are reviewed. |
112+
113+
## Exception Schema
114+
115+
An approved exception must include all fields below. An exception without a live issue and review trigger is not accepted.
116+
117+
| Field | Required |
118+
| --- | --- |
119+
| File path | Yes |
120+
| Owner lane / issue | Yes |
121+
| Why it is not split now | Yes |
122+
| Risk level | Yes |
123+
| Conditions that allow it to remain | Yes |
124+
| Conditions that trigger review | Yes |
125+
| Next PR boundary | Yes |
126+
127+
Current approved exceptions: none.
128+
129+
## Production Burn-down
130+
131+
`>500` production files at baseline:
132+
133+
| LOC | Owner Lane | Status | Path |
134+
| ---: | --- | --- | --- |
135+
| 2463 | #606 final shell | needs-over-500-resolution | `packages/app/src/pages/layout.tsx` |
136+
| 1217 | #601 message flow | needs-over-500-resolution | `packages/app/src/pages/session/message-timeline.tsx` |
137+
| 1129 | #605 visual shell | needs-over-500-resolution | `packages/ui/src/components/file.tsx` |
138+
| 1119 | #606 final shell | needs-over-500-resolution | `packages/app/src/context/layout.tsx` |
139+
| 753 | #601 message flow | needs-over-500-resolution | `packages/ui/src/components/session-turn.tsx` |
140+
| 733 | #604 settings | needs-over-500-resolution | `packages/app/src/components/settings-general.tsx` |
141+
| 691 | #601 message flow | needs-over-500-resolution | `packages/app/src/pages/session.tsx` |
142+
| 673 | other/deferred | needs-over-500-resolution | `packages/app/src/components/terminal.tsx` |
143+
| 665 | #606 final shell | needs-over-500-resolution | `packages/app/src/context/sync.tsx` |
144+
| 661 | #605 visual shell | needs-over-500-resolution | `packages/ui/src/components/session-review.tsx` |
145+
| 654 | #604 settings | needs-over-500-resolution | `packages/app/src/components/dialog-connect-provider.tsx` |
146+
| 649 | #604 settings | needs-over-500-resolution | `packages/app/src/components/dialog-select-server.tsx` |
147+
| 634 | other/deferred | needs-over-500-resolution | `packages/app/src/addons/serialize.ts` |
148+
| 618 | #601 message flow | needs-over-500-resolution | `packages/app/src/pages/session/use-session-commands.tsx` |
149+
| 598 | #601 message flow | needs-over-500-resolution | `packages/ui/src/components/markdown.tsx` |
150+
| 596 | #605 visual shell | needs-over-500-resolution | `packages/ui/src/components/line-comment-annotations.tsx` |
151+
| 595 | #595/#615 scroll-perf | needs-over-500-resolution | `packages/app/src/pages/session/session-timeline-scroll-controller.ts` |
152+
| 588 | #605 visual shell | needs-over-500-resolution | `packages/ui/src/components/file-icon.tsx` |
153+
| 568 | other/deferred | needs-over-500-resolution | `packages/app/src/utils/persist.ts` |
154+
| 560 | #606 final shell | needs-over-500-resolution | `packages/app/src/context/local.tsx` |
155+
| 553 | other/deferred | needs-over-500-resolution | `packages/app/src/pages/session/session-side-panel.tsx` |
156+
| 543 | #606 final shell | needs-over-500-resolution | `packages/app/src/context/global-sync.tsx` |
157+
| 540 | #605 visual shell | needs-over-500-resolution | `packages/ui/src/theme/resolve.ts` |
158+
| 527 | #605 visual shell | needs-over-500-resolution | `packages/ui/src/context/marked.tsx` |
159+
| 511 | #606 final shell | needs-over-500-resolution | `packages/app/src/context/terminal.tsx` |
160+
| 507 | other/deferred | needs-over-500-resolution | `packages/app/src/components/file-tree.tsx` |
161+
162+
`>200` files are tracked by the report command. Use:
163+
164+
```sh
165+
bun run frontend:inventory -- --format markdown --max-rows 120
166+
```
167+
168+
## PR Manifest
169+
170+
| PR | Owner lane | Base | Depends on | Boundary | Architecture effect | Verification | Status | Public write status |
171+
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
172+
| Governance PR | #599 mainline / governance | `dev` | None | Manifest, schema, owner map, warn-only script, baseline report command | boundary created, owner map established, ratchet command added | `bun run frontend:inventory`, `node script/frontend-inventory.mjs --format json`, `bun run frontend:inventory -- --format markdown --max-rows 120` | in progress | PR body only |
173+
| Contract PR | #638 interface audit | Governance branch or post-merge `dev` | Governance PR | Public contract/import boundary and compatibility checks | public contract stabilized, private import risk surfaced | typecheck plus contract-specific compatibility check | planned | PR body only |
174+
| Message-flow PR stack | #601 message flow | post-governance `dev` unless stacked | Governance PR, maybe Contract PR if public imports move | Current launch-path message flow files only | owner extracted, LOC reduced, verification added | typecheck, unit/e2e, #600 perf gate, visual smoke | planned | PR body only |
175+
| Scroll/perf PR stack | #595/#615 scroll-perf | `dev` or message-flow stack if shared files force it | Governance PR | Scroll owner and perf guard work only | owner extracted, perf verification added | typecheck, targeted unit/e2e, #600 perf gate | planned | PR body only |
176+
| Settings PR stack | #604 settings | `dev` after checking #642 overlap | Governance PR | Settings page/dialog family only | owner extracted, LOC reduced | typecheck, settings tests/e2e/manual UI check | planned | PR body only |
177+
178+
## Handoff Rules
179+
180+
- Do not call this work complete until the full completion checklist in #599 and this manifest is satisfied.
181+
- Without merge authorization, stop at ready PRs plus handoff.
182+
- After any stack merge, update this manifest before starting the next dependent stack.
183+
- Keep `STATUS.md` as a local pointer only in this checkout; it is excluded from git here and is not the canonical manifest.

‎package.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@
1010
"dev:desktop": "bun --cwd packages/desktop-electron dev",
1111
"dev:web": "bun --cwd packages/app dev",
1212
"dev:opencode": "bun run --cwd packages/opencode --conditions=browser src/index.ts",
13+
"frontend:inventory": "node script/frontend-inventory.mjs",
14+
"frontend:inventory:json": "node script/frontend-inventory.mjs --format json",
1315
"typecheck": "bun turbo typecheck",
1416
"lint": "eslint \"packages/{app,ui,desktop-electron}/src/**/*.{ts,tsx}\"",
1517
"lint:ci": "bun run lint",

0 commit comments

Comments
 (0)