# 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`