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

docs: update documentation

Browse Source
This commit is contained in:
saravanakumardb1 2026-03-29 15:40:46 -07:00
parent 26739e36db
commit 64885dbc33
15 changed files with 1415 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

374
docs/devops/vercel/ECOSYSTEM_WEB_APPS_INVENTORY.md Normal file
View File

@ -0,0 +1,374 @@
# ByteLyst Ecosystem — Web Apps Inventory & Vercel Deployment Audit
> **Generated:** 2026-03-29
> **Scope:** All web applications across the ByteLyst ecosystem
> **Purpose:** Assess Vercel deployment readiness for every web surface
---
## Executive Summary
**14 web applications** discovered across 12 repositories. All are Next.js 16 except:
- **EffoRise** — Vite + React 19 SPA
- **Productivity Web** — Next.js 15 (standalone, no ecosystem deps)
### Readiness Scorecard
| # | App | Product | Framework | Vercel-Ready | Blockers |
| --- | ----------------- | ------------- | ----------------- | :----------: | ----------------------------------------------------------------------------------------- |
| 1 | Admin Dashboard | Platform | Next.js 16 | ✅ Yes | `workspace:*` deps (monorepo — Vercel handles) |
| 2 | Tracker Dashboard | Platform | Next.js 16 | ✅ Yes | `workspace:*` deps (monorepo — Vercel handles) |
| 3 | User Dashboard | LysnrAI | Next.js 16 | ⚠️ Partial | Server-side Cosmos/Stripe; env vars needed |
| 4 | ChronoMind Web | ChronoMind | Next.js 16 | 🔴 No | `file:` refs (design-tokens, ui); Serwist PWA |
| 5 | JarvisJr Web | JarvisJr | Next.js 16 | 🔴 No | `file:` ref (@bytelyst/ui) |
| 6 | NomGap Web | NomGap | Next.js 16 | 🔴 No | `file:` ref (@bytelyst/ui); hardcoded `output: standalone` |
| 7 | FlowMonk Web | FlowMonk | Next.js 16 | 🔴 No | `file:` ref (@bytelyst/ui) |
| 8 | NoteLett Web | NoteLett | Next.js 16 | 🔴 No | `file:` ref (@bytelyst/ui); hardcoded `output: standalone` |
| 9 | ActionTrail Web | ActionTrail | Next.js 16 | ⚠️ Partial | Hardcoded `output: standalone`; no TailwindCSS |
| 10 | MindLyst Web | MindLyst | Next.js 16 | ⚠️ Partial | Vercel-aware config; many `@bytelyst/*` registry deps |
| 11 | LocalMemGPT Web | LocalMemGPT | Next.js 16 | 🔴 No | `file:` ref (@bytelyst/ui); hardcoded `output: standalone` |
| 12 | LLM Lab Dashboard | Local LLM Lab | Next.js 16 | 🔴 No | `file:` refs (design-tokens, ui); hardcoded `output: standalone`; local Ollama dependency |
| 13 | EffoRise Client | EffoRise | Vite 7 + React 19 | ⚠️ Partial | SPA — needs Vite adapter or static deploy; API proxy to backend |
| 14 | Productivity Web | Standalone | Next.js 15 | ✅ Yes | Standalone app, no ecosystem deps, ready as-is |
### 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 |
---
## Detailed App Inventory
### 1. Admin Dashboard (`@bytelyst/admin-web`)
| Field | Value |
| --------------------- | ------------------------------------------------------------------------ |
| **Repo** | `learning_ai_common_plat` |
| **Path** | `dashboards/admin-web/` |
| **Framework** | Next.js 16.1.6, React 19.2.3 |
| **Styling** | TailwindCSS v4, shadcn/ui |
| **Port** | 3001 |
| **Build** | `next build --webpack` |
| **Output** | Vercel-aware (`process.env.VERCEL ? {} : { output: 'standalone' }`) |
| **@bytelyst/\* deps** | 13 packages via `workspace:*` (monorepo) |
| **Server-side** | Azure Cosmos DB, AKV, JWT (jose), bcryptjs |
| **Env vars** | COSMOS_ENDPOINT, COSMOS_KEY, JWT_SECRET, SEED_SECRET, AZURE_KEYVAULT_URL |
| **Dockerfile** | ✅ Yes |
| **Vercel status** | ✅ Ready — monorepo `workspace:*` resolved by Vercel's pnpm support |
### 2. Tracker Dashboard (`@bytelyst/tracker-web`)
| Field | Value |
| --------------------- | ------------------------------ |
| **Repo** | `learning_ai_common_plat` |
| **Path** | `dashboards/tracker-web/` |
| **Framework** | Next.js 16.1.6, React 19.2.3 |
| **Styling** | TailwindCSS v4 |
| **Port** | 3003 |
| **Build** | `next build --webpack` |
| **Output** | Vercel-aware |
| **@bytelyst/\* deps** | 6 packages via `workspace:*` |
| **Server-side** | AKV (instrumentation.ts) |
| **Env vars** | JWT_SECRET, AZURE_KEYVAULT_URL |
| **Dockerfile** | ✅ Yes |
| **Vercel status** | ✅ Ready |
### 3. User Dashboard (`user-dashboard-web`)
| Field | Value |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Repo** | `learning_voice_ai_agent` |
| **Path** | `user-dashboard-web/` |
| **Framework** | Next.js 16.1.6, React 19.2.3 |
| **Styling** | TailwindCSS v4, shadcn/ui |
| **Port** | 3002 |
| **Build** | `next build --webpack` |
| **Output** | Vercel-aware |
| **@bytelyst/\* deps** | 14 packages via Gitea registry (`^0.1.0`) |
| **Server-side** | Azure Cosmos DB, Stripe, JWT, bcryptjs |
| **Env vars** | COSMOS_ENDPOINT, COSMOS_KEY, JWT_SECRET, STRIPE_SECRET_KEY, STRIPE_PUBLISHABLE_KEY, PLATFORM_SERVICE_URL, ACTIONTRAIL_SERVICE_URL |
| **Dockerfile** | ✅ Yes |
| **Vercel status** | ⚠️ Partial — needs Gitea registry access during Vercel build |
### 4. ChronoMind Web
| Field | Value |
| --------------------- | ----------------------------------------------------------------------------- |
| **Repo** | `learning_ai_clock` |
| **Path** | `web/` |
| **Framework** | Next.js 16.1.6, React 19.2.3 |
| **Styling** | TailwindCSS v4 |
| **Port** | 3030 |
| **Build** | `next build --webpack` |
| **Output** | Vercel-aware |
| **@bytelyst/\* deps** | 10 packages — **2 via `file:` refs** (`design-tokens`, `ui`), 8 via Gitea |
| **Special** | Serwist PWA (service worker) |
| **Env vars** | NEXT_PUBLIC_PLATFORM_URL |
| **Dockerfile** | ✅ Yes |
| **Vercel status** | 🔴 Blocked — `file:` refs; Serwist service worker needs Vercel headers config |
### 5. JarvisJr Web (`jarvisjr-web`)
| Field | Value |
| --------------------- | ------------------------------------------------------ |
| **Repo** | `learning_ai_jarvis_jr` |
| **Path** | `web/` |
| **Framework** | Next.js 16.1.6, React 19.2.3 |
| **Styling** | TailwindCSS v4 |
| **Port** | 3035 |
| **Build** | `next build --webpack` |
| **Output** | Vercel-aware |
| **@bytelyst/\* deps** | 6 packages — **1 via `file:` ref** (`ui`), 5 via Gitea |
| **Env vars** | NEXT_PUBLIC_PLATFORM_URL, NEXT_PUBLIC_BACKEND_URL |
| **Dockerfile** | ✅ Yes |
| **Vercel status** | 🔴 Blocked — `file:` ref for @bytelyst/ui |
### 6. NomGap Web (`@nomgap/web`)
| Field | Value |
| --------------------- | -------------------------------------------------------- |
| **Repo** | `learning_ai_fastgap` |
| **Path** | `web/` |
| **Framework** | Next.js 16.1.6, React 19.2.0 |
| **Styling** | TailwindCSS v4 |
| **Port** | 3055 |
| **Build** | `next build --webpack` |
| **Output** | ❌ Hardcoded `output: "standalone"` |
| **@bytelyst/\* deps** | 14 packages — **1 via `file:` ref** (`ui`), 13 via Gitea |
| **Special** | `outputFileTracingRoot` set to parent dir |
| **Env vars** | NEXT_PUBLIC_PLATFORM_URL, NEXT_PUBLIC_BACKEND_URL |
| **Dockerfile** | ✅ Yes |
| **Vercel status** | 🔴 Blocked — `file:` ref; hardcoded standalone output |
### 7. FlowMonk Web (`@flowmonk/web`)
| Field | Value |
| --------------------- | ------------------------------------------------------ |
| **Repo** | `learning_ai_flowmonk` |
| **Path** | `web/` |
| **Framework** | Next.js 16.1.6, React 19.2.3 |
| **Styling** | No TailwindCSS (minimal CSS) |
| **Port** | 3040 |
| **Build** | `next build --webpack` |
| **Output** | Vercel-aware |
| **@bytelyst/\* deps** | 6 packages — **1 via `file:` ref** (`ui`), 5 via Gitea |
| **Special** | `typedRoutes: true`, `outputFileTracingRoot` set |
| **Env vars** | NEXT_PUBLIC_BACKEND_URL |
| **Dockerfile** | ✅ Yes |
| **Vercel status** | 🔴 Blocked — `file:` ref for @bytelyst/ui |
### 8. NoteLett Web (`@notelett/web`)
| Field | Value |
| --------------------- | ------------------------------------------------------- |
| **Repo** | `learning_ai_notes` |
| **Path** | `web/` |
| **Framework** | Next.js 16.1.6, React 19.2.0 |
| **Styling** | TailwindCSS v4 |
| **Port** | 3045 |
| **Build** | `next build --webpack` |
| **Output** | ❌ Hardcoded `output: "standalone"` |
| **@bytelyst/\* deps** | 10 packages — **1 via `file:` ref** (`ui`), 9 via Gitea |
| **Special** | `outputFileTracingRoot` set to parent dir |
| **Env vars** | NEXT_PUBLIC_PLATFORM_URL, NEXT_PUBLIC_BACKEND_URL |
| **Dockerfile** | ✅ Yes |
| **Vercel status** | 🔴 Blocked — `file:` ref; hardcoded standalone output |
### 9. ActionTrail Web (`@actiontrail/web`)
| Field | Value |
| --------------------- | --------------------------------------------------------- |
| **Repo** | `learning_ai_trails` |
| **Path** | `web/` |
| **Framework** | Next.js 16.1.6, React 19.2.3 |
| **Styling** | No TailwindCSS (minimal CSS) |
| **Port** | 3060 |
| **Build** | `next build --webpack` |
| **Output** | ❌ Hardcoded `output: 'standalone'` |
| **@bytelyst/\* deps** | 7 packages — all via Gitea registry ✅ |
| **Env vars** | NEXT_PUBLIC_BACKEND_URL |
| **Dockerfile** | ✅ Yes |
| **Vercel status** | ⚠️ Partial — hardcoded standalone output; no `file:` refs |
### 10. MindLyst Web (`mindlyst-web`)
| Field | Value |
| --------------------- | -------------------------------------------------------------------------------------------------- |
| **Repo** | `learning_multimodal_memory_agents` |
| **Path** | `mindlyst-native/web/` |
| **Framework** | Next.js ^16.0.0, React ^19.0.0 |
| **Styling** | Vanilla CSS (globals.css with `--ml-*` custom properties) |
| **Port** | 3050 |
| **Build** | `next build` (no `--webpack` flag) |
| **Output** | Vercel-aware |
| **@bytelyst/\* deps** | 10 packages — all via Gitea registry ✅ |
| **Server-side** | Azure Cosmos DB (direct `@azure/cosmos`) |
| **Special** | Nested path (`mindlyst-native/web/`); uses `tsconfig.build.json` |
| **Env vars** | COSMOS_ENDPOINT, COSMOS_KEY, MINDLYST_USER_ID, SEED_SECRET, OPENAI_API_KEY, EXTRACTION_SERVICE_URL |
| **Dockerfile** | ✅ Yes |
| **Vercel status** | ⚠️ Partial — needs Vercel root directory config for nested path; many server-side env vars |
### 11. LocalMemGPT Web (`@localmemgpt/web`)
| Field | Value |
| --------------------- | -------------------------------------------------------------------------------------- |
| **Repo** | `learning_ai_local_memory_gpt` |
| **Path** | `web/` |
| **Framework** | Next.js 16.1.6, React 19.2.3 |
| **Styling** | TailwindCSS v4 |
| **Port** | 3070 |
| **Build** | `next build --webpack` |
| **Output** | ❌ Hardcoded `output: 'standalone'` |
| **@bytelyst/\* deps** | 7 packages — **1 via `file:` ref** (`ui`), 6 via Gitea |
| **Env vars** | NEXT_PUBLIC_BACKEND_URL |
| **Dockerfile** | ✅ Yes |
| **Vercel status** | 🔴 Blocked — `file:` ref; hardcoded standalone; web is a thin client for local backend |
### 12. LLM Lab Dashboard
| Field | Value |
| --------------------- | ------------------------------------------------------------------------- |
| **Repo** | `learning_ai_local_llms` |
| **Path** | `dashboard/` |
| **Framework** | Next.js 16.1.6, React 19.2.3 |
| **Styling** | TailwindCSS v4 |
| **Port** | 3000 |
| **Build** | `next build` |
| **Output** | ❌ Hardcoded `output: 'standalone'` |
| **@bytelyst/\* deps** | 3 packages — **2 via `file:` refs** (`design-tokens`, `ui`), 1 via Gitea |
| **Special** | API routes proxy to local Ollama — **cannot run on Vercel** |
| **Env vars** | OLLAMA_HOST, NEXT_PUBLIC_LOCALMEMGPT_URL |
| **Dockerfile** | ✅ Yes (docker-compose.yml) |
| **Vercel status** | 🔴 Not viable — requires local Ollama instance; API routes are proxy-only |
### 13. EffoRise Client
| Field | Value |
| --------------------- | ---------------------------------------------------------------------------------------------------- |
| **Repo** | `learning_ai_efforise` |
| **Path** | `client/` (root vite.config.ts) |
| **Framework** | Vite 7.1.7, React 19.2.1 |
| **Styling** | TailwindCSS v4, shadcn/ui |
| **Port** | 3000 |
| **Build** | `vite build` → `dist/public/` |
| **@bytelyst/\* deps** | 8 packages via Gitea registry ✅ |
| **Special** | SPA with API proxy (`/api` → localhost:4020); `wouter` for routing |
| **Env vars** | (client-side only via Vite env) |
| **Dockerfile** | ✅ Yes |
| **Vercel status** | ⚠️ Partial — Vite SPA needs rewrites config for client-side routing; API proxy needs Vercel rewrites |
### 14. Productivity Web
| Field | Value |
| --------------------- | ----------------------------------------------- |
| **Repo** | `learning_ai_productivity_web` |
| **Path** | `/` (root) |
| **Framework** | Next.js 15.1.7, React ^19.0.0 |
| **Styling** | TailwindCSS v3 |
| **Port** | 3000 |
| **Build** | `next build` |
| **Output** | Default (no standalone) |
| **@bytelyst/\* deps** | None |
| **Env vars** | None |
| **Dockerfile** | ✅ Yes |
| **Vercel status** | ✅ Ready — zero external deps, standard Next.js |
---
## Common `file:` Reference Blockers
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.
| 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` |
**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.
---
## 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)
---
## Deployment Architecture on Vercel
### Recommended Vercel project structure:
```
Vercel Organization: ByteLyst
├── bytelyst-admin ← admin-web (common-plat monorepo)
├── bytelyst-tracker ← tracker-web (common-plat monorepo)
├── lysnrai-portal ← user-dashboard-web
├── chronomind-web ← learning_ai_clock/web
├── jarvisjr-web ← learning_ai_jarvis_jr/web
├── nomgap-web ← learning_ai_fastgap/web
├── flowmonk-web ← learning_ai_flowmonk/web
├── notelett-web ← learning_ai_notes/web
├── actiontrail-web ← learning_ai_trails/web
├── mindlyst-web ← learning_multimodal_memory_agents/mindlyst-native/web
├── localmemgpt-web ← learning_ai_local_memory_gpt/web
├── efforise-client ← learning_ai_efforise (Vite SPA)
├── productivity-tools ← learning_ai_productivity_web
└── (skip) llm-lab-dashboard ← NOT viable on Vercel (needs local Ollama)
```
### Monorepo apps (admin-web, tracker-web)
- Single Vercel project connected to `learning_ai_common_plat` repo
- Root directory set to `dashboards/admin-web/` or `dashboards/tracker-web/`
- `pnpm` detected automatically; `workspace:*` deps resolved
### 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`
---
## Per-App Roadmap Documents
Each app has a dedicated roadmap in this folder:
| App | Roadmap File |
| ------------------------ | -------------------------------------------------------------- |
| Admin Dashboard | [`ROADMAP_ADMIN_WEB.md`](./ROADMAP_ADMIN_WEB.md) |
| Tracker Dashboard | [`ROADMAP_TRACKER_WEB.md`](./ROADMAP_TRACKER_WEB.md) |
| User Dashboard (LysnrAI) | [`ROADMAP_USER_DASHBOARD.md`](./ROADMAP_USER_DASHBOARD.md) |
| ChronoMind Web | [`ROADMAP_CHRONOMIND_WEB.md`](./ROADMAP_CHRONOMIND_WEB.md) |
| JarvisJr Web | [`ROADMAP_JARVISJR_WEB.md`](./ROADMAP_JARVISJR_WEB.md) |
| NomGap Web | [`ROADMAP_NOMGAP_WEB.md`](./ROADMAP_NOMGAP_WEB.md) |
| FlowMonk Web | [`ROADMAP_FLOWMONK_WEB.md`](./ROADMAP_FLOWMONK_WEB.md) |
| NoteLett Web | [`ROADMAP_NOTELETT_WEB.md`](./ROADMAP_NOTELETT_WEB.md) |
| ActionTrail Web | [`ROADMAP_ACTIONTRAIL_WEB.md`](./ROADMAP_ACTIONTRAIL_WEB.md) |
| MindLyst Web | [`ROADMAP_MINDLYST_WEB.md`](./ROADMAP_MINDLYST_WEB.md) |
| LocalMemGPT Web | [`ROADMAP_LOCALMEMGPT_WEB.md`](./ROADMAP_LOCALMEMGPT_WEB.md) |
| LLM Lab Dashboard | [`ROADMAP_LLM_LAB.md`](./ROADMAP_LLM_LAB.md) |
| EffoRise Client | [`ROADMAP_EFFORISE.md`](./ROADMAP_EFFORISE.md) |
| Productivity Web | [`ROADMAP_PRODUCTIVITY_WEB.md`](./ROADMAP_PRODUCTIVITY_WEB.md) |

