Skip to content

Commit 906a097

Browse files
ToolboxAidToolboxAid
committed
Document repository layout architecture plan
1 parent b3a2b30 commit 906a097

11 files changed

Lines changed: 702 additions & 719 deletions

‎dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -117,7 +117,7 @@ Rules:
117117

118118
## Current Version/Date
119119

120-
- Project Instructions Version: 2026.06.28.003
120+
- Project Instructions Version: 2026.06.28.004
121121
- Date: 2026-06-28
122122
- Owner: OWNER
123123

@@ -195,6 +195,7 @@ That file owns Start of Day, PLAN_PR, BUILD_PR, APPLY_PR, and invalid command be
195195
- Project branching policy: `dev/build/ProjectInstructions/PROJECT_BRANCHING_POLICY.md`
196196
- Project state: `dev/build/ProjectInstructions/PROJECT_STATE.md`
197197
- Repository folder placement SSoT: `dev/build/ProjectInstructions/repository/canonical_repository_structure.md`
198+
- Proposed repository layout architecture plan: `dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md`
198199
- Codex workflow commands: `dev/build/ProjectInstructions/standards/CODEX_WORKFLOW_COMMANDS.md`
199200
- Codex Start-of-Day bootstrap: `dev/build/ProjectInstructions/bootstrap/codex_start_of_day_bootstrap.md`
200201
- Branch lifecycle: `dev/build/ProjectInstructions/addendums/project_instructions_single_source_eod_lock.md`

‎dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS_VERSION.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Project Instructions Version
22

3-
Current Project Instructions Version: 2026.06.28.003
3+
Current Project Instructions Version: 2026.06.28.004
44

55
Last Updated: 2026-06-28
66

@@ -11,6 +11,7 @@ Last Updated: 2026-06-28
1111
- Added dedicated branching policy document.
1212
- Startup validation now verifies the branching policy document was loaded instead of duplicating policy text.
1313
- Added backlog startup assignment policy requiring `BACKLOG_MASTER.md` and Tool Votes/Admin Owner priority signal review during team startup.
14+
- Added proposed repository layout architecture plan for future `www/`, `api/`, and `dev/` separation.
1415
- Codex must read this version file and the latest repository copy of `PROJECT_INSTRUCTIONS.md` before performing work.
1516
- Codex must discard previously remembered Project Instructions and treat the repository copy as authoritative.
1617
- Codex must validate canonical report and ZIP paths, branching model, and legacy path avoidance before work proceeds.

‎dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,18 @@ Completion percentages are updated at SOD, after every accepted PR, and at EOD.
3232

3333
The backlog is the authoritative source for determining the next logical PRs.
3434

35+
## Owner Assignments
36+
37+
### Repository Architecture Simplification
38+
39+
- Team: Owner
40+
- Product Area: Repository Architecture Simplification
41+
- Status: Planned
42+
- Percent Complete: 0%
43+
- Active PR: PR_26180_OWNER_004-repository-layout-architecture-plan
44+
- Next Milestone: Architecture plan
45+
- Source / Reference: `dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md`
46+
3547
## Game Journey MVP
3648

3749
### Idea

