# ChronoMind Web — Vercel Deployment Roadmap

> **App:** ChronoMind Web
> **Repo:** `learning_ai_clock` → `web/`
> **Status:** 🔴 Blocked — `file:` refs + Serwist PWA

---

## Current State

- **Framework:** Next.js 16.1.6, React 19.2.3, TailwindCSS v4
- **Output:** Vercel-aware
- **Dependencies:** 10 `@bytelyst/*` — **2 via `file:` refs** (`design-tokens`, `ui`), 8 via Gitea
- **Build:** `next build --webpack`
- **Special:** Serwist PWA with service worker (`@serwist/next`)
- **Client-side only** — no server-side Cosmos/API routes (connects to backend at runtime)

## Gaps to Fix

### Gap 1: Convert `file:` refs to registry refs (~10 min)

Both packages are already published to Gitea registry.

**Files to edit:** `web/package.json`

```diff
- "@bytelyst/design-tokens": "file:../../learning_ai_common_plat/packages/design-tokens",
+ "@bytelyst/design-tokens": "^0.1.0",
- "@bytelyst/ui": "file:../../learning_ai_common_plat/packages/ui",
+ "@bytelyst/ui": "^0.1.0",
```

- [ ] Update `package.json` — replace 2 `file:` refs with `^0.1.0`
- [ ] Run `pnpm install` to update lockfile
- [ ] Verify `pnpm build` still passes

### Gap 2: Registry Access on Vercel (~5 min)

Once Caddy is configured on the Azure VM (see [SECURE_API_EXPOSURE.md](../single_azure_vm/docker/SECURE_API_EXPOSURE.md)), Gitea will be accessible at `https://gitea.bytelyst.com`.

- [ ] Update `.npmrc`:
  ```
  @bytelyst:registry=https://gitea.bytelyst.com/api/packages/ByteLyst/npm/
  //gitea.bytelyst.com/api/packages/ByteLyst/npm/:_authToken=${GITEA_NPM_TOKEN}
  ```
- [ ] Set `GITEA_NPM_TOKEN` as a Vercel environment variable

### Gap 3: Serwist PWA Service Worker (~10 min)

Serwist generates a service worker at `public/sw.js`. Vercel serves static files from `public/`, so this should work, but needs verification.

- [ ] Verify `Cache-Control` headers for `sw.js` (should be `no-cache` or short TTL)
- [ ] Add Vercel `vercel.json` header override if needed:
  ```json
  {
    "headers": [
      { "source": "/sw.js", "headers": [{ "key": "Cache-Control", "value": "no-cache" }] }
    ]
  }
  ```
- [ ] Test PWA install flow on Vercel preview URL

## Deployment Steps

### Step 1: Fix `file:` refs (~10 min)

### Step 2: Fix registry access (~5 min)

### Step 3: Create Vercel Project (~5 min)

- [ ] Connect `learning_ai_clock` repo
- [ ] Set **Root Directory** to `web`
- [ ] Framework preset: **Next.js**
- [ ] Build command: `pnpm build`

### Step 4: Environment Variables (~5 min)

- [ ] `NEXT_PUBLIC_PLATFORM_URL` — platform-service endpoint
- [ ] `NEXT_PUBLIC_BACKEND_URL` — ChronoMind backend endpoint (port 4011)

### Step 5: Verify PWA (~10 min)

- [ ] Verify service worker registration
- [ ] Test offline functionality
- [ ] Verify manifest.json loads correctly

### Step 6: Domain (~5 min)

- [ ] Add custom domain (e.g., `app.chronomind.app`)

## Estimated Total Effort: ~50 minutes