71
docs/devops/vercel/ROADMAP_ACTIONTRAIL_WEB.md Normal file
View File

@ -0,0 +1,71 @@
# ActionTrail Web — Vercel Deployment Roadmap
> **App:** `@actiontrail/web`
> **Repo:** `learning_ai_trails` → `web/`
> **Status:** ⚠️ Partial — hardcoded standalone output
---
## Current State
- **Framework:** Next.js 16.1.6, React 19.2.3
- **Output:** ❌ Hardcoded `output: 'standalone'`
- **Styling:** No TailwindCSS (minimal CSS)
- **Dependencies:** 7 `@bytelyst/*` — **all via Gitea registry** ✅ (no `file:` refs)
- **Build:** `next build --webpack`
- **Client-side focused** — timeline, approvals, agents, insights, traces, welcome, settings
- **SSE support** — real-time toast notifications via EventSource
## Gaps to Fix
### Gap 1: Make output Vercel-aware (~5 min)
**File:** `web/next.config.ts`
```diff
- output: 'standalone',
+ ...(process.env.VERCEL ? {} : { output: 'standalone' }),
```
- [ ] Update `next.config.ts`
- [ ] Verify Docker build still works
### Gap 2: Registry Access (~15 min)
- [ ] Configure Vercel-compatible npm registry for `@bytelyst/*` scope
### Gap 3 (optional): SSE Compatibility
Vercel serverless functions have a 25-second timeout (Hobby) / 300s (Pro). SSE streams via `GET /api/events/stream` will be cut short.
- [ ] Consider using Vercel's Edge Runtime for SSE endpoints (longer timeout)
- [ ] Or switch to polling on Vercel, keep SSE for Docker/self-hosted
## Deployment Steps
### Step 1: Fix output mode (~5 min)
### Step 2: Fix registry access (~15 min)
### Step 3: Create Vercel Project (~5 min)
- [ ] Connect `learning_ai_trails` repo
- [ ] Set **Root Directory** to `web`
- [ ] Framework preset: **Next.js**
### Step 4: Environment Variables (~5 min)
- [ ] `NEXT_PUBLIC_BACKEND_URL` — ActionTrail backend endpoint (port 4018)
### Step 5: Verify (~10 min)
- [ ] Test timeline page with action list
- [ ] Test approval queue
- [ ] Test agent card grid
- [ ] Verify SSE toast notifications work (or gracefully degrade)
### Step 6: Domain (~5 min)
- [ ] Add custom domain (e.g., `app.actiontrail.dev`)
## Estimated Total Effort: ~45 minutes

