hermes-mobile/PROJECT_STRUCTURE.md

Proposed Project Structure

hermes-mobile/
  README.md
  PROJECT_STRUCTURE.md
  LICENSE
  .gitignore
  .editorconfig
  package.json                 # pnpm workspace root, later
  pnpm-workspace.yaml
  tsconfig.base.json
  install.sh                   # one-liner installer entrypoint, later
  docs/
    PRODUCT_PLAN.md
    ARCHITECTURE.md
    DESIGN_SYSTEM.md
    COMPANION_SERVER.md
    MOBILE_APP.md
    INSTALL.md
    TESTING.md
    ROADMAP.md
  apps/
    mobile/                    # Android-first PWA
      package.json
      vite.config.ts
      index.html
      public/
        manifest.webmanifest
        icons/
      src/
        app/
          App.tsx
          router.tsx
          providers.tsx
        screens/
          AskScreen/
          ActivityScreen/
          CronScreen/
          FilesScreen/
          SettingsScreen/
        components/
          agent-status-orb/
          composer/
          tool-card/
          event-timeline/
          upload-tray/
          voice-recorder/
          cron-job-card/
          approval-card/
          bottom-nav/
          app-shell/
        features/
          tasks/
          sessions/
          cron/
          files/
          approvals/
          notifications/
          pairing/
          settings/
        lib/
          api-client.ts
          realtime.ts
          push.ts
          audio.ts
          file-utils.ts
          format.ts
        styles/
          globals.css
          tokens.css
        main.tsx
    companion/                 # local server installed beside Hermes Agent
      package.json
      src/
        app.ts
        config/
          index.ts
          schema.ts
        auth/
          pairing.ts
          sessions.ts
          middleware.ts
        db/
          client.ts
          migrations/
          repositories/
        events/
          bus.ts
          types.ts
          websocket.ts
          sse.ts
        hermes/
          HermesAdapter.ts
          CliHermesAdapter.ts
          ApiHermesAdapter.ts
          PythonHermesAdapter.ts
          promptFormatting.ts
        tasks/
          TaskManager.ts
          TaskQueue.ts
          taskTypes.ts
        uploads/
          uploadRoutes.ts
          UploadStore.ts
          fileValidation.ts
        notifications/
          NotificationProvider.ts
          WebPushProvider.ts
          NtfyProvider.ts
          GotifyProvider.ts
          NoopProvider.ts
        cron/
          CronService.ts
          HermesCronAdapter.ts
        approvals/
          ApprovalService.ts
        routes/
          health.ts
          tasks.ts
          uploads.ts
          sessions.ts
          cron.ts
          approvals.ts
          settings.ts
        system/
          hermesHealth.ts
          logs.ts
        index.ts
      scripts/
        hermes_worker.py       # direct Python bridge later
  packages/
    shared/                    # shared TS types/schemas
      package.json
      src/
        events.ts
        api.ts
        tasks.ts
        cron.ts
        files.ts
        notifications.ts
    ui/                        # optional shared UI primitives later
      package.json
      src/
  scripts/
    install.sh
    uninstall.sh
    dev-hermes-smoke.sh
    build-release.sh
  deploy/
    systemd/
      hermes-mobile-companion.service
    nginx/
      hermes-mobile.conf
    caddy/
      Caddyfile.example

Modularity Notes

• apps/mobile should never import Hermes-specific server internals directly. It uses packages/shared schemas and API client only.
• apps/companion/src/hermes is the only layer that knows how to talk to Hermes Agent.
• apps/companion/src/notifications is provider-swappable.
• apps/companion/src/cron wraps Hermes cron rather than replacing it.
• packages/shared defines stable event types used by both app and server.
• scripts/ and deploy/ stay boring and auditable.