bytelyst/learning_ai_common_plat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(vercel): review and fix ecosystem web apps audit — update registry strategy to Gitea-on-Azure-VM, fix effort estimates, fix EffoRise path, remove spurious PeakPulse entry, add prerequisite section

Browse Source
This commit is contained in:
saravanakumardb1 2026-03-29 15:46:21 -07:00
parent 64885dbc33
commit e6b625f4e2
12 changed files with 85 additions and 102 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
docs/devops/vercel/ECOSYSTEM_WEB_APPS_INVENTORY.md
View File

@ -34,13 +34,14 @@
### Blocker Categories
| Blocker | Count | Fix Effort |
| ---------------------------------- | :----: | :-----------------------------------------------------: |
| **`file:` refs to common-plat** | 7 apps | ~30 min/app — publish to Gitea registry |
| **Hardcoded `output: standalone`** | 4 apps | ~5 min/app — add Vercel-aware conditional |
| **No TailwindCSS** | 2 apps | Cosmetic — not a deployment blocker |
| **Serwist PWA** | 1 app | May need Vercel config for service worker |
| **Local-only dependencies** | 1 app | LLM Lab needs Ollama — Vercel won't work for API routes |
| Blocker | Count | Fix Effort |
| ------------------------------------------- | :-----: | :----------------------------------------------------------: |
| **`file:` refs to common-plat** | 7 apps | ~5 min/app — convert to `^0.1.0` (packages already on Gitea) |
| **Gitea registry inaccessible from Vercel** | 12 apps | One-time fix — deploy Gitea to Azure VM with public URL |
| **Hardcoded `output: standalone`** | 4 apps | ~5 min/app — add Vercel-aware conditional |
| **No TailwindCSS** | 2 apps | Cosmetic — not a deployment blocker |
| **Serwist PWA** | 1 app | May need Vercel config for service worker |
| **Local-only dependencies** | 1 app | LLM Lab needs Ollama — Vercel won't work for API routes |
---
@ -253,10 +254,10 @@
| Field | Value |
| --------------------- | ---------------------------------------------------------------------------------------------------- |
| **Repo** | `learning_ai_efforise` |
| **Path** | `client/` (root vite.config.ts) |
| **Path** | `/` (root `vite.config.ts`, client source in `client/`) |
| **Framework** | Vite 7.1.7, React 19.2.1 |
| **Styling** | TailwindCSS v4, shadcn/ui |
| **Port** | 3000 |
| **Port** | 3000 (Vite dev) / 4020 (backend API) |
| **Build** | `vite build` → `dist/public/` |
| **@bytelyst/\* deps** | 8 packages via Gitea registry ✅ |
| **Special** | SPA with API proxy (`/api` → localhost:4020); `wouter` for routing |
@ -282,37 +283,17 @@
---
## Common `file:` Reference Blockers
## Prerequisite: Gitea NPM Registry on Azure VM
The most common Vercel blocker is `file:` references to `learning_ai_common_plat/packages/`. These resolve locally but fail on Vercel since the sibling repo doesn't exist.
All 12 product web apps (everything except admin-web and tracker-web which use `workspace:*`) pull `@bytelyst/*` packages from the local Gitea npm registry. Currently Gitea runs at `http://localhost:3300`, which Vercel can't reach.
| Package | Apps Using `file:` | Fix |
| ------------------------- | ---------------------------------------------------------------------- | ------------------------------- |
| `@bytelyst/ui` | ChronoMind, JarvisJr, NomGap, FlowMonk, NoteLett, LocalMemGPT, LLM Lab | Publish to Gitea → use `^0.1.0` |
| `@bytelyst/design-tokens` | ChronoMind, LLM Lab | Publish to Gitea → use `^0.1.0` |
**Once Gitea is deployed to the Azure VM with a public HTTPS URL** (e.g., `https://gitea.bytelyst.com`), this blocker is eliminated for all apps simultaneously:
**Note:** Both packages are already published to the local Gitea npm registry. The fix is simply converting the `file:` references to semver references and ensuring `.npmrc` points to Gitea.
1. Update `.npmrc` in each repo: `@bytelyst:registry=https://gitea.bytelyst.com/api/packages/YOUR_ORG/npm/`
2. Set `GITEA_NPM_TOKEN` as a Vercel environment variable per project
3. All 49 `@bytelyst/*` packages are already published — no re-publishing needed
---
## Environment Variable Categories
### Server-side secrets (need Vercel env vars)
- `COSMOS_ENDPOINT`, `COSMOS_KEY` — Admin, User, MindLyst dashboards
- `JWT_SECRET` — Admin, User, Tracker dashboards
- `STRIPE_SECRET_KEY`, `STRIPE_PUBLISHABLE_KEY` — User dashboard
- `AZURE_KEYVAULT_URL` — Admin, User, Tracker dashboards
- `OPENAI_API_KEY` — MindLyst web
### Client-side public (NEXT*PUBLIC*\*)
- `NEXT_PUBLIC_PLATFORM_URL` — most product web apps
- `NEXT_PUBLIC_BACKEND_URL` — product web apps pointing to their Fastify backend
### Not Vercel-compatible
- `OLLAMA_HOST` — LLM Lab (requires local Ollama instance)
**This is the single highest-leverage fix in the ecosystem.** Once done, the per-app registry access gap disappears from every roadmap.
---
@ -347,8 +328,8 @@ Vercel Organization: ByteLyst
### Product web apps (all others)
- Each gets its own Vercel project connected to its repo
- Root directory set to `web/` (or `client/` for EffoRise)
- Gitea npm registry configured via `NPM_CONFIG_REGISTRY` or `.npmrc`
- Root directory set to `web/` (or `/` for EffoRise, `mindlyst-native/web/` for MindLyst)
- Gitea npm registry configured via `.npmrc` pointing to Azure VM Gitea + `GITEA_NPM_TOKEN` env var
---

