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

Layout And Naming

Canonical Structure

<repo-root>/
  web/
    app.py
    <web modules>
    requirements.txt
  mac/
    <AppName>Mac/
      <AppName>Mac.xcodeproj/
      <AppName>Mac/
        ContentView.swift
        <AppName>MacApp.swift
        EmbeddedBackend/
          <AppName>Backend
  scripts/
    build_embedded_backend.sh
    build_selfcontained_mac_app.sh
    create_installer_dmg.sh
  docs/
    architecture.md
    onboarding.md

Naming Rules

• Repo: lowercase hyphenated (trader-desktop-shell).
• macOS app target/project: PascalCase with Mac suffix (TraderMac).
• Embedded backend binary: PascalCase + Backend (TraderBackend).
• Settings directory: lowercase snake or kebab (~/.trader_app).
• Environment port var: uppercase snake (TRADER_PORT).

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. Rename Xcode project/target last, with a dedicated verification commit.

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. build(packaging): add self-contained app + dmg scripts
6. chore(rename): finalize naming migration