create-lego-one 2.0.12 → 2.0.13

package/template/docs/framework/research/07-deployment.md

@@ -0,0 +1,629 @@
+# Deployment: Host and Sub-Apps
+
+**Project:** Lego-One (Modern.js SaaS OS)
+**Document:** 07 - Deployment Strategy
+**Status:** Research Phase
+
+## Executive Summary
+
+This document explains how to deploy the Lego-One application to production. **Plugins are bundled into the host** for single-server deployment, while remaining separate during development for independent workflow.
+
+---
+
+## 1. Deployment Architecture
+
+### 1.1 Key Principle
+
+**Development = Separate servers │ Production = Single server (plugins bundled)**
+
+### 1.2 Production Runtime Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                          Production Environment                         │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                           │
+│  ┌─────────────────────────────────────────────────────────────────────┐  │
+│  │                      CDN / Edge Layer                                │  │
+│  │                  (Vercel Edge, CloudFront)                          │  │
+│  └─────────────────────────────────────────────────────────────────────┘  │
+│                                    │                                      │
+│                                    ▼                                      │
+│  ┌─────────────────────────────────────────────────────────────────────┐  │
+│  │                   Application Server (Single)                        │  │
+│  │  ┌───────────────────────────────────────────────────────────────┐  │  │
+│  │  │  host/dist/                                                  │  │  │
+│  │  │  ├── index.html                                              │  │  │
+│  │  │  ├── static/js/                                               │  │  │
+│  │  │  │   ├── main-[hash].js          (Host + Kernel)              │  │  │
+│  │  │  │   ├── vendor-[hash].js        (React, Zustand, etc.)       │  │  │
+│  │  │  │   └── plugins/                 ← ALL PLUGINS BUNDLED       │  │  │
+│  │  │  │       ├── dashboard-[hash].js  (Plugin A)                  │  │  │
+│  │  │  │       ├── loan-calc-[hash].js  (Plugin B)                  │  │  │
+│  │  │  │       └── inventory-[hash].js  (Plugin C)                  │  │  │
+│  │  │  └── static/css/                                              │  │  │
+│  │  │      └── main-[hash].css                                       │  │  │
+│  │  └───────────────────────────────────────────────────────────────┘  │  │
+│  │                         │                                          │  │
+│  │                         │ One deployment, one URL                  │  │
+│  │                         ▼                                          │  │
+│  │  ┌─────────────────────────────────────────────────────────────┐    │  │
+│  │  │           Browser loads app.yourdomain.com                  │    │  │
+│  │  │                                                             │    │  │
+│  │  │  User navigates → Garfish loads plugin bundle dynamically   │    │  │
+│  │  └─────────────────────────────────────────────────────────────┘    │  │
+│  └─────────────────────────────────────────────────────────────────────┘  │
+│                                    │                                      │
+│                                    │ API Calls                             │
+│                                    ▼                                      │
+│  ┌─────────────────────────────────────────────────────────────────────┐  │
+│  │                        PocketBase                                   │  │
+│  │  - Docker Container / Managed Service                              │  │
+│  │  - Port 8090                                                        │  │
+│  └─────────────────────────────────────────────────────────────────────┘  │
+│                                                                           │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### 1.3 Development Runtime Diagram (For Comparison)
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                        Development Environment                          │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                           │
+│  Host     : http://localhost:8080                                        │
+│  Plugin A : http://localhost:3001  ← Separate dev server                │
+│  Plugin B : http://localhost:3002  ← Separate dev server                │
+│  Plugin C : http://localhost:3003  ← Separate dev server                │
+│                                                                           │
+│  WHY? Each developer can work on a plugin independently                 │
+│       Hot reload works independently for each plugin                     │
+│                                                                           │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2: Monorepo vs Polyrepo
+
+### 2.1 Comparison Table
+
+| Aspect | Monorepo | Polyrepo |
+|--------|----------|----------|
+| **Code Organization** | Single repo with host + plugins | Separate repo per plugin |
+| **Shared Dependencies** | Easy (root package.json) | Difficult (duplicate versions) |
+| **CI/CD** | Single pipeline | Multiple pipelines |
+| **Deployment** | Host + plugins together | Independent plugin deployments |
+| **Team Autonomy** | Coordinated changes | Fully independent |
+| **Git History** | Single timeline | Separate timelines |
+| **Recommended For** | Small teams, tight coupling | Large teams, independent plugins |
+
+### 2.2 Our Recommendation: **Monorepo**
+
+**Reasons:**
+1. Modern.js + Garfish work best with shared dependencies
+2. Simplified development (`pnpm install` at root)
+3. Atomic commits across host + plugins
+4. Easier onboarding and documentation
+5. pnpm workspaces handle this well
+
+---
+
+## 3. Monorepo Deployment
+
+### 3.1 Repository Structure
+
+```
+lego-one/                          # Single monorepo
+├── host/                           # Kernel application
+├── packages/
+│   └── plugins/
+│       └── @lego/
+│           ├── plugin-dashboard/   # Official plugins
+│           ├── plugin-auth/
+│           └── plugin-billing/
+├── pnpm-workspace.yaml
+├── package.json
+├── turbo.json                      # Turborepo config (optional)
+└── .github/
+    └── workflows/
+        └── deploy.yml              # CI/CD pipeline
+```
+
+### 3.2 Workspace Configuration
+
+**File:** `pnpm-workspace.yaml`
+
+```yaml
+packages:
+  - 'host'
+  - 'packages/plugins/@lego/*'
+```
+
+**File:** `package.json` (root)
+
+```json
+{
+  "name": "lego-one",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "pnpm --filter './host' dev",
+    "build": "pnpm -r --filter './host' --filter './packages/plugins/@lego/*' build",
+    "clean": "pnpm -r clean",
+    "lint": "pnpm -r lint",
+    "typecheck": "pnpm -r typecheck"
+  },
+  "devDependencies": {
+    "@modern-js/app-tools": "^2.0.0",
+    "typescript": "^5.5.0"
+  }
+}
+```
+
+---
+
+## 4. Build Strategy
+
+### 4.1 Production Build Output (Single Server)
+
+**IMPORTANT:** In production, ALL plugins are bundled into the host's `dist/` folder. Modern.js handles this automatically when you use dynamic imports.
+
+```
+host/dist/
+├── html/
+│   └── index.html                 # Entry point
+├── static/
+│   ├── js/
+│   │   ├── main-[hash].js         # Host bundle
+│   │   ├── vendor-[hash].js       # Shared dependencies (React, Zustand, etc.)
+│   │   ├── plugins/               ← PLUGINS BUNDLED HERE
+│   │   │   ├── dashboard-[hash].js
+│   │   │   ├── loan-calc-[hash].js
+│   │   │   └── inventory-[hash].js
+│   │   └── ...                   # Code-split chunks
+│   └── css/
+│       └── main-[hash].css
+```
+
+**Key Point:** Each plugin is code-split and loaded on-demand when the user navigates to its route. Not all plugins load immediately!
+
+### 4.2 Build Configuration
+
+**Host:** `host/modern.config.ts`
+
+```typescript
+export default defineConfig({
+  // Production optimization
+  output: {
+    distPath: {
+      html: './dist/html',
+      js: './dist/static/js',
+      css: './dist/static/css',
+    },
+  },
+
+  // Asset prefix for CDN
+  source: {
+    assetPrefix: process.env.CDN_URL || '',
+  },
+});
+```
+
+**Plugin:** `packages/plugins/@lego/plugin-dashboard/modern.config.ts`
+
+```typescript
+export default defineConfig({
+  deploy: {
+    microFrontend: true,
+  },
+
+  output: {
+    distPath: {
+      html: './dist/html',
+      js: './dist/static/js',
+      css: './dist/static/css',
+    },
+  },
+});
+```
+
+### 4.3 Shared Dependencies
+
+Modern.js + Garfish automatically handle shared dependencies. In production:
+
+- **Host bundle** includes: React, ReactDOM, Router, Zustand
+- **Plugin bundles** exclude: React, ReactDOM (marked as external)
+- **Runtime**: Garfish loads shared deps from host, avoids duplicate loading
+
+---
+
+## 5. Deployment Options
+
+### 5.1 Option A: Vercel (Recommended)
+
+**Pros:**
+- Zero-config deployment
+- Built-in CI/CD
+- Edge caching
+- Preview deployments
+- **Single deployment for entire app**
+
+**Setup:**
+
+```bash
+# Install Vercel CLI
+pnpm add -g vercel
+
+# Deploy the entire app (host + bundled plugins)
+cd host
+vercel --prod
+
+# That's it! Plugins are already bundled into host/dist
+```
+
+**No separate plugin deployments needed!**
+
+**Environment Variables:**
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `VITE_POCKETBASE_URL` | PocketBase API URL | `https://api.example.com` |
+| `VITE_POCKETBASE_ADMIN_EMAIL` | Admin email (for migrations) | `admin@example.com` |
+| `VITE_POCKETBASE_ADMIN_PASSWORD` | Admin password | `***` |
+| `CDN_URL` | CDN prefix for assets | `https://cdn.example.com` |
+
+### 5.2 Option B: Railway
+
+**Pros:**
+- Docker support
+- Built-in databases
+- Easy PocketBase deployment
+
+**Setup:**
+
+Create `Dockerfile` for PocketBase:
+
+```dockerfile
+# Dockerfile.pocketbase
+FROM alpine:latest
+
+RUN apk add --no-cache wget ca-certificates
+
+WORKDIR /app
+
+# Download PocketBase
+RUN wget https://github.com/pocketbase/pocketbase/releases/download/v0.22.0/pocketbase_0.22.0_linux_amd64.zip
+RUN unzip pocketbase_0.22.0_linux_amd64.zip
+
+EXPOSE 8090
+
+CMD ["./pocketbase", "serve", "--http", "0.0.0.0:8090"]
+```
+
+### 5.3 Option C: Self-Hosted (Docker Compose)
+
+**File:** `docker-compose.yml`
+
+```yaml
+version: '3.8'
+
+services:
+  pocketbase:
+    build:
+      context: .
+      dockerfile: Dockerfile.pocketbase
+    ports:
+      - "8090:8090"
+    volumes:
+      - pocketbase_data:/app/pb_data
+    restart: unless-stopped
+
+  # Single app service (plugins already bundled in!)
+  app:
+    image: node:18-alpine
+    working_dir: /app
+    volumes:
+      - ./host:/app
+      - /app/node_modules
+    ports:
+      - "8080:8080"
+    command: sh -c "npm install && npm run build && npm run preview"
+    environment:
+      - VITE_POCKETBASE_URL=http://pocketbase:8090
+    depends_on:
+      - pocketbase
+
+volumes:
+  pocketbase_data:
+```
+
+**Note:** No separate plugin containers needed! They're bundled in the app build.
+
+---
+
+## 6. CI/CD Pipeline
+
+### 6.1 GitHub Actions Workflow
+
+**File:** `.github/workflows/deploy.yml`
+
+```yaml
+name: Deploy
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  NODE_VERSION: '18'
+  PNPM_VERSION: '8'
+
+jobs:
+  # Test job
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v2
+        with:
+          version: ${{ env.PNPM_VERSION }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Run tests
+        run: pnpm test
+
+      - name: Type check
+        run: pnpm typecheck
+
+      - name: Lint
+        run: pnpm lint
+
+  # Build job
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v2
+        with:
+          version: ${{ env.PNPM_VERSION }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Build application (host + plugins bundled)
+        run: pnpm build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: host/dist/
+
+  # Deploy job - Single deployment only!
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: host/dist/
+
+      - name: Deploy to Vercel
+        working-directory: ./host
+        run: npx vercel --prod --token=${{ secrets.VERCEL_TOKEN }}
+```
+
+**Key Change:** Only ONE deployment step, not separate host + plugin deployments!
+
+---
+
+## 7. Runtime Configuration
+
+### 7.1 Host: Dev vs Prod Entry Points
+
+**File:** `host/src/modern.runtime.ts`
+
+```typescript
+import { defineRuntimeConfig } from '@modern-js/runtime';
+
+// Detect environment
+const isDev = import.meta.env.MODE === 'development';
+
+export default defineRuntimeConfig({
+  masterApp: {
+    apps: [
+      {
+        name: '@lego/plugin-dashboard',
+        // Dev: Separate server │ Prod: Bundled via dynamic import
+        entry: isDev
+          ? 'http://localhost:3001'
+          : () => import('@lego/plugin-dashboard'),
+        activeWhen: '/dashboard',
+      },
+      {
+        name: '@lego/plugin-loan-calculator',
+        entry: isDev
+          ? 'http://localhost:3002'
+          : () => import('@lego/plugin-loan-calculator'),
+        activeWhen: '/apps/loan',
+      },
+      {
+        name: '@lego/plugin-inventory',
+        entry: isDev
+          ? 'http://localhost:3003'
+          : () => import('@lego/plugin-inventory'),
+        activeWhen: '/apps/inventory',
+      },
+    ],
+  },
+});
+```
+
+**How it works:**
+- **Development:** Garfish fetches plugin from `http://localhost:3001`
+- **Production:** Modern.js bundles plugin into host, loaded via `import()`
+
+### 7.2 Environment-Specific Config
+
+**File:** `.env.production`
+
+```bash
+# Host configuration
+VITE_POCKETBASE_URL=https://api.yourdomain.com
+VITE_POCKETBASE_ADMIN_EMAIL=admin@yourdomain.com
+VITE_POCKETBASE_ADMIN_PASSWORD=${PB_ADMIN_PASSWORD}
+
+# No plugin URLs needed! They're bundled in production.
+```
+
+**File:** `.env.development`
+
+```bash
+# Host configuration
+VITE_POCKETBASE_URL=http://localhost:8090
+VITE_POCKETBASE_ADMIN_EMAIL=admin@localhost
+VITE_POCKETBASE_ADMIN_PASSWORD=admin123
+
+# Plugin dev servers (for reference)
+VITE_DEV_DASHBOARD_PORT=3001
+VITE_DEV_LOAN_CALC_PORT=3002
+VITE_DEV_INVENTORY_PORT=3003
+```
+
+---
+
+## 8. Monitoring and Logging
+
+### 8.1 Health Checks
+
+```typescript
+// Host: src/api/health.ts
+export async function healthCheck() {
+  const checks = {
+    host: true,
+    pocketbase: false,
+    plugins: {},
+  };
+
+  // Check PocketBase
+  try {
+    const pb = new PocketBase(import.meta.env.VITE_POCKETBASE_URL);
+    await pb.health.check();
+    checks.pocketbase = true;
+  } catch (error) {
+    console.error('PocketBase health check failed:', error);
+  }
+
+  // Check plugins (if loaded)
+  for (const [name, app] of Object.entries(Garfish.apps)) {
+    checks.plugins[name] = app.appInfo ? true : false;
+  }
+
+  return checks;
+}
+```
+
+### 8.2 Error Tracking
+
+Integrate Sentry for both host and plugins:
+
+```typescript
+// Host: src/bootstrap.tsx
+import * as Sentry from '@sentry/react';
+
+Sentry.init({
+  dsn: import.meta.env.VITE_SENTRY_DSN,
+  environment: import.meta.env.MODE,
+  // Track plugin errors separately
+  beforeSend(event, hint) {
+    if (event.exception?.values?.[0]?.stacktrace) {
+      const stack = event.exception.values[0].stacktrace;
+      // Tag plugin errors
+      for (const frame of stack.frames || []) {
+        if (frame.filename?.includes('@lego/plugin-')) {
+          event.tags = { ...event.tags, plugin: frame.filename };
+          break;
+        }
+      }
+    }
+    return event;
+  },
+});
+```
+
+---
+
+## 9. Deployment Checklist
+
+### Pre-Deployment
+
+- [ ] All tests passing
+- [ ] TypeScript compilation successful
+- [ ] Linting clean
+- [ ] Environment variables configured
+- [ ] PocketBase migrations tested
+- [ ] Build completes successfully (host + plugins bundled)
+
+### Post-Deployment
+
+- [ ] Application accessible at domain
+- [ ] Navigation loads plugins correctly
+- [ ] PocketBase API accessible
+- [ ] Authentication working
+- [ ] SSL certificates valid
+- [ ] Error monitoring active
+
+---
+
+## 10. Next Steps
+
+All research documents complete. Proceed to implementation planning phase.
+
+---
+
+## Research Summary
+
+| Document | Status |
+|----------|--------|
+| `00-modernjs-audit.md` | ✅ Complete |
+| `01-system-blueprint.md` | ✅ Complete |
+| `02-data-migration-protocol.md` | ✅ Complete |
+| `03-host-setup.md` | ✅ Complete |
+| `04-plugin-architecture.md` | ✅ Complete |
+| `05-slot-injection-pattern.md` | ✅ Complete |
+| `06-cli-strategy.md` | ✅ Complete |
+| `07-deployment.md` | ✅ Complete |
+
+---
+
+## References
+
+- [Modern.js Deployment Guide](https://modernjs.dev/guides/deploy)
+- [Vercel Documentation](https://vercel.com/docs)
+- [Railway Documentation](https://docs.railway.app/)
+- [PocketBase Deployment](https://pocketbase.io/docs/go-deployment/)
+- [GitHub Actions](https://docs.github.com/en/actions)