11
docs/devops/vercel/ROADMAP_ACTIONTRAIL_WEB.md
View File

@ -30,9 +30,12 @@
- [ ] Update `next.config.ts`
- [ ] Verify Docker build still works
### Gap 2: Registry Access (~15 min)
### Gap 2: Registry Access (~5 min)
- [ ] Configure Vercel-compatible npm registry for `@bytelyst/*` scope
Once Gitea is deployed to the Azure VM with a public HTTPS URL, update `.npmrc`.
- [ ] Update `.npmrc` to Azure VM Gitea URL
- [ ] Set `GITEA_NPM_TOKEN` as a Vercel environment variable
### Gap 3 (optional): SSE Compatibility
@ -45,7 +48,7 @@ Vercel serverless functions have a 25-second timeout (Hobby) / 300s (Pro). SSE s
### Step 1: Fix output mode (~5 min)
### Step 2: Fix registry access (~15 min)
### Step 2: Fix registry access (~5 min)
### Step 3: Create Vercel Project (~5 min)
@ -68,4 +71,4 @@ Vercel serverless functions have a 25-second timeout (Hobby) / 300s (Pro). SSE s
- [ ] Add custom domain (e.g., `app.actiontrail.dev`)
## Estimated Total Effort: ~45 minutes
## Estimated Total Effort: ~35 minutes

12
docs/devops/vercel/ROADMAP_CHRONOMIND_WEB.md
View File

@ -34,12 +34,12 @@ Both packages are already published to Gitea registry.
- [ ] Run `pnpm install` to update lockfile
- [ ] Verify `pnpm build` still passes
### Gap 2: Registry Access on Vercel (~15 min)
### Gap 2: Registry Access on Vercel (~5 min)
Same as all product repos — `.npmrc` points to local Gitea.
Once Gitea is deployed to the Azure VM with a public HTTPS URL, update `.npmrc`.
- [ ] Choose registry strategy (npm / GitHub Packages / vendored tarballs)
- [ ] Update `.npmrc` for Vercel-compatible registry
- [ ] Update `.npmrc` to Azure VM Gitea URL (e.g., `@bytelyst:registry=https://gitea.bytelyst.com/api/packages/YOUR_ORG/npm/`)
- [ ] Set `GITEA_NPM_TOKEN` as a Vercel environment variable
### Gap 3: Serwist PWA Service Worker (~10 min)
@ -60,7 +60,7 @@ Serwist generates a service worker at `public/sw.js`. Vercel serves static files
### Step 1: Fix `file:` refs (~10 min)
### Step 2: Fix registry access (~15 min)
### Step 2: Fix registry access (~5 min)
### Step 3: Create Vercel Project (~5 min)
@ -84,4 +84,4 @@ Serwist generates a service worker at `public/sw.js`. Vercel serves static files
- [ ] Add custom domain (e.g., `app.chronomind.app`)
## Estimated Total Effort: ~60 minutes
## Estimated Total Effort: ~50 minutes