56
docs/devops/vercel/ROADMAP_ADMIN_WEB.md Normal file
View File

@ -0,0 +1,56 @@
# Admin Dashboard — Vercel Deployment Roadmap
> **App:** `@bytelyst/admin-web`
> **Repo:** `learning_ai_common_plat` → `dashboards/admin-web/`
> **Status:** ✅ Ready
---
## Current State
- **Framework:** Next.js 16.1.6, React 19.2.3, TailwindCSS v4, shadcn/ui
- **Output:** Vercel-aware (`process.env.VERCEL ? {} : { output: 'standalone' }`)
- **Dependencies:** 13 `@bytelyst/*` packages via `workspace:*` (monorepo — Vercel resolves automatically)
- **Build:** `next build --webpack`
- **Server-side:** Azure Cosmos DB, AKV, JWT, bcryptjs
- **No `file:` references** — all deps are workspace or npm
## Deployment Steps
### Step 1: Create Vercel Project (~5 min)
- [ ] Connect `learning_ai_common_plat` repo to Vercel
- [ ] Set **Root Directory** to `dashboards/admin-web`
- [ ] Framework preset: **Next.js**
- [ ] Build command: `pnpm build` (auto-detected)
- [ ] Output directory: `.next` (auto-detected)
### Step 2: Configure Environment Variables (~10 min)
- [ ] `COSMOS_ENDPOINT` — Azure Cosmos DB endpoint
- [ ] `COSMOS_KEY` — Azure Cosmos DB key
- [ ] `JWT_SECRET` — JWT signing secret
- [ ] `SEED_SECRET` — Seed endpoint secret
- [ ] `AZURE_KEYVAULT_URL` — Azure Key Vault URL (optional — for AKV secret resolution)
- [ ] `NODE_ENV` = `production`
### Step 3: Verify Build (~5 min)
- [ ] Trigger first deploy
- [ ] Verify security headers are applied (CSP, HSTS, X-Frame-Options)
- [ ] Test login flow with JWT auth
- [ ] Verify Cosmos DB connectivity from Vercel serverless functions
### Step 4: Domain Configuration (~5 min)
- [ ] Add custom domain (e.g., `admin.bytelyst.com`)
- [ ] Verify SSL certificate auto-provisioning
## Risks & Notes
- **Cosmos DB latency:** Vercel serverless functions run in specific regions. Ensure Cosmos DB region matches Vercel deployment region (recommend `iad1` for eastus).
- **Cold starts:** Server-side pages that hit Cosmos will have cold start latency (~1-2s). Consider ISR for static-friendly pages.
- **CSP headers:** Current CSP allows `connect-src` to `*.documents.azure.com` — correct for Cosmos.
- **Webpack flag:** Build uses `--webpack` — Vercel respects this via the build command override.
## Estimated Total Effort: ~25 minutes

