docs: initial Hermes Mobile planning scaffold

2026-07-09 03:45:48 +00:00
commit 2cd4730324
14 changed files with 2139 additions and 0 deletions
@@ -0,0 +1,166 @@
+# Proposed Project Structure
+
+```text
+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.