11
docs/devops/vercel/ROADMAP_EFFORISE.md
View File

@ -56,9 +56,12 @@ The SPA proxies `/api` to the Fastify backend. On Vercel, options:
- [ ] Add catch-all rewrite in `vercel.json`: `{ "source": "/(.*)", "destination": "/index.html" }`
### Gap 4: Registry Access (~15 min)
### Gap 4: Registry Access (~5 min)
- [ ] Configure Vercel-compatible npm registry for `@bytelyst/*` scope
Once Gitea is deployed to the Azure VM with a public HTTPS URL, update `.npmrc`.
- [ ] Update `.npmrc` to Azure VM Gitea URL
- [ ] Set `GITEA_NPM_TOKEN` as a Vercel environment variable
### Gap 5: Build Output Directory (~5 min)
@ -70,7 +73,7 @@ Vite outputs to `dist/public/` (custom, not default `dist/`). Vercel needs to kn
### Step 1: Create `vercel.json` (~10 min)
### Step 2: Fix registry access (~15 min)
### Step 2: Fix registry access (~5 min)
### Step 3: Create Vercel Project (~5 min)
@ -101,4 +104,4 @@ Vite outputs to `dist/public/` (custom, not default `dist/`). Vercel needs to kn
- **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: ~50 minutes
## Estimated Total Effort: ~40 minutes

11
docs/devops/vercel/ROADMAP_FLOWMONK_WEB.md
View File

@ -31,9 +31,12 @@
- [ ] Run `pnpm install`
- [ ] Verify build
### Gap 2: Registry Access (~15 min)
### Gap 2: Registry Access (~5 min)
- [ ] Configure Vercel-compatible npm registry for `@bytelyst/*` scope
Once Gitea is deployed to the Azure VM with a public HTTPS URL, update `.npmrc`.
- [ ] Update `.npmrc` to Azure VM Gitea URL
- [ ] Set `GITEA_NPM_TOKEN` as a Vercel environment variable
### Gap 3 (optional): Add TailwindCSS
@ -45,7 +48,7 @@ Not a deployment blocker, but the app lacks TailwindCSS unlike all other ecosyst
### Step 1: Fix `file:` ref (~5 min)
### Step 2: Fix registry access (~15 min)
### Step 2: Fix registry access (~5 min)
### Step 3: Create Vercel Project (~5 min)
@ -67,4 +70,4 @@ Not a deployment blocker, but the app lacks TailwindCSS unlike all other ecosyst
- [ ] Add custom domain (e.g., `app.flowmonk.app`)
## Estimated Total Effort: ~40 minutes
## Estimated Total Effort: ~30 minutes

8
docs/devops/vercel/ROADMAP_JARVISJR_WEB.md
View File

@ -29,15 +29,11 @@
- [ ] Run `pnpm install`
- [ ] Verify `pnpm build` passes
### Gap 2: Registry Access on Vercel (~15 min)
- [ ] Configure Vercel-compatible npm registry for `@bytelyst/*` scope
## Deployment Steps
### Step 1: Fix `file:` ref (~5 min)
### Step 2: Fix registry access (~15 min)
### Step 2: Fix registry access (~5 min)
### Step 3: Create Vercel Project (~5 min)
@ -58,6 +54,8 @@
### Step 6: Domain (~5 min)
3
- [ ] Add custom domain (e.g., `app.jarvisjr.app`)
## Estimated Total Effort: ~40 minutes

5
docs/devops/vercel/ROADMAP_LLM_LAB.md
View File