87
docs/devops/vercel/ROADMAP_CHRONOMIND_WEB.md Normal file
View File

@ -0,0 +1,87 @@
# 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 (~15 min)
Same as all product repos — `.npmrc` points to local Gitea.
- [ ] Choose registry strategy (npm / GitHub Packages / vendored tarballs)
- [ ] Update `.npmrc` for Vercel-compatible registry
### 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 (~15 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: ~60 minutes

104
docs/devops/vercel/ROADMAP_EFFORISE.md Normal file
View File

@ -0,0 +1,104 @@
# 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` env var for API base URL
### 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 (~15 min)
- [ ] Configure Vercel-compatible npm registry for `@bytelyst/*` scope
### 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 (~15 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: ~50 minutes

70
docs/devops/vercel/ROADMAP_FLOWMONK_WEB.md Normal file
View File

@ -0,0 +1,70 @@
# FlowMonk Web — Vercel Deployment Roadmap
> **App:** `@flowmonk/web`
> **Repo:** `learning_ai_flowmonk` → `web/`
> **Status:** 🔴 Blocked — `file:` ref
---
## Current State
- **Framework:** Next.js 16.1.6, React 19.2.3
- **Output:** Vercel-aware
- **Styling:** No TailwindCSS (minimal inline/module CSS)
- **Dependencies:** 6 `@bytelyst/*` — **1 via `file:` ref** (`ui`), 5 via Gitea (pinned versions like `0.1.0` and `0.1.1`)
- **Build:** `next build --webpack`
- **Special:** `typedRoutes: true`, `outputFileTracingRoot` set (harmless on Vercel)
- **Client-side focused** — zones, flows, tasks, schedule, recommendations
## Gaps to Fix
### Gap 1: Convert `file:` ref (~5 min)
**File:** `web/package.json`
```diff
- "@bytelyst/ui": "file:../../learning_ai_common_plat/packages/ui",
+ "@bytelyst/ui": "^0.1.0",
```
- [ ] Update `package.json`
- [ ] Run `pnpm install`
- [ ] Verify build
### Gap 2: Registry Access (~15 min)
- [ ] Configure Vercel-compatible npm registry for `@bytelyst/*` scope
### Gap 3 (optional): Add TailwindCSS
Not a deployment blocker, but the app lacks TailwindCSS unlike all other ecosystem web apps.
- [ ] (Deferred) Add TailwindCSS v4 for consistency
## Deployment Steps
### Step 1: Fix `file:` ref (~5 min)
### Step 2: Fix registry access (~15 min)
### Step 3: Create Vercel Project (~5 min)
- [ ] Connect `learning_ai_flowmonk` repo
- [ ] Set **Root Directory** to `web`
- [ ] Framework preset: **Next.js**
### Step 4: Environment Variables (~5 min)
- [ ] `NEXT_PUBLIC_BACKEND_URL` — FlowMonk backend endpoint (port 4017)
### Step 5: Verify (~5 min)
- [ ] Test dashboard loads
- [ ] Test zone/flow/task CRUD pages
- [ ] Test schedule generation view
### Step 6: Domain (~5 min)
- [ ] Add custom domain (e.g., `app.flowmonk.app`)
## Estimated Total Effort: ~40 minutes