‎dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# Repository Layout Architecture Plan
2+
3+
Status: Proposed
4+
Owner: Owner
5+
Scope: Documentation/governance only
6+
7+
## Purpose
8+
9+
Document the proposed repository architecture simplification before any file moves occur.
10+
11+
This plan does not authorize moving files, changing runtime behavior, changing package commands, or mixing feature work into layout migration PRs.
12+
13+
## Proposed Future Layout
14+
15+
```text
16+
www/
17+
api/
18+
dev/
19+
```
20+
21+
### www/
22+
23+
`www/` is the browser-served application.
24+
25+
It will own deployable browser pages, browser assets, and static application entry points currently spread across root product folders, `assets/`, `docs/`, `games/`, `toolbox/`, and browser-facing runtime surfaces.
26+
27+
`www/` must not own authoritative product data.
28+
29+
### api/
30+
31+
`api/` is the Node/API/server application.
32+
33+
It will own server entry points, API routing, API services, environment adapters, database access, storage access, server-side setup, and deployable API/runtime support code.
34+
35+
`api/` owns the Browser -> API -> Postgres/R2 boundary.
36+
37+
### dev/
38+
39+
`dev/` is the developer-only workspace.
40+
41+
It owns Project Instructions, governance, architecture docs, reports, tests, scripts, templates, local developer bootstrap, generated output, zips, logs, and historical archive material.
42+
43+
Production runtime, browser application code, and API deployment code must never depend on `dev/`.
44+
45+
## Deployment Model
46+
47+
The proposed target deployment model has two deployable application surfaces:
48+
49+
- `www/` deploys the browser-served application.
50+
- `api/` deploys the Node/API/server application.
51+
52+
`dev/` is not deployed as product runtime and must be excluded from runtime dependency paths.
53+
54+
Environment differences remain governed by `.env` values and environment-managed secrets. The same deployable browser and API code paths must be promoted through Local, DEV, IST, UAT, and PROD.
55+
56+
## Browser/API/Database Flow
57+
58+
Required product-data flow:
59+
60+
```text
61+
Browser -> API -> Postgres/R2
62+
```
63+
64+
Rules:
65+
66+
- Browser code reads and writes authoritative product data only through the API/service contract.
67+
- Product metadata is persisted in Postgres.
68+
- Product assets are persisted in Cloudflare R2.
69+
- Browser storage, page arrays, source JSON files, `/tmp`, and dev workspace files are not authoritative product-data sources.
70+
- Seed data is allowed only when it seeds the database through server/API/setup ownership.
71+
72+
## Developer Local-Runtime Flow
73+
74+
Local development may use the team-aware developer bootstrap and local runtime support, but the runtime boundary remains the same:
75+
76+
```text
77+
Developer command -> dev bootstrap -> local www server + local api server -> Postgres/R2 or approved local provider
78+
```
79+
80+
Current local bootstrap commands remain unchanged by this plan. This PR does not modify `package.json` commands.
81+
82+
The local developer workflow must continue to prove the same browser/API/database contract that deployed environments use.
83+
84+
## Migration Strategy
85+
86+
Migration must happen through small, reviewable, stacked PRs after this architecture plan is accepted.
87+
88+
Rules:
89+
90+
- No file moves occur in this plan PR.
91+
- No feature work may be mixed into migration PRs.
92+
- Each migration PR moves or rewires one bounded ownership area.
93+
- Each migration PR must preserve the same product behavior unless the PR is explicitly a behavior change.
94+
- Each migration PR must update references, validation, reports, and ZIP artifacts for only its scoped move.
95+
- Each migration PR must include rollback notes or clear validation evidence.
96+
97+
## Proposed Stacked PR Sequence
98+
99+
1. `www/` shell and governance
100+
- Create the destination shell and document browser-served ownership.
101+
- Do not move product pages yet.
102+
103+
2. `api/` shell and governance
104+
- Create the destination shell and document API/server ownership.
105+
- Do not move API/runtime implementation yet.
106+
107+
3. Browser-served public section moves
108+
- Move root browser-served product sections into `www/` in small groups.
109+
- Preserve routes through compatibility redirects or server/static configuration as needed.
110+
111+
4. Browser asset moves
112+
- Move browser assets into `www/` ownership.
113+
- Preserve asset URLs or update references in the same PR.
114+
115+
5. API/server moves
116+
- Move Node/API/server entry points and service code into `api/`.
117+
- Preserve API contract shape and route behavior.
118+
119+
6. Runtime/shared source boundary cleanup
120+
- Move deployable browser/runtime/API modules into `www/` or `api/` ownership as appropriate.
121+
- Keep shared runtime dependency direction explicit.
122+
123+
7. Developer bootstrap and validation updates
124+
- Update local developer bootstrap and validation paths after deployable surfaces are moved.
125+
- Keep `dev/` developer-only.
126+
127+
8. Legacy path cleanup
128+
- Remove or archive obsolete empty folders and compatibility shims only after validation proves they are unused.
129+
130+
## Hard Rules
131+
132+
- No feature work may be mixed into repository layout migration.
133+
- Runtime must never depend on `dev/`.
134+
- Browser code must never own authoritative product data.
135+
- Browser code must use Browser -> API -> Postgres/R2 for product data.
136+
- API/server code must not import from developer-only reports, Project Instructions, tests, or workspace artifacts.
137+
- Migration PRs must not change package commands unless the PR explicitly owns command migration.
138+
- Migration PRs must not introduce Creator-writeable repository folders.
139+
- Migration PRs must not hide behavior changes inside path moves.
140+
141+
## Validation Expectations
142+
143+
Every layout migration PR must at minimum run:
144+
145+
```text
146+
git diff --check
147+
npm run validate:canonical-structure
148+
```
149+
150+
Additional targeted validation must match the moved surface.
151+

‎dev/reports/PR_26180_OWNER_004-repository-layout-architecture-plan_branch-validation.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# PR_26180_OWNER_004 Branch Validation
2+
3+
| Gate | Result | Evidence |
4+
|---|---|---|
5+
| Project Instructions loaded | PASS | Version `2026.06.28.003` loaded before work began; PR bumps to `2026.06.28.004`. |
6+
| Repository source | PASS | Loaded from `dev/build/ProjectInstructions/`. |
7+
| Cached memory discarded | PASS | Repository files used as authority. |
8+
| Branching policy loaded | PASS | `dev/build/ProjectInstructions/PROJECT_BRANCHING_POLICY.md`. |
9+
| Start branch | PASS | Started from synchronized `main`. |
10+
| Working branch | PASS | `PR_26180_OWNER_004-repository-layout-architecture-plan`. |
11+
| Worktree before edits | PASS | Clean before edits. |
12+
| Scope | PASS | Documentation/governance only. |
13+

