Documentation Deployment Architecture

Visual overview of how the documentation deployment works.

Current Architecture (After This PR)

┌─────────────────────────────────────────────────────────────────┐
│                         GitHub Repository                        │
│                    cattreedev/lantern_app                        │
└───────────────┬─────────────────────┬───────────────────────────┘
                │                     │
                │                     │
        Push to main            Push to dev
                │                     │
                ▼                     ▼
┌───────────────────────┐   ┌───────────────────────┐
│  GitHub Actions       │   │  GitHub Actions       │
│  deploy-docs.yml      │   │  deploy-docs.yml      │
│                       │   │                       │
│  1. npm ci            │   │  1. npm ci            │
│  2. npm run           │   │  2. npm run           │
│     docs:build        │   │     docs:build        │
│  3. Deploy to CF      │   │  3. Deploy to CF      │
└───────────┬───────────┘   └───────────┬───────────┘
            │                           │
            ▼                           ▼
┌───────────────────────┐   ┌───────────────────────┐
│  Cloudflare Pages     │   │  Cloudflare Pages     │
│  lantern-docs         │   │  lantern-docs-dev     │
│  (Production)         │   │  (Development)        │
└───────────┬───────────┘   └───────────┬───────────┘
            │                           │
            ▼                           ▼
┌───────────────────────┐   ┌───────────────────────┐
│  docs.ourlantern.app  │   │ docs-dev.ourlantern.  │
│  (Public/Protected)   │   │ app (Protected)       │
└───────────────────────┘   └───────────────────────┘

Pull Request Flow

┌─────────────────────────────────────────┐
│  Developer creates PR with docs changes │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│       GitHub Actions triggers           │
│       (on pull_request event)           │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│  Builds docs and deploys to preview URL │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│  Preview URL:                           │
│  feature-xyz.lantern-docs-dev.pages.dev │
│                                         │
│  Team reviews docs before merge         │
└─────────────────────────────────────────┘

Complete Infrastructure

┌────────────────────────────────────────────────────────────┐
│                   Lantern Infrastructure                    │
└────────────────────────────────────────────────────────────┘

Main Application:
┌──────────────────┐                    ┌──────────────────┐
│ ourlantern.app   │                    │ dev.ourlantern.  │
│ (Production)     │◄───┐      ┌───────►│ app (Dev)        │
└──────────────────┘    │      │        └──────────────────┘
         ▲              │      │                 ▲
         │              │      │                 │
         │         ┌────┴──────┴────┐           │
         │         │  Cloudflare     │           │
         │         │  Pages Projects │           │
         │         │                 │           │
         │         │  lantern-app    │           │
         │         │  lantern-app-dev│           │
         │         └─────────────────┘           │
         │                                        │
         └────────────────┬───────────────────────┘
                          │
                    GitHub Repo
                  (cattreedev/
                   lantern_app)
                          │
         ┌────────────────┴───────────────────────┐
         │                                        │
         ▼                                        ▼
┌──────────────────┐                    ┌──────────────────┐
│ docs.ourlantern. │                    │ docs-dev.        │
│ app (Production) │◄───┐      ┌───────►│ ourlantern.app   │
└──────────────────┘    │      │        └──────────────────┘
         ▲              │      │                 ▲
         │              │      │                 │
         │         ┌────┴──────┴────┐           │
         │         │  Cloudflare     │           │
         │         │  Pages Projects │           │
         │         │                 │           │
         │         │  lantern-docs   │           │
         │         │  lantern-docs-  │           │
         │         │  dev            │           │
         │         └─────────────────┘           │
         │                                        │
         └────────────────────────────────────────┘

Documentation Site (NEW - This PR)

DNS Configuration

┌─────────────────────────────────────────────┐
│     Cloudflare DNS (ourlantern.app zone)    │
├─────────────────────────────────────────────┤
│                                             │
│  @ (root)         → lantern-app.pages.dev   │
│  dev              → lantern-app-dev.pages.  │
│                     dev                     │
│  docs (NEW)       → lantern-docs.pages.dev  │
│  docs-dev (NEW)   → lantern-docs-dev.pages. │
│                     dev                     │
│                                             │
│  All CNAME records are Proxied (🟠)        │
└─────────────────────────────────────────────┘

GitHub Actions Workflow Triggers