63
docs/devops/vercel/ROADMAP_JARVISJR_WEB.md Normal file
View File

@ -0,0 +1,63 @@
# JarvisJr Web — Vercel Deployment Roadmap
> **App:** `jarvisjr-web`
> **Repo:** `learning_ai_jarvis_jr` → `web/`
> **Status:** 🔴 Blocked — `file:` ref
---
## Current State
- **Framework:** Next.js 16.1.6, React 19.2.3, TailwindCSS v4
- **Output:** Vercel-aware
- **Dependencies:** 6 `@bytelyst/*` — **1 via `file:` ref** (`ui`), 5 via Gitea
- **Build:** `next build --webpack`
- **Client-side focused** — dashboard, history, progress, store, settings pages
## Gaps to Fix
### Gap 1: Convert `file:` ref to registry ref (~5 min)
**File:** `web/package.json`
```diff
- "@bytelyst/ui": "file:../../learning_ai_common_plat/packages/ui",
+ "@bytelyst/ui": "^0.1.0",
```
- [ ] Update `package.json`
- [ ] 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 3: Create Vercel Project (~5 min)
- [ ] Connect `learning_ai_jarvis_jr` repo
- [ ] Set **Root Directory** to `web`
- [ ] Framework preset: **Next.js**
### Step 4: Environment Variables (~5 min)
- [ ] `NEXT_PUBLIC_PLATFORM_URL` — platform-service endpoint
- [ ] `NEXT_PUBLIC_BACKEND_URL` — JarvisJr backend endpoint (port 4012)
### Step 5: Verify (~5 min)
- [ ] Test dashboard page loads
- [ ] Verify agent card grid renders
- [ ] Test sidebar navigation
### Step 6: Domain (~5 min)
- [ ] Add custom domain (e.g., `app.jarvisjr.app`)
## Estimated Total Effort: ~40 minutes

63
docs/devops/vercel/ROADMAP_LLM_LAB.md Normal file
View File

@ -0,0 +1,63 @@
# LLM Lab Dashboard — Vercel Deployment Roadmap
> **App:** LLM Lab Dashboard (Mission Control)
> **Repo:** `learning_ai_local_llms` → `dashboard/`
> **Status:** 🔴 Not viable on Vercel — requires local Ollama
---
## Current State
- **Framework:** Next.js 16.1.6, React 19.2.3, TailwindCSS v4
- **Output:** ❌ Hardcoded `output: 'standalone'`
- **Dependencies:** 3 `@bytelyst/*` — **2 via `file:` refs** (`design-tokens`, `ui`), 1 via Gitea
- **Build:** `next build`
- **Architecture:** Dashboard with API routes that **proxy to local Ollama** (`/api/ollama/*`)
- **System info routes:** Read hardware stats via `vm_stat`, `top`, `system_profiler` — macOS only
## Why Vercel Won't Work
1. **Ollama dependency:** API routes proxy to Ollama (`OLLAMA_HOST`). Ollama must run on the same machine or reachable network. Vercel serverless functions can't access a local Ollama instance.
2. **System commands:** Routes call macOS system commands (`vm_stat`, `system_profiler`) which don't exist on Vercel's Linux runtime.
3. **Whisper integration:** TTS/STT routes depend on local `whisper-cpp` binary.
4. **Purpose:** This is a **local machine management tool**, not a cloud app.
## If Deployment Is Still Desired (Static Shell Only)
### Gap 1: Convert `file:` refs (~5 min)
**File:** `dashboard/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",
```
### Gap 2: Make output Vercel-aware (~5 min)
**File:** `dashboard/next.config.ts`
```diff
- output: 'standalone',
+ ...(process.env.VERCEL ? {} : { output: 'standalone' }),
```
### Gap 3: Registry Access (~15 min)
- [ ] Configure Vercel-compatible npm registry
### Gap 4: Disable/stub server-side routes (~30 min)
- [ ] Stub out system info routes (return mock data or error)
- [ ] Make Ollama proxy routes return "configure OLLAMA_HOST" message
- [ ] Gate system commands behind runtime check
## Recommendation
**Do NOT deploy to Vercel.** This app is purpose-built for local/Docker use. The API routes are the core value and none work in a serverless environment.
**Alternative:** Keep using Docker Compose or the `scripts/start-dashboard.sh` launcher.
## Estimated Total Effort: Not recommended. If forced: ~60 minutes for static shell only.

