# EffoRise Client — Vercel Deployment Roadmap

> **App:** `effo-rise-ai` (Vite SPA)
> **Repo:** `learning_ai_efforise` → root `vite.config.ts`, client source in `client/`
> **Status:** ⚠️ Partial — Vite SPA needs rewrites + API proxy strategy

---

## Current State

- **Framework:** Vite 7.1.7, React 19.2.1, TailwindCSS v4, shadcn/ui
- **Build:** `vite build` → output at `dist/public/`
- **Routing:** `wouter` (client-side SPA routing)
- **Dependencies:** 8 `@bytelyst/*` — **all via Gitea registry** ✅ (no `file:` refs)
- **API proxy:** Dev server proxies `/api` → `http://localhost:4020` (Fastify backend)
- **No Next.js** — this is a pure Vite SPA, not SSR

## Gaps to Fix

### Gap 1: Vercel Framework Configuration (~10 min)

Vercel supports Vite out of the box, but needs correct settings.

- [ ] Create `vercel.json` in repo root:
  ```json
  {
    "buildCommand": "pnpm build",
    "outputDirectory": "dist/public",
    "framework": "vite",
    "rewrites": [
      { "source": "/api/(.*)", "destination": "https://YOUR_BACKEND_URL/api/$1" },
      { "source": "/(.*)", "destination": "/index.html" }
    ]
  }
  ```

### Gap 2: API Proxy Strategy (~10 min)

The SPA proxies `/api` to the Fastify backend. On Vercel, options:

**Options:**

- **A) Vercel Rewrites** — proxy `/api/*` to the deployed backend URL (recommended)
- **B) Direct API calls** — configure `VITE_API_URL` env var, update API client to use absolute URLs
- **C) Vercel Serverless Functions** — not feasible (backend is Fastify, not Node serverless)

**Recommended:** Option A with Vercel rewrites, falling back to Option B.

- [ ] Choose proxy strategy
- [ ] Update `vercel.json` or API client accordingly
- [ ] Set `VITE_BACKEND_URL` = `https://api.bytelyst.com/efforise`

### Gap 3: SPA Client-Side Routing (~5 min)

`wouter` handles routing client-side. All routes must serve `index.html`.

- [ ] Add catch-all rewrite in `vercel.json`: `{ "source": "/(.*)", "destination": "/index.html" }`

### Gap 4: Registry Access (~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 5: Build Output Directory (~5 min)

Vite outputs to `dist/public/` (custom, not default `dist/`). Vercel needs to know.

- [ ] Set **Output Directory** to `dist/public` in Vercel project settings or `vercel.json`

## Deployment Steps

### Step 1: Create `vercel.json` (~10 min)

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

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

- [ ] Connect `learning_ai_efforise` repo
- [ ] Framework preset: **Vite**
- [ ] Root directory: `/` (vite.config.ts is at root)
- [ ] Build command: `pnpm build`
- [ ] Output directory: `dist/public`

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

- [ ] `VITE_BACKEND_URL` — EffoRise backend endpoint (port 4020)
- [ ] (Client-side only — all `VITE_*` vars are embedded at build time)

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

- [ ] Test SPA routing (navigate between pages, refresh deep links)
- [ ] Test API connectivity (identity CRUD, habit tracking)
- [ ] Verify shadcn/ui components render correctly

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

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

## Risks

- **API proxy reliability:** Vercel rewrites to external backend add a hop. Latency depends on backend hosting location.
- **Build-time env vars:** Vite embeds `VITE_*` vars at build time. Changing backend URL requires a redeploy.
- **No SSR:** Pure SPA — no SEO benefits. Landing page should be separate or use meta tags.

## Estimated Total Effort: ~40 minutes