@ -44,9 +44,10 @@
+ ...(process.env.VERCEL ? {} : { output: 'standalone' }),
```
### Gap 3: Registry Access (~15 min)
### Gap 3: Registry Access (~5 min)
- [ ] Configure Vercel-compatible npm registry
- [ ] Update `.npmrc` to Azure VM Gitea URL
- [ ] Set `GITEA_NPM_TOKEN` as a Vercel environment variable
### Gap 4: Disable/stub server-side routes (~30 min)

11
docs/devops/vercel/ROADMAP_LOCALMEMGPT_WEB.md
View File

@ -41,9 +41,12 @@
- [ ] Update `next.config.ts`
### Gap 3: Registry Access (~15 min)
### Gap 3: Registry Access (~5 min)
- [ ] Configure Vercel-compatible npm registry for `@bytelyst/*` scope
Once Gitea is deployed to the Azure VM with a public HTTPS URL, update `.npmrc`.
- [ ] Update `.npmrc` to Azure VM Gitea URL
- [ ] Set `GITEA_NPM_TOKEN` as a Vercel environment variable
### Gap 4: Backend Connectivity (⚠️ Architecture concern)
@ -63,7 +66,7 @@ The web app is a thin client — all data comes from the local Fastify backend (
### Step 2: Fix output mode (~5 min)
### Step 3: Fix registry access (~15 min)
### Step 3: Fix registry access (~5 min)
### Step 4: Create Vercel Project (~5 min)
@ -90,4 +93,4 @@ The web app is a thin client — all data comes from the local Fastify backend (
- **SSE streaming:** Chat and compare features use SSE — same Vercel timeout constraints as ActionTrail.
- **No server-side routes:** The web app has no API routes — all logic is in the backend.
## Estimated Total Effort: ~45 minutes (technical), but architectural decision needed first
## Estimated Total Effort: ~35 minutes (technical), but architectural decision needed first

11
docs/devops/vercel/ROADMAP_MINDLYST_WEB.md
View File

@ -19,9 +19,12 @@
## Gaps to Fix
### Gap 1: Registry Access (~15 min)
### Gap 1: Registry Access (~5 min)
- [ ] Configure Vercel-compatible npm registry for `@bytelyst/*` scope
Once Gitea is deployed to the Azure VM with a public HTTPS URL, update `.npmrc`.
- [ ] Update `.npmrc` to Azure VM Gitea URL
- [ ] Set `GITEA_NPM_TOKEN` as a Vercel environment variable
### Gap 2: Nested Root Directory (~2 min)
@ -55,7 +58,7 @@ Uses `tsconfig.build.json` for typecheck (`tsc --noEmit -p tsconfig.build.json`)
## Deployment Steps
### Step 1: Fix registry access (~15 min)
### Step 1: Fix registry access (~5 min)
### Step 2: Create Vercel Project (~5 min)
@ -84,4 +87,4 @@ Uses `tsconfig.build.json` for typecheck (`tsc --noEmit -p tsconfig.build.json`)
- **Extraction service:** Several routes call extraction-service — must be publicly accessible.
- **No ISR/SSG:** All pages appear to be dynamic — no static optimization opportunities without refactoring.
## Estimated Total Effort: ~50 minutes
## Estimated Total Effort: ~40 minutes

8
docs/devops/vercel/ROADMAP_NOMGAP_WEB.md
View File

@ -46,17 +46,13 @@
- [ ] Update `next.config.ts` — conditional output mode
- [ ] Verify Docker build still works (`output: standalone` still active without `VERCEL`)
### Gap 3: Registry Access (~15 min)
- [ ] Configure Vercel-compatible npm registry for `@bytelyst/*` scope
## Deployment Steps
### Step 1: Fix `file:` ref (~5 min)
### Step 2: Fix output mode (~5 min)
### Step 3: Fix registry access (~15 min)
### Step 3: Fix registry access (~5 min)
### Step 4: Create Vercel Project (~5 min)
@ -77,6 +73,8 @@
### Step 7: Domain (~5 min)
4
- [ ] Add custom domain (e.g., `app.nomgap.app`)
## Estimated Total Effort: ~50 minutes

11
docs/devops/vercel/ROADMAP_NOTELETT_WEB.md
View File

@ -46,9 +46,12 @@
- [ ] Update `next.config.ts`
- [ ] Verify Docker build still works
### Gap 3: Registry Access (~15 min)
### Gap 3: Registry Access (~5 min)
- [ ] Configure Vercel-compatible npm registry for `@bytelyst/*` scope
Once Gitea is deployed to the Azure VM with a public HTTPS URL, update `.npmrc`.
- [ ] Update `.npmrc` to Azure VM Gitea URL
- [ ] Set `GITEA_NPM_TOKEN` as a Vercel environment variable
## Deployment Steps
@ -56,7 +59,7 @@
### Step 2: Fix output mode (~5 min)
### Step 3: Fix registry access (~15 min)
### Step 3: Fix registry access (~5 min)
### Step 4: Create Vercel Project (~5 min)
@ -80,4 +83,4 @@
- [ ] Add custom domain (e.g., `app.notelett.app`)
## Estimated Total Effort: ~50 minutes
## Estimated Total Effort: ~40 minutes

31
docs/devops/vercel/ROADMAP_USER_DASHBOARD.md
View File

@ -17,24 +17,12 @@
## Gaps to Fix
### Gap 1: Gitea Registry Access on Vercel (~15 min)
### Gap 1: Gitea Registry Access on Vercel (~5 min)
The `.npmrc` points to local Gitea (`http://localhost:3300`). Vercel can't reach this.
The `.npmrc` currently points to local Gitea (`http://localhost:3300`). Once Gitea is deployed to the Azure VM with a public HTTPS URL, this is a simple `.npmrc` update.
**Options:**
- **A) Publish to npm (public)** — best for production
- **B) Publish to GitHub Packages (private)** — requires `NODE_AUTH_TOKEN` on Vercel
- **C) Use Vercel's private npm support** — configure in project settings
- **D) Vendor tarballs** — use `scripts/docker-prep.sh` pattern to pack tarballs and reference locally
**Recommended:** Option B or C for initial deployment.
**Fix:**
- [ ] Publish `@bytelyst/*` packages to GitHub Packages or npm
- [ ] Update `.npmrc` to use the chosen registry (with Vercel env var for auth token)
- [ ] OR use `docker-prep.sh` to vendor tarballs and adjust `package.json`
- [ ] Update `.npmrc` to use Azure VM Gitea URL (e.g., `@bytelyst:registry=https://gitea.bytelyst.com/api/packages/YOUR_ORG/npm/`)
- [ ] Set `GITEA_NPM_TOKEN` as a Vercel environment variable
### Gap 2: Environment Variables (~10 min)
@ -50,11 +38,10 @@ The `.npmrc` points to local Gitea (`http://localhost:3300`). Vercel can't reach
## Deployment Steps
### Step 1: Fix Registry Access (~15 min)
### Step 1: Fix Registry Access (~5 min)
- [ ] Choose registry strategy (npm / GitHub Packages / Vercel private)
- [ ] Publish packages or configure vendoring
- [ ] Update `.npmrc` with Vercel-compatible registry URL
- [ ] Update `.npmrc` to Azure VM Gitea URL
- [ ] Set `GITEA_NPM_TOKEN` on Vercel
### Step 2: Create Vercel Project (~5 min)
@ -65,7 +52,7 @@ The `.npmrc` points to local Gitea (`http://localhost:3300`). Vercel can't reach
### Step 3: Configure Environment Variables (~10 min)
- [ ] Add all env vars listed above
- [ ] Set `NODE_AUTH_TOKEN` if using private registry
- [ ] Set `GITEA_NPM_TOKEN` for registry auth
### Step 4: Verify (~10 min)
@ -84,4 +71,4 @@ The `.npmrc` points to local Gitea (`http://localhost:3300`). Vercel can't reach
- **Stripe webhooks:** Stripe webhook URL must be updated to Vercel domain.
- **Platform-service connectivity:** PLATFORM_SERVICE_URL must point to a publicly accessible endpoint (not localhost).
## Estimated Total Effort: ~45 minutes
## Estimated Total Effort: ~35 minutes