93
docs/devops/vercel/ROADMAP_LOCALMEMGPT_WEB.md Normal file
View File

@ -0,0 +1,93 @@
# LocalMemGPT Web — Vercel Deployment Roadmap
> **App:** `@localmemgpt/web`
> **Repo:** `learning_ai_local_memory_gpt` → `web/`
> **Status:** 🔴 Blocked — `file:` ref + hardcoded standalone + local-first architecture
---
## Current State
- **Framework:** Next.js 16.1.6, React 19.2.3, TailwindCSS v4
- **Output:** ❌ Hardcoded `output: 'standalone'`
- **Dependencies:** 7 `@bytelyst/*` — **1 via `file:` ref** (`ui`), 6 via Gitea
- **Build:** `next build --webpack`
- **Architecture:** Thin web client that connects to local Fastify backend (port 4019)
- **Backend dependency:** SQLite + Ollama — both local-only, NOT cloud-compatible
## Gaps to Fix
### Gap 1: Convert `file:` ref (~5 min)
**File:** `web/package.json`
```diff
- "@bytelyst/ui": "file:../../learning_ai_common_plat/packages/ui",
+ "@bytelyst/ui": "^0.1.0",
```
- [ ] Update `package.json`
- [ ] Run `pnpm install`
- [ ] Verify build
### Gap 2: Make output Vercel-aware (~5 min)
**File:** `web/next.config.ts`
```diff
- output: 'standalone',
+ ...(process.env.VERCEL ? {} : { output: 'standalone' }),
```
- [ ] Update `next.config.ts`
### Gap 3: Registry Access (~15 min)
- [ ] Configure Vercel-compatible npm registry for `@bytelyst/*` scope
### Gap 4: Backend Connectivity (⚠️ Architecture concern)
The web app is a thin client — all data comes from the local Fastify backend (SQLite + Ollama). On Vercel, there's no backend to connect to unless:
**Options:**
- **A) Deploy web as static shell** — Vercel serves the UI, user configures `NEXT_PUBLIC_BACKEND_URL` to point to their self-hosted backend (e.g., home server, VPS)
- **B) Skip Vercel** — this is inherently a local-first app, Docker/self-hosted is the natural fit
- **C) Hybrid** — deploy landing page + docs on Vercel, keep app itself self-hosted
**Recommended:** Option A — deploy as configurable shell. Users point it at their own backend.
## Deployment Steps
### Step 1: Fix `file:` ref (~5 min)
### Step 2: Fix output mode (~5 min)
### Step 3: Fix registry access (~15 min)
### Step 4: Create Vercel Project (~5 min)
- [ ] Connect `learning_ai_local_memory_gpt` repo
- [ ] Set **Root Directory** to `web`
- [ ] Framework preset: **Next.js**
### Step 5: Environment Variables (~5 min)
- [ ] `NEXT_PUBLIC_BACKEND_URL` — user's self-hosted backend URL
### Step 6: Verify (~5 min)
- [ ] Verify app loads with "no backend" graceful error
- [ ] Test with a publicly accessible backend URL
### Step 7: Domain (~5 min)
- [ ] Add custom domain (e.g., `app.localmemgpt.app`)
## Risks
- **Local-first tension:** This app is designed to run locally. Vercel deployment is useful only as a hosted shell pointing to a user's 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

87
docs/devops/vercel/ROADMAP_MINDLYST_WEB.md Normal file
View File

@ -0,0 +1,87 @@
# MindLyst Web — Vercel Deployment Roadmap
> **App:** `mindlyst-web`
> **Repo:** `learning_multimodal_memory_agents` → `mindlyst-native/web/`
> **Status:** ⚠️ Partial — nested path + server-side Cosmos + many env vars
---
## Current State
- **Framework:** Next.js ^16.0.0, React ^19.0.0
- **Output:** Vercel-aware
- **Styling:** Vanilla CSS (`globals.css` with `--ml-*` custom properties) — no TailwindCSS
- **Dependencies:** 10 `@bytelyst/*` — **all via Gitea registry** ✅ (no `file:` refs)
- **Build:** `next build` (no `--webpack` flag)
- **Server-side:** Azure Cosmos DB (direct `@azure/cosmos`), OpenAI API, extraction-service calls
- **Special:** Nested repo path (`mindlyst-native/web/`), uses `tsconfig.build.json`
- **33 API routes** — triage, memory, brains, streaks, reflections, etc.
## Gaps to Fix
### Gap 1: Registry Access (~15 min)
- [ ] Configure Vercel-compatible npm registry for `@bytelyst/*` scope
### Gap 2: Nested Root Directory (~2 min)
Vercel needs to know the app lives at `mindlyst-native/web/`, not the repo root.
- [ ] Set **Root Directory** in Vercel project settings to `mindlyst-native/web`
### Gap 3: Server-Side Dependencies (~10 min)
The app has 33 API routes that directly query Azure Cosmos DB. All require server-side env vars.
- [ ] Configure all required env vars on Vercel (see list below)
- [ ] Ensure Cosmos DB firewall allows Vercel's IP ranges (or use `0.0.0.0/0` for serverless)
### Gap 4: TypeScript Build Config (~5 min)
Uses `tsconfig.build.json` for typecheck (`tsc --noEmit -p tsconfig.build.json`). Vercel's default `next build` should work without this, but verify.
- [ ] Confirm `next build` succeeds without explicit tsconfig reference
## Environment Variables (~10 min)
- [ ] `COSMOS_ENDPOINT` — Azure Cosmos DB endpoint
- [ ] `COSMOS_KEY` — Azure Cosmos DB key
- [ ] `MINDLYST_USER_ID` — Default user ID
- [ ] `SEED_SECRET` — Seed endpoint secret
- [ ] `OPENAI_API_KEY` — OpenAI API key (for triage)
- [ ] `EXTRACTION_SERVICE_URL` — extraction-service endpoint (port 4005)
- [ ] `PLATFORM_SERVICE_URL` — platform-service endpoint (port 4003)
- [ ] `NEXT_PUBLIC_PLATFORM_URL` — client-side platform URL
## Deployment Steps
### Step 1: Fix registry access (~15 min)
### Step 2: Create Vercel Project (~5 min)
- [ ] Connect `learning_multimodal_memory_agents` repo
- [ ] Set **Root Directory** to `mindlyst-native/web`
- [ ] Framework preset: **Next.js**
### Step 3: Configure Environment Variables (~10 min)
### Step 4: Verify (~15 min)
- [ ] Test dashboard loads (3-pane layout)
- [ ] Test brain packs page
- [ ] Test triage API (needs OpenAI key)
- [ ] Test memory creation flow
- [ ] Verify Cosmos connectivity
### Step 5: Domain (~5 min)
- [ ] Add custom domain (e.g., `app.mindlyst.com`)
## Risks
- **Cosmos DB latency:** 33 server-side API routes all hit Cosmos. Cold starts will be noticeable.
- **OpenAI dependency:** Triage API calls OpenAI — needs API key and will incur costs.
- **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