‎dev/reports/PR_26180_OWNER_004-repository-layout-architecture-plan_manual-validation-notes.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# PR_26180_OWNER_004 Manual Validation Notes
2+
3+
- Confirmed the new architecture plan is proposal-only and explicitly does not authorize file moves.
4+
- Confirmed proposed future layout documents `www/`, `api/`, and `dev/`.
5+
- Confirmed migration hard rules prohibit feature work mixed with path migration.
6+
- Confirmed runtime dependency on `dev/` is prohibited.
7+
- Confirmed browser-owned authoritative product data is prohibited.
8+
- Confirmed `BACKLOG_MASTER.md` contains the planned Owner backlog item.
9+
- Confirmed Project Instructions version is updated to `2026.06.28.004`.
10+
- Confirmed no package command changes.
11+

‎dev/reports/PR_26180_OWNER_004-repository-layout-architecture-plan_report.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# PR_26180_OWNER_004 Repository Layout Architecture Plan Report
2+
3+
## Executive Summary
4+
5+
PASS: Added a documentation/governance-only architecture plan for future repository layout simplification before any file moves.
6+
7+
The proposed future layout is:
8+
9+
- `www/` = browser-served application
10+
- `api/` = Node/API/server application
11+
- `dev/` = developer-only workspace
12+
13+
No files were moved. No runtime, UI, API implementation, database implementation, or `package.json` command changes were made.
14+
15+
## Changes
16+
17+
- Added `dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md`.
18+
- Updated `PROJECT_INSTRUCTIONS.md` to reference the new proposed layout plan.
19+
- Bumped Project Instructions version to `2026.06.28.004`.
20+
- Updated `BACKLOG_MASTER.md` with Owner planned work:
21+
- Team: Owner
22+
- Product Area: Repository Architecture Simplification
23+
- Status: Planned
24+
- Percent Complete: 0%
25+
- Next Milestone: Architecture plan
26+
27+
## Architecture Plan Coverage
28+
29+
| Required Topic | Result |
30+
|---|---|
31+
| Proposed `www/`, `api/`, `dev/` layout | PASS |
32+
| Deployment model | PASS |
33+
| Browser/API/database flow | PASS |
34+
| Developer local-runtime flow | PASS |
35+
| Migration strategy | PASS |
36+
| Stacked PR sequence | PASS |
37+
| No feature work mixed into migration | PASS |
38+
| Runtime must never depend on `dev/` | PASS |
39+
| Browser must never own authoritative product data | PASS |
40+
41+
## Scope Validation
42+
43+
Changed files are limited to Project Instructions, backlog governance, and reports.
44+
45+
Implementation files, runtime code, UI files, API implementation files, database implementation files, and package commands were not changed.
46+
47+
## Artifact
48+
49+
Repo-structured outcome ZIP:
50+
51+
```text
52+
dev/workspace/zips/PR_26180_OWNER_004-repository-layout-architecture-plan_delta.zip
53+
```

‎dev/reports/PR_26180_OWNER_004-repository-layout-architecture-plan_requirement-checklist.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# PR_26180_OWNER_004 Requirement Checklist
2+
3+
| Requirement | Result | Notes |
4+
|---|---|---|
5+
| Document proposed future layout `www/`, `api/`, `dev/` | PASS | Added to repository layout architecture plan. |
6+
| Include deployment model | PASS | `www/` and `api/` deployable surfaces documented; `dev/` non-runtime. |
7+
| Include browser/API/database flow | PASS | Browser -> API -> Postgres/R2 documented. |
8+
| Include developer local-runtime flow | PASS | Developer command -> dev bootstrap -> local www/API flow documented. |
9+
| Include migration strategy | PASS | Strategy and constraints documented. |
10+
| Include stacked PR sequence | PASS | Eight-step proposed sequence documented. |
11+
| Hard rule: no feature work mixed into migration | PASS | Documented. |
12+
| Hard rule: runtime must never depend on `dev/` | PASS | Documented. |
13+
| Hard rule: browser must never own authoritative product data | PASS | Documented. |
14+
| Update `BACKLOG_MASTER.md` Owner planned item | PASS | Added Team/Product Area/Status/Percent/Next Milestone entry. |
15+
| Increment Project Instructions version if ProjectInstructions changed | PASS | Version bumped to `2026.06.28.004`. |
16+
| Do not move files | PASS | No file moves performed. |
17+
| Do not modify runtime code | PASS | No runtime files changed. |
18+
| Do not change `package.json` commands | PASS | `package.json` unchanged. |
19+

