Hosting HTML-Docs Internally at Meta
Migration Plan

One codebase. Two deployment targets. Keep the external Vercel app running for outside users while shipping the same product internally on Meta's Nest platform — with first-class analytics and keyboard shortcuts on both.

Context

HTML-Docs currently runs on Vercel + Supabase (Auth + Postgres) + Liveblocks + OpenAI. None of these are usable for an internal Meta deployment: external SaaS is blocked by data policy, Supabase email/password isn't an accepted internal auth method, and Vercel isn't a Meta hosting target. We need to deploy this app to employees on the corp network while changing as little of the editor logic as possible — and the external version must keep running for outside users.

The right target is Nest (fbsource/nest/apps/) — Meta's internal Next.js platform. It runs the exact stack we already use (Next.js 16 + React 19 + Node 22), supports WebSockets and SSE through Proxygen/X2P, gives you employee auth at the edge for free, and ships first-class libraries for every infra dependency we have (XDB for Postgres, Manifold for storage, @nest/llm for OpenAI, Chronos for cron). The editor code itself — components/shadow-dom-viewer.tsx, lib/html-parser.ts, lib/interactive-patterns.ts, all the Tiptap / Radix UI — does not change.

Maintenance model — one codebase, two targets

Because the external version keeps serving outside users while the internal version stands up for Meta employees, we need ONE codebase that builds to both. The pattern is a thin adapter layer + a build-time DEPLOY_TARGET env var (public | meta) that picks which implementation gets bundled. Editor code calls adapter interfaces, never vendor SDKs directly. Next.js tree-shakes the unused branch — the public build ships zero Nest code and the Meta build ships zero Supabase code.

The contract

