maneshtrader/skills/macos-selfcontained-webapp/references/layout-and-naming.md

Layout And Naming

Canonical Structure

<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