82
docs/devops/vercel/ROADMAP_NOMGAP_WEB.md Normal file
View File

@ -0,0 +1,82 @@
# NomGap Web — Vercel Deployment Roadmap
> **App:** `@nomgap/web`
> **Repo:** `learning_ai_fastgap` → `web/`
> **Status:** 🔴 Blocked — `file:` ref + hardcoded standalone output
---
## Current State
- **Framework:** Next.js 16.1.6, React 19.2.0, TailwindCSS v4
- **Output:** ❌ Hardcoded `output: "standalone"`
- **Dependencies:** 14 `@bytelyst/*` — **1 via `file:` ref** (`ui`), 13 via Gitea
- **Build:** `next build --webpack`
- **Special:** `outputFileTracingRoot` set to parent dir (Docker optimization)
- **Rich client** — body visualization, fasting timer, protocols, social, simulator
## Gaps to Fix
### Gap 1: Convert `file:` ref (~5 min)
**File:** `web/package.json`
```diff
- "@bytelyst/ui": "file:../../learning_ai_common_plat/packages/ui",
+ "@bytelyst/ui": "^0.1.0",
```
- [ ] Update `package.json`
- [ ] Run `pnpm install`
- [ ] Verify build
### Gap 2: Make output Vercel-aware (~5 min)
**File:** `web/next.config.ts`
```diff
- output: "standalone",
- outputFileTracingRoot: path.join(process.cwd(), ".."),
+ ...(process.env.VERCEL ? {} : {
+ output: "standalone",
+ outputFileTracingRoot: path.join(process.cwd(), ".."),
+ }),
```
- [ ] 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 4: Create Vercel Project (~5 min)
- [ ] Connect `learning_ai_fastgap` repo
- [ ] Set **Root Directory** to `web`
- [ ] Framework preset: **Next.js**
### Step 5: Environment Variables (~5 min)
- [ ] `NEXT_PUBLIC_PLATFORM_URL` — platform-service endpoint
- [ ] `NEXT_PUBLIC_BACKEND_URL` — NomGap backend endpoint (port 4013)
### Step 6: Verify (~10 min)
- [ ] Test dashboard with body visualization canvas
- [ ] Test fasting timer flow
- [ ] Verify protocol listing
### Step 7: Domain (~5 min)
- [ ] Add custom domain (e.g., `app.nomgap.app`)
## Estimated Total Effort: ~50 minutes

83
docs/devops/vercel/ROADMAP_NOTELETT_WEB.md Normal file
View File

@ -0,0 +1,83 @@
# NoteLett Web — Vercel Deployment Roadmap
> **App:** `@notelett/web`
> **Repo:** `learning_ai_notes` → `web/`
> **Status:** 🔴 Blocked — `file:` ref + hardcoded standalone output
---
## Current State
- **Framework:** Next.js 16.1.6, React 19.2.0, TailwindCSS v4
- **Output:** ❌ Hardcoded `output: "standalone"`
- **Dependencies:** 10 `@bytelyst/*` — **1 via `file:` ref** (`ui`), 9 via Gitea
- **Build:** `next build --webpack`
- **Special:** `outputFileTracingRoot` set to parent dir
- **Rich client** — dashboard, workspaces, search, reviews, note editor
## Gaps to Fix
### Gap 1: Convert `file:` ref (~5 min)
**File:** `web/package.json`
```diff
- "@bytelyst/ui": "file:../../learning_ai_common_plat/packages/ui",
+ "@bytelyst/ui": "^0.1.0",
```
- [ ] Update `package.json`
- [ ] Run `pnpm install`
- [ ] Verify build
### Gap 2: Make output Vercel-aware (~5 min)
**File:** `web/next.config.ts`
```diff
- output: "standalone",
- outputFileTracingRoot: path.join(process.cwd(), ".."),
+ ...(process.env.VERCEL ? {} : {
+ output: "standalone",
+ outputFileTracingRoot: path.join(process.cwd(), ".."),
+ }),
```
- [ ] Update `next.config.ts`
- [ ] Verify Docker build still works
### 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 4: Create Vercel Project (~5 min)
- [ ] Connect `learning_ai_notes` repo
- [ ] Set **Root Directory** to `web`
- [ ] Framework preset: **Next.js**
### Step 5: Environment Variables (~5 min)
- [ ] `NEXT_PUBLIC_PLATFORM_URL` — platform-service endpoint
- [ ] `NEXT_PUBLIC_BACKEND_URL` — NoteLett backend endpoint (port 4016)
### Step 6: Verify (~10 min)
- [ ] Test dashboard with metrics
- [ ] Test note creation + editor
- [ ] Test workspace filtering
- [ ] Test approval queue / agent timeline
### Step 7: Domain (~5 min)
- [ ] Add custom domain (e.g., `app.notelett.app`)
## Estimated Total Effort: ~50 minutes

45
docs/devops/vercel/ROADMAP_PRODUCTIVITY_WEB.md Normal file
View File

