MySuperApp

Personal super app — a Next.js 14 monorepo hosting modular mini-apps (assistant, stocks). Runs locally on port 3000 and is reached from mobile via Tailscale.

Quick start

pnpm install
pnpm dev               # turbo runs all apps; web is on http://localhost:3000
pnpm --filter @mysuperapp/web test

New machine setup

1. Toolchain

Tool	Version	Notes
Node	>= 20 (tested 25)	Use nvm / fnm on Mac/Linux, nvm-windows
pnpm	9.15.0	corepack enable && corepack prepare pnpm@9.15.0 --activate
Git	any recent	Set core.autocrlf=true on Windows
Claude Code	latest	npm i -g @anthropic-ai/claude-code — the assistant shells out to claude -p
Tailscale	latest	Required for phone PWA access (see step 5)

2. Clone + install

git clone https://github.com/<your-org>/MySuperApp.git
cd MySuperApp
pnpm install

3. Environment

The web app reads apps/web/.env.local. It is gitignored — copy from the old machine or recreate. Required vars:

# Database (SQLite via libsql)
DATABASE_URL=file:./local.db

# NextAuth — SKIP_AUTH=true bypasses login for personal/local use
SKIP_AUTH=true
AUTH_SECRET=<openssl rand -base64 32>
AUTH_TRUST_HOST=true
AUTH_URL=http://<tailscale-hostname>:3000   # e.g. http://sbook.tail4621a0.ts.net:3000

# Web Push (VAPID) — generate once with: npx web-push generate-vapid-keys
VAPID_PUBLIC_KEY=<public>
VAPID_PRIVATE_KEY=<private>
NEXT_PUBLIC_VAPID_PUBLIC_KEY=<public>        # same as VAPID_PUBLIC_KEY
VAPID_SUBJECT=mailto:you@example.com

# Internal bearer for /api/push/fire (used by cron / external triggers)
PUSH_INTERNAL_TOKEN=<openssl rand -hex 32>

# Assistant
GH_TOKEN=<github personal access token — only if using GitHub Models fallback>
ASSISTANT_WORKSPACE_PATH=C:\Users\<you>\OneDrive\Assistant   # absolute path to the assistant notes workspace

VAPID keys: regenerating these invalidates every existing push subscription. If you want existing devices to keep working, copy the old keys verbatim.

4. Database

SQLite file at apps/web/local.db is created on first run (initializeDatabase runs lazily). To start fresh, just delete the file.

pnpm db:generate    # regenerate Drizzle migrations from schema (only when schema changes)
pnpm db:studio      # browse the DB

5. Tailscale (phone access)

The PWA on your phone connects to the dev server via Tailscale, not localhost.

1. Install Tailscale on the new machine and sign in with the same account.
2. Note the machine's Tailscale hostname (e.g. sbook.tail4621a0.ts.net).
3. Set AUTH_URL in .env.local to http://<hostname>:3000.
4. On the phone, open http://<hostname>:3000 in Chrome/Safari → "Add to Home Screen".
5. Grant notification permission to enable Web Push.

6. Assistant workspace (OneDrive)

The personal-assistant surface reads/writes notes from a OneDrive folder so all surfaces (Claude Code, Copilot, SuNaPaNa email bot, in-app chat) share state.

1. Install OneDrive on the new machine; sign in.
2. Wait for OneDrive/Assistant/ to sync down (contains CLAUDE.md, notes/, .claude/commands/).
3. Point ASSISTANT_WORKSPACE_PATH at the absolute synced path.

7. Out-of-repo dependencies

These live outside this repo and are not auto-cloned. Migrate manually:

Path	What it is	Migration
C:\mcp-servers\sunnapana	Email-driven assistant (30min cron)	Copy folder; restart its service
C:\mcp-servers\outlook-email	Outlook MCP server	Copy folder
C:\mcp-servers\travel-scanner	Travel scanner MCP server	Copy folder
c:\git\music\carnatic_ml	ML experiments (not in git)	Copy folder; reinstall Python deps

Long term: each of these should become its own git repo. For now, copy via external drive or sync via OneDrive.

8. Smoke test

pnpm dev
# Visit http://localhost:3000 from the machine itself
# Visit http://<tailscale-host>:3000 from phone
# Open /assistant — send "hi", verify reply streams in
# Open /stocks — verify quotes load
# Send a /remind to test the tool path

Layout

apps/
  web/                  Next.js 14 (App Router). The shell + API routes.
miniapps/
  assistant/            Chat + tools (Claude Code CLI integration)
  stocks/               Watchlist, quotes, fundamentals (Yahoo Finance)
packages/
  ui, core, database,   Shared workspace packages
  config, tailwind-config, typescript-config, eslint-config

Common commands

pnpm dev                                       # all apps via turbo
pnpm --filter @mysuperapp/web dev              # just the web app
pnpm --filter @mysuperapp/web test             # vitest run
pnpm --filter @mysuperapp/web lint
pnpm build

Troubleshooting

• Phone PWA blank / "site can't be reached": Tailscale not connected on phone, or AUTH_URL doesn't match the hostname the phone is hitting.
• Push notifications silent: VAPID keys changed → re-subscribe from the PWA Settings page.
• claude not found when assistant runs: ensure Claude Code CLI is on PATH for the shell that started pnpm dev. On Windows, the .cmd shim must be invocable as claude (check where claude).
• Port 3000 stops responding after ~60s: the dev server was likely launched with an inline timeout. Restart without one.