Event: Push to main/dev
Conditions:
  - Files in docs/** changed OR
  - package.json changed OR
  - .github/workflows/deploy-docs.yml changed
  ↓
  Run workflow

Event: Pull Request
Conditions:
  - Files in docs/** changed
  ↓
  Run workflow (preview deployment)

Event: workflow_dispatch
Conditions:
  - Manual trigger from GitHub UI
  ↓
  Run workflow

Deployment Timeline

Time: T+0s
├─ Developer pushes commit to dev branch
│
Time: T+5s
├─ GitHub Actions detects push
├─ Workflow starts
│
Time: T+10s
├─ Checkout code
├─ Setup Node.js
│
Time: T+30s
├─ Install dependencies (npm ci)
│
Time: T+60s
├─ Build docs (npm run docs:build)
│
Time: T+90s
├─ Deploy to Cloudflare Pages
│
Time: T+120s
├─ Cloudflare builds and deploys
│
Time: T+180s (3 minutes)
└─ ✅ Docs live at docs.dev.ourlantern.app

Security & Access

┌─────────────────────────────────────────────┐
│              Access Control                  │
├─────────────────────────────────────────────┤
│                                             │
│  ourlantern.app                             │
│  └─ Cloudflare Access: PIN Auth (Piloting)  │
│                                             │
│  dev.ourlantern.app                         │
│  └─ Cloudflare Access: PIN Auth            │
│                                             │
│  docs.ourlantern.app (NEW)                  │
│  └─ Option 1: Public (Recommended)          │
│  └─ Option 2: Cloudflare Access (Optional) │
│                                             │
│  docs.dev.ourlantern.app (NEW)              │
│  └─ Option 1: Public                        │
│  └─ Option 2: Protected (For unreleased     │
│                          features)          │
└─────────────────────────────────────────────┘

Build Outputs

Repository Structure:
/home/runner/work/lantern_app/lantern_app/
│
├─ Main App Build (npm run build:app)
│  └─ Output: dist/
│     ├─ index.html
│     ├─ assets/
│     ├─ sw.js (service worker)
│     └─ manifest.webmanifest
│
└─ Docs Build (npm run docs:build)
   └─ Output: docs/.vitepress/dist/
      ├─ index.html
      ├─ assets/
      ├─ engineering/
      ├─ features/
      ├─ business/
      └─ ... (all docs pages)

Note: Builds are now INDEPENDENT - no longer copied together

Key Benefits Visualized

Before (Single Deployment):
┌─────────────────────────┐
│   Build App + Docs      │  ← 5-10 minutes
│   (Single large build)  │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  Deploy to Cloudflare   │  ← 2-3 minutes
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│ ourlantern.app/docs/    │
└─────────────────────────┘

After (Separate Deployments):
┌──────────────┐  ┌──────────────┐
│  Build App   │  │  Build Docs  │  ← 2-3 min each
└──────┬───────┘  └──────┬───────┘
       │                 │
       ▼                 ▼
┌──────────────┐  ┌──────────────┐
│  Deploy App  │  │  Deploy Docs │  ← 2-3 min each
└──────┬───────┘  └──────┬───────┘
       │                 │
       ▼                 ▼
┌──────────────┐  ┌──────────────┐
│ourlantern.app│  │docs.ourlantern│
│              │  │.app           │
└──────────────┘  └──────────────┘

Benefits:
✅ Update docs without touching app
✅ Faster individual builds
✅ Independent scaling
✅ Cleaner URLs
✅ Better SEO

Monitoring & Verification

1. GitHub Actions
   └─ https://github.com/cattreedev/lantern_app/actions
      └─ "Deploy Documentation" workflow
         ├─ View status (✅ or ❌)
         ├─ See deployment logs
         └─ Check deployment summary

2. Cloudflare Dashboard
   └─ https://dash.cloudflare.com
      └─ Workers & Pages → Pages
         ├─ lantern-docs (production)
         │  └─ Deployments tab
         │     ├─ View history
         │     ├─ See build logs
         │     └─ Check status
         │
         └─ lantern-docs-dev (development)
            └─ Same monitoring

3. Direct Verification
   ├─ Visit docs.ourlantern.app
   ├─ Hard refresh (Ctrl+Shift+R)
   └─ Verify changes appear

---

Quick Decision Tree

Need to update docs?
    │
    ├─ Yes
    │  │
    │  ├─ Edit docs/ files
    │  ├─ Test locally (npm run docs:dev)
    │  ├─ Commit and push to dev
    │  └─ ✅ Auto-deploys to docs.dev.ourlantern.app
    │
    └─ Ready for production?
       │
       ├─ Yes
       │  ├─ Merge to main
       │  └─ ✅ Auto-deploys to docs.ourlantern.app
       │
       └─ No
          └─ Keep testing on docs-dev

---

Last updated: 2026-01-10