73 lines
2.3 KiB
Markdown
73 lines
2.3 KiB
Markdown
# Layout And Naming
|
|
|
|
## Canonical Structure
|
|
|
|
```text
|
|
<repo-root>/
|
|
web/
|
|
run.sh
|
|
src/
|
|
app.py
|
|
<web modules>
|
|
requirements.txt
|
|
ONBOARDING.md
|
|
mac/
|
|
src/
|
|
<Project>.xcodeproj/
|
|
App/
|
|
ContentView.swift
|
|
<AppMain>.swift
|
|
EmbeddedBackend/
|
|
WebBackend
|
|
Help/
|
|
help.html
|
|
AppTests/
|
|
AppUITests/
|
|
scripts/
|
|
build_embedded_backend.sh
|
|
build_selfcontained_mac_app.sh
|
|
create_installer_dmg.sh
|
|
build/
|
|
dmg/
|
|
<AppName>-<timestamp>.dmg
|
|
docs/
|
|
architecture.md
|
|
```
|
|
|
|
## Naming Rules
|
|
- Repo: lowercase hyphenated (`trader-desktop-shell`).
|
|
- macOS target/scheme: PascalCase (`TraderMac` or project-defined), but source folders should stay generic (`App`, `AppTests`, `AppUITests`).
|
|
- Embedded backend binary: stable generic default (`WebBackend`) with env override support.
|
|
- Settings directory: lowercase snake or kebab (`~/.trader_app`).
|
|
- Environment port var: uppercase snake (keep legacy fallbacks during migration).
|
|
|
|
## Script Discovery Rules
|
|
- Build scripts should discover the first `*.xcodeproj` under `mac/src` unless `MAC_PROJECT_PATH` is provided.
|
|
- Build scripts should discover scheme via `xcodebuild -list -json` unless `MAC_SCHEME` is provided.
|
|
- Embedded backend target dir should be derived from selected project sources or `EMBEDDED_BACKEND_DIR`.
|
|
- Python tests should run with `PYTHONPATH=web/src`.
|
|
- DMG scripts should write to `build/dmg/` and clean temporary staging folders.
|
|
|
|
## Ignore Rules
|
|
Add these to root `.gitignore`:
|
|
- `build/`
|
|
- `*.dmg`
|
|
- `rw.*.dmg`
|
|
|
|
## Migration Rules For Existing Projects
|
|
1. Do not rename everything in one commit.
|
|
2. First, add new folders and compatibility references.
|
|
3. Move scripts and docs next.
|
|
4. Move web source only after build scripts are updated.
|
|
5. Move mac source into `mac/src/App*` before optional target/project renames.
|
|
6. Add compatibility lookup for old backend binary names and old settings paths during transition.
|
|
|
|
## Commit Strategy
|
|
1. `chore(layout): add canonical folders`
|
|
2. `build(backend): add embedded binary build`
|
|
3. `feat(mac-shell): host local backend in webview`
|
|
4. `feat(sync): add shared settings contract`
|
|
5. `feat(help): add native help popup + web fallback`
|
|
6. `build(packaging): add self-contained app + dmg scripts`
|
|
7. `chore(rename): finalize naming migration`
|