‎dev/reports/PR_26180_OWNER_004-repository-layout-architecture-plan_validation-report.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# PR_26180_OWNER_004 Validation Report
2+
3+
## Validation Commands
4+
5+
| Command | Result |
6+
|---|---|
7+
| `git diff --check` | PASS |
8+
| `npm run validate:canonical-structure` | PASS |
9+
10+
## Canonical Structure Output
11+
12+
```text
13+
Canonical repository structure guardrail: PASS
14+
Blocking violations: 0
15+
Approved legacy exceptions: 501
16+
```
17+
18+
## Scope Validation
19+
20+
No runtime, UI, API implementation, database implementation, or package command files changed.
21+
22+
Playwright was not run because this is documentation/governance-only and no runtime/UI files changed.
23+

‎dev/reports/codex_changed_files.txt‎

Lines changed: 25 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,25 @@
1-
dev/reports/PR_26179_CHARLIE_022-sprites-tool-shell.md
2-
dev/reports/PR_26179_CHARLIE_023-sprites-toolbar-placeholders.md
3-
dev/reports/PR_26179_CHARLIE_024-sprites-canvas-grid.md
4-
dev/reports/PR_26179_CHARLIE_025-sprites-basic-drawing.md
5-
dev/reports/PR_26179_CHARLIE_026-sprites-palette-panel.md
6-
dev/reports/PR_26179_CHARLIE_027-sprites-preview-export.md
7-
dev/reports/PR_26179_CHARLIE_028-sprites-editor-polish.md
8-
dev/reports/PR_26179_CHARLIE_029-sprites-clear-reset-controls.md
9-
dev/reports/PR_26179_CHARLIE_030-sprites-undo-redo.md
10-
dev/reports/PR_26179_CHARLIE_031-sprites-picker-zoom.md
11-
dev/reports/PR_26179_CHARLIE_032-sprites-shape-tools.md
12-
dev/reports/PR_26179_CHARLIE_033-sprites-canvas-preview-sync.md
13-
dev/reports/PR_26179_CHARLIE_034-sprites-frame-strip.md
14-
dev/reports/PR_26179_CHARLIE_035-sprites-frame-editing.md
15-
dev/reports/PR_26179_CHARLIE_036-sprites-animation-preview.md
16-
dev/reports/PR_26179_CHARLIE_037-sprites-animation-export.md
17-
dev/reports/PR_26179_CHARLIE_038-sprites-grid-dimension-fix.md
18-
dev/reports/PR_26179_CHARLIE_039-sprites-color-and-zoom-fix.md
19-
dev/reports/PR_26179_CHARLIE_040-dev-artifact-location-cleanup.md
20-
dev/reports/codex_changed_files.txt
21-
dev/reports/codex_review.diff
22-
docs_build/dev/reports/codex_changed_files.txt
23-
docs_build/dev/reports/codex_review.diff
1+
# git diff --name-status merge-base(origin/main, HEAD)..working-tree
2+
M dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md
3+
M dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS_VERSION.md
4+
M dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md
5+
M dev/reports/codex_changed_files.txt
6+
M dev/reports/codex_review.diff
7+
8+
# git ls-files --others --exclude-standard
9+
dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md
10+
dev/reports/PR_26180_OWNER_004-repository-layout-architecture-plan_branch-validation.md
11+
dev/reports/PR_26180_OWNER_004-repository-layout-architecture-plan_manual-validation-notes.md
12+
dev/reports/PR_26180_OWNER_004-repository-layout-architecture-plan_report.md
13+
dev/reports/PR_26180_OWNER_004-repository-layout-architecture-plan_requirement-checklist.md
14+
dev/reports/PR_26180_OWNER_004-repository-layout-architecture-plan_validation-report.md
15+
16+
# git diff --stat merge-base(origin/main, HEAD)..working-tree
17+
.../ProjectInstructions/PROJECT_INSTRUCTIONS.md | 3 +-
18+
.../PROJECT_INSTRUCTIONS_VERSION.md | 3 +-
19+
.../ProjectInstructions/backlog/BACKLOG_MASTER.md | 12 +
20+
dev/reports/codex_changed_files.txt | 46 +-
21+
dev/reports/codex_review.diff | 1085 +++++++-------------
22+
5 files changed, 430 insertions(+), 719 deletions(-)
23+
24+
# merge-base
25+
b3a2b30f51a1050596bbad2d7db211e1cba45b66

0 commit comments

Comments
 (0)