@ -0,0 +1,45 @@
# Productivity Web — Vercel Deployment Roadmap
> **App:** `productivity-web`
> **Repo:** `learning_ai_productivity_web` → root
> **Status:** ✅ Ready — zero ecosystem deps, standard Next.js
---
## Current State
- **Framework:** Next.js 15.1.7, React ^19.0.0, TailwindCSS v3
- **Output:** Default (no `output` config — Vercel's default mode)
- **Dependencies:** Zero `@bytelyst/*` packages — completely standalone
- **Build:** `next build`
- **Styling:** TailwindCSS v3 (older than ecosystem v4)
- **No env vars required**
- **No server-side APIs** — pure static/client-side tool collection
## Deployment Steps
### Step 1: Create Vercel Project (~5 min)
- [ ] Connect `learning_ai_productivity_web` repo
- [ ] Root directory: `/` (default)
- [ ] Framework preset: **Next.js** (auto-detected)
- [ ] Build command: auto (`next build`)
- [ ] No environment variables needed
### Step 2: Verify (~5 min)
- [ ] Test landing page loads
- [ ] Test tool navigation (`/tools/*`)
- [ ] Test manage page (`/manage`)
### Step 3: Domain (~5 min)
- [ ] Add custom domain if desired
## Notes
- **Simplest deploy in the ecosystem.** No ecosystem dependencies, no env vars, no server-side logic.
- **Next.js 15** — one version behind ecosystem standard (16). Not a Vercel blocker.
- **TailwindCSS v3** — works fine on Vercel, just older than ecosystem v4 standard.
## Estimated Total Effort: ~15 minutes

50
docs/devops/vercel/ROADMAP_TRACKER_WEB.md Normal file
View File

@ -0,0 +1,50 @@
# Tracker Dashboard — Vercel Deployment Roadmap
> **App:** `@bytelyst/tracker-web`
> **Repo:** `learning_ai_common_plat` → `dashboards/tracker-web/`
> **Status:** ✅ Ready
---
## Current State
- **Framework:** Next.js 16.1.6, React 19.2.3, TailwindCSS v4
- **Output:** Vercel-aware (`process.env.VERCEL ? {} : { output: 'standalone' }`)
- **Dependencies:** 6 `@bytelyst/*` packages via `workspace:*` (monorepo)
- **Build:** `next build --webpack`
- **Server-side:** AKV secret resolution only (via instrumentation.ts)
- **No `file:` references**
## Deployment Steps
### Step 1: Create Vercel Project (~5 min)
- [ ] Connect `learning_ai_common_plat` repo to Vercel (or reuse org if admin-web already connected)
- [ ] Set **Root Directory** to `dashboards/tracker-web`
- [ ] Framework preset: **Next.js**
### Step 2: Configure Environment Variables (~5 min)
- [ ] `JWT_SECRET` — JWT signing secret
- [ ] `AZURE_KEYVAULT_URL` — Azure Key Vault URL (optional)
- [ ] `PLATFORM_SERVICE_URL` — URL of platform-service API
- [ ] `NODE_ENV` = `production`
### Step 3: Verify Build (~5 min)
- [ ] Trigger deploy
- [ ] Verify public roadmap page loads (`/roadmap`)
- [ ] Test item submission and voting
- [ ] Verify security headers
### Step 4: Domain Configuration (~5 min)
- [ ] Add custom domain (e.g., `tracker.bytelyst.com`)
## Notes
- **pretest script:** Has a `pretest` script that builds workspace deps — Vercel won't run this, but `pnpm build` in the root handles workspace resolution.
- **Lighter footprint:** Fewer server-side deps than admin-web. Mostly a client-side app that calls platform-service APIs.
- **Bundle size:** Has `bundlesize` checks configured — good for monitoring after deploy.
## Estimated Total Effort: ~20 minutes

87
docs/devops/vercel/ROADMAP_USER_DASHBOARD.md Normal file
View File

@ -0,0 +1,87 @@
# User Dashboard (LysnrAI) — Vercel Deployment Roadmap
> **App:** `user-dashboard-web`
> **Repo:** `learning_voice_ai_agent` → `user-dashboard-web/`
> **Status:** ⚠️ Partial — needs Gitea registry access + env vars
---
## Current State
- **Framework:** Next.js 16.1.6, React 19.2.3, TailwindCSS v4, shadcn/ui
- **Output:** Vercel-aware (`process.env.VERCEL ? {} : { output: 'standalone' }`)
- **Dependencies:** 14 `@bytelyst/*` packages via Gitea registry (`^0.1.0`)
- **Build:** `next build --webpack`
- **Server-side:** Azure Cosmos DB, Stripe, JWT, bcryptjs
- **No `file:` references** ✅
## Gaps to Fix
### Gap 1: Gitea Registry Access on Vercel (~15 min)
The `.npmrc` points to local Gitea (`http://localhost:3300`). Vercel can't reach this.
**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`
### Gap 2: Environment Variables (~10 min)
- [ ] `COSMOS_ENDPOINT` — Azure Cosmos DB endpoint
- [ ] `COSMOS_KEY` — Azure Cosmos DB key
- [ ] `JWT_SECRET` — JWT signing secret
- [ ] `STRIPE_SECRET_KEY` — Stripe server-side key
- [ ] `STRIPE_PUBLISHABLE_KEY` — Stripe public key
- [ ] `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` — Client-side Stripe key
- [ ] `PLATFORM_SERVICE_URL` — platform-service endpoint
- [ ] `ACTIONTRAIL_SERVICE_URL` — ActionTrail backend
- [ ] `AZURE_KEYVAULT_URL` — AKV (optional)
## Deployment Steps
### Step 1: Fix Registry Access (~15 min)
- [ ] Choose registry strategy (npm / GitHub Packages / Vercel private)
- [ ] Publish packages or configure vendoring
- [ ] Update `.npmrc` with Vercel-compatible registry URL
### Step 2: Create Vercel Project (~5 min)
- [ ] Connect `learning_voice_ai_agent` repo
- [ ] Set **Root Directory** to `user-dashboard-web`
- [ ] Framework preset: **Next.js**
### Step 3: Configure Environment Variables (~10 min)
- [ ] Add all env vars listed above
- [ ] Set `NODE_AUTH_TOKEN` if using private registry
### Step 4: Verify (~10 min)
- [ ] Trigger deploy
- [ ] Test login, dashboard, billing flow
- [ ] Verify Stripe integration
- [ ] Verify Cosmos connectivity
### Step 5: Domain (~5 min)
- [ ] Add custom domain (e.g., `portal.lysnrai.com`)
## Risks
- **Cosmos latency:** Same region concern as admin-web.
- **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