• All vendor SDK imports (@supabase/*, @liveblocks/*, @ai-sdk/openai, @nest/*) live under lib/{db,auth,llm,storage,realtime}/impl/{public,meta}/.
• Pages, components, server actions, and API routes import from @/lib/{db,auth,...} only — never from the vendor SDK directly.
• lib/{db,auth,...}/index.ts does the dispatch at build time:

export const db = process.env.DEPLOY_TARGET === 'meta'
  ? await import('./impl/meta')
  : await import('./impl/public')

• ESLint import/no-restricted-paths rule blocks direct vendor imports outside impl/.

File layout

Cost model

Escape hatch: if a second team starts maintaining the internal build, or the two versions need genuinely different feature sets, switch to extracting the editor core as an internal npm package consumed by two thin app shells. Until then, the single-repo adapter model is the right cost/benefit.

Detailed architecture

This section is the implementation companion to the plan above. It zooms into request lifecycle, deployment topology, authentication, the AI request flow, the database schema, per-adapter TypeScript contracts, and environment variables — enough detail to build either target without re-deriving the design.

Request lifecycle (side-by-side)

The same HTTP request flows through symmetric layers on both targets. The middle band — Next.js routing, server actions, adapter interfaces — is identical. Only the outer edges differ: what's in front of Next.js (Vercel CDN vs X2P/Proxygen) and what's behind the adapters (Supabase vs XDB, OpenAI vs Plugboard, Liveblocks vs a WS sidecar). That's the entire architectural payoff of the adapter model.

Deployment topology

Where things actually run, and what crosses which network boundary.

Authentication flows

Both targets land the viewer's identity in the same shape ({ id, name, email }) before any server action runs — but via very different handshakes.

The lib/auth/ adapter normalizes both into a single getViewer(): Promise<Viewer | null> call so server actions don't branch on target.

AI request flow (Docsmith chat)

Most architecturally interesting path because it spans the client (streaming SSE), the LLM adapter (provider selection), and tool calling (which gates writes through user-approval cards).

Database schema

21 tables across 7 domain groups. Postgres has foreign-key constraints and one trigger (on document_events) that auto-records mutations; XDB drops the FK CONSTRAINTs (app-level invariants instead) and replaces the trigger with an explicit recordEvent() helper called from each mutation.

Per-adapter TypeScript contracts

Each adapter ships a types.ts defining the shape both impls must satisfy. Snippets below show the minimum-viable shape after the first slice has landed; surfaces grow as more action files migrate.

// lib/llm/types.ts — LLM adapter
export type LLMCapability = 'chat' | 'refine' | 'review' | 'vision'

export interface LLMAdapter {
  getModel(capability: LLMCapability): LanguageModel
  webSearchTool(): Tool | null
}

// lib/db/types.ts — DB adapter (grows per table)
export interface DBAdapter {
  documents: {
    getById(id: string): Promise<Document | null>
    listByOwner(ownerId: string): Promise<Document[]>
    getIdByShareCode(code: string): Promise<string | null>
    updateHtmlContent(id: string, html: string): Promise<void>
    getKnowledge(id: string): Promise<string>
    getOwnerId(id: string): Promise<string | null>
    updateKnowledge(id: string, knowledge: string): Promise<void>
  }
  regions: {
    listByDocument(documentId: string): Promise<EditableRegion[]>
  }
  accountKnowledge: {
    get(userId: string): Promise<string>
    upsert(userId: string, content: string): Promise<void>
  }
}

// lib/auth/types.ts — Auth adapter (planned)
export interface Viewer {
  id: string             // uuid (public) | fbid (meta)
  name: string
  email: string
  unixname?: string      // meta only
}

export interface AuthAdapter {
  getViewer(): Promise<Viewer | null>
  requireViewer(): Promise<Viewer> // throws if unauthed
}

// lib/storage/types.ts — Storage adapter (planned)
export interface StorageAdapter {
  uploadDocImage(documentId: string, file: Buffer, mime: string):
    Promise<{ url: string; path: string }>
  uploadPdfOriginal(documentId: string, file: Buffer):
    Promise<{ path: string }>
  getPdfDownloadUrl(path: string): Promise<string>
}

// lib/realtime/types.ts — Realtime adapter (stubbed for MVP)
export interface RealtimeHooks {
  RoomProvider: React.FC<{ roomId: string; children: React.ReactNode }>
  useMyPresence(): [Presence, (next: Partial<Presence>) => void]
  useOthers(): readonly OtherUser[]
  useBroadcastEvent(): (event: RoomEvent) => void
  useEventListener(handler: (event: RoomEvent) => void): void
}

// lib/analytics/types.ts — Shared module (no public/meta split)
export function track(eventName: string, properties?: Record<string, unknown>): void

// Written through lib/db; same call sites, same schema, both targets.

Environment variables per target

The variable space partitions cleanly. Most public secrets disappear on meta (the corresponding service is internal); meta-specific config is owned by Configerator and the Nest CLI.

Target architecture (per-adapter)

Concrete file changes

Analytics — own implementation, shared module

analytics_events {
  id            uuid / bigint pk
  user_id       uuid / fbid    nullable   // null = anon viewer on public
  session_id    text
  event_name    text           // 'docsmith_message_sent', 'pdf_imported', etc.
  properties    jsonb / json
  path          text
  referrer      text           nullable
  user_agent    text
  occurred_at   timestamptz
}

import { track } from '@/lib/analytics'

track('docsmith_message_sent', { documentId, model, hasAttachments: true })
track('pdf_imported', { pageCount, viaVision: true })
track('document_published', { documentId, visibility })

Keyboard shortcuts

Phased rollout

Verification

1. Phase 0 (public, no behavior change): existing tests + Vercel preview smoke. grep -r "@supabase\|@liveblocks\|@ai-sdk/openai" app components empty outside lib/*/impl/.
2. Local dev (meta): nest dev; internalmeta.com proxy serves home page; authed /documents populates useInternAuth().user.unixname.
3. DB (meta): nest xdb migrate + UI create-doc; verify row in nest xdb shell; recordEvent() produces document_events rows.
4. Storage (meta): Upload PNG; returned URL is scontent.xx.fbcdn.net and renders.
5. AI (meta): Open Docsmith, stream message; SSE works; actorId in @nest/llm logs.
6. PDF vision (meta): Upload 5-page PDF; llama4-maverick produces editable HTML.
7. Cron (meta): curl --cert ... -H "Authorization: Bearer $CRON_SECRET" .../api/cron/webhook-deliveries returns 200; Chronos UI shows minute cadence.
8. Realtime stub (meta): two tabs on same doc — edits do NOT appear live (expected); both save without errors.
9. Analytics (both): Open doc + send Docsmith message + publish doc → confirm 3 corresponding analytics_events rows with correct user_id / event_name / properties. PUBLIC /admin/stats shows counts; META Unidash returns rows.
10. Web Vitals (both): Scroll + navigate; web_vital rows for LCP / CLS / INP show up.
11. Shortcuts (both): ⌘K opens command palette. ? shows cheatsheet. ⌘/ opens Docsmith. Confirm shortcut_used event lands in analytics_events.
12. Per-target clean build: DEPLOY_TARGET=public next build ships no @nest/*. nest build ships no @supabase/* or @liveblocks/*.

What stays unchanged across both targets

Identical-on-both-targets-by-design (new shared modules)

• lib/analytics/ — one implementation, writes through lib/db; same event schema and call sites everywhere
• lib/shortcuts/ — pure editor-core; new shortcuts get registered once and ship to both targets