@prmichaelsen/acp-visualizer 0.1.0

package/agent/patterns/tanstack-cloudflare.nextjs-to-tanstack-routing.md

@@ -0,0 +1,461 @@
+# Next.js to TanStack Start Routing Migration
+
+**Category**: Migration
+**Applicable To**: Projects migrating from Next.js App Router to TanStack Start + Cloudflare Workers
+**Status**: Stable
+
+---
+
+## Overview
+
+This pattern maps Next.js App Router conventions to their TanStack Start equivalents. It covers page routes, layouts, API routes, dynamic parameters, metadata, server-side data fetching, and middleware. The goal is a systematic migration where each Next.js file has a clear TanStack Start counterpart.
+
+Both frameworks use file-based routing, but they differ in naming conventions, data loading strategies, and API route syntax. This guide provides side-by-side mappings with code examples.
+
+---
+
+## When to Use This Pattern
+
+✅ **Use this pattern when:**
+- Migrating an existing Next.js App Router application to TanStack Start
+- Need a reference for mapping Next.js conventions to TanStack equivalents
+- Building new features and want to know the TanStack way of doing something familiar from Next.js
+
+❌ **Don't use this pattern when:**
+- Migrating from Next.js Pages Router (different conventions)
+- Building a new project from scratch (use other patterns directly)
+
+---
+
+## Route File Mapping
+
+| Next.js App Router | TanStack Start | Notes |
+|-------------------|----------------|-------|
+| `app/page.tsx` | `routes/index.tsx` | Home page |
+| `app/layout.tsx` | `routes/__root.tsx` | Root layout |
+| `app/about/page.tsx` | `routes/about.tsx` | Static page |
+| `app/blog/[id]/page.tsx` | `routes/blog/$id.tsx` | Dynamic route (`[id]` → `$id`) |
+| `app/blog/[...slug]/page.tsx` | `routes/blog/$.tsx` | Catch-all route |
+| `app/api/posts/route.ts` | `routes/api/posts/index.tsx` | API route |
+| `app/api/posts/[id]/route.ts` | `routes/api/posts/$id.tsx` | Dynamic API route |
+| `app/(group)/page.tsx` | `routes/_group/index.tsx` | Route group (parentheses → underscore) |
+| `app/loading.tsx` | `pendingComponent` on route | Loading state |
+| `app/error.tsx` | `errorComponent` on route | Error boundary |
+| `app/not-found.tsx` | `notFoundComponent` on route | 404 handler |
+
+---
+
+## Page Routes
+
+### Next.js: Server Component with Data Fetching
+
+```typescript
+// app/home/page.tsx (Next.js)
+import { cookies } from 'next/headers'
+import { getServerSession } from '@/lib/auth-server'
+import HomePageClient from './HomePageClient'
+
+export const metadata = {
+  title: 'Home',
+  description: 'Your neighborhood feed',
+}
+
+export default async function HomePage() {
+  const cookieStore = cookies()
+  const session = cookieStore.get('session')
+  // Fetch data server-side...
+  return <HomePageClient />
+}
+```
+
+### TanStack Start: Route with beforeLoad
+
+```typescript
+// routes/home.tsx (TanStack Start)
+import { createFileRoute, redirect } from '@tanstack/react-router'
+import { getAuthSession } from '@/lib/auth/server-fn'
+
+export const Route = createFileRoute('/home')({
+  // Server-side data fetching (replaces async Server Component)
+  beforeLoad: async () => {
+    const user = await getAuthSession()
+    if (!user) {
+      throw redirect({ to: '/auth', search: { redirect_url: '/home' } })
+    }
+
+    let posts = []
+    try {
+      posts = await PostDatabaseService.getFeed(user.uid, 50)
+    } catch (error) {
+      console.error('Failed to preload feed:', error)
+    }
+
+    return { user, posts }
+  },
+
+  // SEO metadata (replaces export const metadata)
+  meta: () => [
+    { title: 'Home' },
+    { name: 'description', content: 'Your neighborhood feed' },
+  ],
+
+  component: HomePage,
+})
+
+function HomePage() {
+  const { user, posts } = Route.useRouteContext()
+  return <HomePageClient initialPosts={posts} />
+}
+```
+
+---
+
+## Layouts
+
+### Next.js: layout.tsx
+
+```typescript
+// app/layout.tsx (Next.js)
+import { cookies } from 'next/headers'
+import ReduxProvider from '@/components/ReduxProvider'
+
+export default async function RootLayout({ children }) {
+  const cookieStore = cookies()
+  const sessionCookie = cookieStore.get('session')
+
+  let initialState
+  try {
+    initialState = await getStateFromHeaders(sessionCookie?.value)
+  } catch { initialState = {} }
+
+  return (
+    <html lang="en">
+      <body>
+        <ReduxProvider initialState={initialState}>
+          <Navbar />
+          {children}
+          <ModalContainer />
+          <ToastContainer />
+        </ReduxProvider>
+      </body>
+    </html>
+  )
+}
+```
+
+### TanStack Start: __root.tsx
+
+```typescript
+// routes/__root.tsx (TanStack Start)
+import { createRootRouteWithContext, Outlet } from '@tanstack/react-router'
+import { getAuthSession } from '@/lib/auth/server-fn'
+import ReduxProvider from '@/components/ReduxProvider'
+
+export const Route = createRootRouteWithContext()({
+  beforeLoad: async () => {
+    const user = await getAuthSession()
+    return { user }
+  },
+  component: RootLayout,
+})
+
+function RootLayout() {
+  const { user } = Route.useRouteContext()
+
+  return (
+    <ReduxProvider initialUser={user}>
+      <Navbar />
+      <Outlet />  {/* Replaces {children} */}
+      <ModalContainer />
+      <ToastContainer />
+    </ReduxProvider>
+  )
+}
+```
+
+**Key differences**:
+- `{children}` → `<Outlet />`
+- `cookies()` from `next/headers` → `getAuthSession()` server function
+- Metadata in `export const metadata` → `meta` function on route
+- `<html>` and `<body>` go in a separate entry file, not in `__root.tsx`
+
+---
+
+## API Routes
+
+### Next.js: Route Handlers
+
+```typescript
+// app/api/posts/create/route.ts (Next.js)
+import { NextRequest, NextResponse } from 'next/server'
+import { getServerSession } from '@/lib/auth-server'
+
+export async function POST(request: NextRequest) {
+  const session = await getServerSession(request)
+  if (!session?.user) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const body = await request.json()
+  const post = await PostDatabaseService.create(session.user.uid, body)
+
+  return NextResponse.json(post, { status: 201 })
+}
+```
+
+### TanStack Start: Server Handlers
+
+```typescript
+// routes/api/posts/create.tsx (TanStack Start)
+import { createFileRoute } from '@tanstack/react-router'
+import { getAuthSession } from '@/lib/auth/server-fn'
+
+export const Route = createFileRoute('/api/posts/create')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const user = await getAuthSession()
+        if (!user) {
+          return new Response(JSON.stringify({ error: 'Unauthorized' }), {
+            status: 401,
+            headers: { 'Content-Type': 'application/json' },
+          })
+        }
+
+        const body = await request.json()
+        const post = await PostDatabaseService.create(user.uid, body)
+
+        return new Response(JSON.stringify(post), {
+          status: 201,
+          headers: { 'Content-Type': 'application/json' },
+        })
+      },
+    },
+  },
+})
+```
+
+**Key differences**:
+- `NextResponse.json()` → `new Response(JSON.stringify())` with headers
+- `export async function POST` → `server.handlers.POST`
+- `NextRequest` type → standard `Request`
+- File extension `.ts` → `.tsx`
+
+---
+
+## Dynamic Routes
+
+### Next.js: [id] Parameter
+
+```typescript
+// app/api/posts/[id]/route.ts (Next.js)
+export async function GET(request: NextRequest, { params }: { params: { id: string } }) {
+  const post = await PostDatabaseService.getById(params.id)
+  return NextResponse.json(post)
+}
+```
+
+### TanStack Start: $id Parameter
+
+```typescript
+// routes/api/posts/$id.tsx (TanStack Start)
+export const Route = createFileRoute('/api/posts/$id')({
+  server: {
+    handlers: {
+      GET: async ({ params }) => {
+        const post = await PostDatabaseService.getById(params.id)
+        return new Response(JSON.stringify(post), {
+          status: 200,
+          headers: { 'Content-Type': 'application/json' },
+        })
+      },
+    },
+  },
+})
+```
+
+**Key difference**: `[id]` → `$id` in file names. Params accessed the same way.
+
+---
+
+## Server-Side Data Fetching
+
+| Next.js Pattern | TanStack Start Equivalent |
+|----------------|--------------------------|
+| `async function Page()` (Server Component) | `beforeLoad` on route |
+| `cookies()` from `next/headers` | `getRequest()` from `@tanstack/react-start/server` |
+| `headers()` from `next/headers` | `getRequest().headers` |
+| `fetch()` in Server Component | Database service call in `beforeLoad` |
+| `revalidatePath()` / `revalidateTag()` | Not needed (no ISR — always fresh on Workers) |
+| `generateStaticParams()` | Not applicable (no SSG on Workers) |
+
+---
+
+## Metadata / SEO
+
+### Next.js: Metadata Export
+
+```typescript
+// app/profile/[username]/page.tsx (Next.js)
+export async function generateMetadata({ params }) {
+  const profile = await getProfile(params.username)
+  return {
+    title: profile.displayName,
+    openGraph: { title: profile.displayName, images: [profile.avatar] },
+  }
+}
+```
+
+### TanStack Start: meta Function
+
+```typescript
+// routes/profile/$username.tsx (TanStack Start)
+export const Route = createFileRoute('/profile/$username')({
+  beforeLoad: async ({ params }) => {
+    const profile = await ProfileDatabaseService.getByUsername(params.username)
+    return { profile }
+  },
+  meta: ({ loaderData }) => [
+    { title: loaderData.profile?.displayName },
+    { property: 'og:title', content: loaderData.profile?.displayName },
+  ],
+  component: ProfilePage,
+})
+```
+
+---
+
+## Middleware
+
+### Next.js: middleware.ts
+
+```typescript
+// middleware.ts (Next.js — runs on every request)
+import { NextResponse } from 'next/server'
+export function middleware(request) {
+  if (request.nextUrl.pathname.startsWith('/admin')) {
+    // Check auth, redirect if needed
+  }
+  return NextResponse.next()
+}
+export const config = { matcher: ['/admin/:path*'] }
+```
+
+### TanStack Start: beforeLoad on Parent Route
+
+```typescript
+// routes/admin.tsx (TanStack Start — layout route for /admin/*)
+export const Route = createFileRoute('/admin')({
+  beforeLoad: async () => {
+    const user = await getAuthSession()
+    if (!user?.isAdmin) {
+      throw redirect({ to: '/auth' })
+    }
+    return { user }
+  },
+  component: AdminLayout,
+})
+
+function AdminLayout() {
+  return <Outlet />  // Child admin routes render here
+}
+```
+
+**Key difference**: No global middleware file. Use `beforeLoad` on parent routes for path-specific guards.
+
+---
+
+## SSE / Streaming Responses
+
+### Next.js: ReadableStream
+
+```typescript
+// app/api/chat/stream/route.ts (Next.js)
+export async function POST(request: NextRequest) {
+  const stream = new ReadableStream({
+    async start(controller) {
+      const encoder = new TextEncoder()
+      controller.enqueue(encoder.encode(`data: ${JSON.stringify({ type: 'chunk' })}\n\n`))
+      controller.close()
+    }
+  })
+  return new Response(stream, {
+    headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' }
+  })
+}
+```
+
+### TanStack Start: Same Pattern (Web Standards)
+
+```typescript
+// routes/api/chat/stream.tsx (TanStack Start)
+POST: async ({ request }) => {
+  const stream = new ReadableStream({
+    async start(controller) {
+      const encoder = new TextEncoder()
+      controller.enqueue(encoder.encode(`data: ${JSON.stringify({ type: 'chunk' })}\n\n`))
+      controller.close()
+    }
+  })
+  return new Response(stream, {
+    headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' }
+  })
+}
+```
+
+SSE streaming is identical — both use Web Standard `ReadableStream`. However, for real-time chat consider migrating to **Durable Objects WebSocket** instead of SSE.
+
+---
+
+## Migration Checklist
+
+### Phase 1: Project Setup
+- [ ] Initialize TanStack Start project with Cloudflare Workers
+- [ ] Configure `wrangler.toml` (see [wrangler-configuration](./tanstack-cloudflare.wrangler-configuration.md))
+- [ ] Set up `vite.config.ts` with TanStack + Cloudflare plugins
+- [ ] Configure path aliases (`@/` → `./src/`)
+- [ ] Move environment variables to Cloudflare secrets
+
+### Phase 2: Route Migration
+- [ ] Convert `app/layout.tsx` → `routes/__root.tsx`
+- [ ] Convert `app/page.tsx` → `routes/index.tsx`
+- [ ] Convert page routes: `app/X/page.tsx` → `routes/X.tsx`
+- [ ] Convert dynamic routes: `[id]` → `$id`
+- [ ] Convert `metadata` exports → `meta` functions
+- [ ] Move `{children}` to `<Outlet />`
+
+### Phase 3: API Route Migration
+- [ ] Convert `app/api/X/route.ts` → `routes/api/X/index.tsx`
+- [ ] Replace `NextRequest`/`NextResponse` with Web Standard `Request`/`Response`
+- [ ] Replace `export async function GET/POST` → `server.handlers.GET/POST`
+- [ ] Replace `cookies()` API with cookie parsing from request headers
+
+### Phase 4: Data Fetching Migration
+- [ ] Replace async Server Components with `beforeLoad`
+- [ ] Replace `cookies()`/`headers()` with `getAuthSession()` server function
+- [ ] Remove `revalidatePath`/`revalidateTag` (not needed on Workers)
+- [ ] Remove `generateStaticParams` (no SSG on Workers)
+
+### Phase 5: Next.js Specific Removal
+- [ ] Remove `next.config.js`
+- [ ] Remove `middleware.ts` (use `beforeLoad` guards)
+- [ ] Remove `next/image` usage (use standard `<img>` or Cloudflare Images)
+- [ ] Remove `next/link` (use TanStack Router `<Link>`)
+- [ ] Remove `next/navigation` (use TanStack Router hooks)
+- [ ] Remove `next/headers` usage
+
+---
+
+## Related Patterns
+
+- **[API Route Handlers](./tanstack-cloudflare.api-route-handlers.md)**: Target API route pattern
+- **[SSR Preload](./tanstack-cloudflare.ssr-preload.md)**: Replaces async Server Components
+- **[Auth Session Management](./tanstack-cloudflare.auth-session-management.md)**: Replaces `cookies()` auth pattern
+- **[Wrangler Configuration](./tanstack-cloudflare.wrangler-configuration.md)**: Replaces `vercel.json` + `next.config.js`
+
+---
+
+**Status**: Stable - Comprehensive migration reference
+**Recommendation**: Use as a lookup guide during Next.js → TanStack Start migration
+**Last Updated**: 2026-02-28
+**Contributors**: Patrick Michaelsen

package/agent/patterns/tanstack-cloudflare.notifications-engine.md

@@ -0,0 +1,151 @@
+# Notifications Engine
+
+**Category**: Architecture
+**Applicable To**: Real-time push notifications via WebSocket with multi-tab sync, exponential backoff, and FCM fallback for offline users
+**Status**: Stable
+
+---
+
+## Overview
+
+A three-layer notification system: NotificationsEngine (client WebSocket with event subscriptions), NotificationHub (per-user Durable Object broadcasting to all connected tabs), and NotificationTriggers (server-side delivery with WebSocket-first, FCM-fallback strategy). Notifications flow in real-time to all open tabs; when the user is offline, FCM push notifications deliver instead.
+
+---
+
+## Implementation
+
+### NotificationsEngine (Client)
+
+**File**: `src/lib/notifications/notifications-engine.ts`
+
+```typescript
+type NotificationEventType = 'notification' | 'notification_read' | 'notification_removed'
+                            | 'unread_count' | 'connection_change'
+
+class NotificationsEngine {
+  private ws: WebSocket | null = null
+  private handlers: Map<NotificationEventType, Set<EventHandler>> = new Map()
+  private reconnectAttempts = 0
+  private maxReconnectAttempts = 10
+  private reconnectDelay = 1000
+  private intentionalClose = false
+
+  connect() {
+    const protocol = location.protocol === 'https:' ? 'wss:' : 'ws:'
+    this.ws = new WebSocket(`${protocol}//${location.host}/api/notifications-ws`)
+    this.ws.onopen = () => { this.reconnectAttempts = 0; this.emit('connection_change', { connected: true }) }
+    this.ws.onmessage = (e) => { const data = JSON.parse(e.data); this.emit(data.type, data) }
+    this.ws.onclose = () => { this.emit('connection_change', { connected: false }); this.attemptReconnect() }
+  }
+
+  on<T extends NotificationEventType>(event: T, handler: EventHandler<T>): () => void {
+    if (!this.handlers.has(event)) this.handlers.set(event, new Set())
+    this.handlers.get(event)!.add(handler)
+    return () => { this.handlers.get(event)?.delete(handler) }  // Unsubscribe
+  }
+
+  disconnect() { this.intentionalClose = true; this.ws?.close() }
+}
+```
+
+Backoff: `1000 * 2^(attempt-1)` — 1s, 2s, 4s, ... 512s, then give up after 10 attempts.
+
+### NotificationHub (Server — Durable Object)
+
+**File**: `src/durable-objects/NotificationHub.ts`
+
+```typescript
+class NotificationHub extends DurableObject {
+  private sessions: Set<WebSocket> = new Set()
+
+  async fetch(request: Request) {
+    if (url.pathname === '/broadcast') {
+      const event = await request.json()
+      this.broadcast(event)  // Send to all connected tabs
+      return new Response('ok')
+    }
+    if (url.pathname === '/connected') {
+      return Response.json({ connected: this.sessions.size > 0, count: this.sessions.size })
+    }
+    // WebSocket upgrade
+    const [client, server] = Object.values(new WebSocketPair())
+    this.ctx.acceptWebSocket(server)
+    this.sessions.add(server)
+    return new Response(null, { status: 101, webSocket: client })
+  }
+
+  private broadcast(event: NotificationEvent) {
+    for (const ws of this.sessions) {
+      try { ws.send(JSON.stringify(event)) }
+      catch { this.sessions.delete(ws) }  // Clean dead connections
+    }
+  }
+}
+```
+
+One DO instance per user (`idFromName(userId)`). Push-only channel — clients don't send messages.
+
+### NotificationTriggers (Delivery Strategy)
+
+**File**: `src/services/notification-triggers.service.ts`
+
+```typescript
+private static async deliver(recipientId, notification, pushData?, env?) {
+  if (env) {
+    const connected = await NotificationHubService.isUserConnected(env, recipientId)
+    if (connected) {
+      // In-app: WebSocket only (updates bell badge instantly)
+      await NotificationHubService.pushNotification(env, recipientId, notification)
+      return
+    }
+  }
+  // Offline: FCM push notification
+  await FcmService.sendToUser(recipientId, { title: notification.title, body: notification.message })
+}
+```
+
+### Multi-Tab Sync
+
+When any tab marks a notification as read:
+1. API updates Firestore
+2. API broadcasts `notification_read` to NotificationHub
+3. Hub sends to ALL connected tabs
+4. Each tab's `engine.on('notification_read')` decrements unread count
+
+### Component Integration
+
+```typescript
+function NotificationBell() {
+  const [unreadCount, setUnreadCount] = useState(0)
+  const engineRef = useRef<NotificationsEngine | null>(null)
+
+  useEffect(() => {
+    if (!user?.uid) return
+    const engine = new NotificationsEngine(user.uid)
+
+    engine.on('notification', () => setUnreadCount(c => c + 1))
+    engine.on('notification_read', () => setUnreadCount(c => Math.max(0, c - 1)))
+    engine.on('notification_removed', () => refetchCount())
+
+    engine.connect()
+    engineRef.current = engine
+    return () => engine.disconnect()
+  }, [user?.uid])
+}
+```
+
+---
+
+## Checklist
+
+- [ ] One NotificationHub DO per user (`idFromName(userId)`)
+- [ ] Engine `on()` returns unsubscribe function — call it on unmount
+- [ ] Delivery checks WebSocket connectivity first, falls back to FCM
+- [ ] API endpoints broadcast changes for multi-tab sync
+- [ ] Push-only WebSocket — clients receive, never send
+
+---
+
+**Status**: Stable
+**Last Updated**: 2026-03-14
+**Contributors**: Community

package/agent/patterns/tanstack-cloudflare.oauth-token-refresh.md

@@ -0,0 +1,90 @@
+# OAuth Token Refresh Queue
+
+**Category**: Architecture
+**Applicable To**: Proactive OAuth credential rotation with cron-driven queue processing and per-provider refresh logic
+**Status**: Stable
+
+---
+
+## Overview
+
+A Firestore-backed queue system for proactive OAuth token refresh. After OAuth callback, credentials are enqueued with a `next_refresh_at` timestamp (e.g., 10 minutes before expiry). A cron job queries the queue for expiring entries, performs per-provider token rotation (Google refresh_token exchange, Instagram stateless refresh), updates credentials, and re-enqueues with the next refresh time.
+
+---
+
+## Implementation
+
+**File**: `src/services/oauth-refresh.service.ts`
+
+### Queue Entry
+
+```typescript
+interface RefreshQueueEntry {
+  user_id: string
+  provider: string
+  next_refresh_at: string    // ISO timestamp
+  created_at: string
+  updated_at: string
+}
+// Collection: oauth-refresh-queue
+// Document ID: {userId}_{provider}
+```
+
+### Service Methods
+
+```typescript
+class OAuthRefreshService {
+  // Called after OAuth callback — schedule first refresh
+  static async enqueueRefresh(userId, provider, nextRefreshAt): Promise<void>
+
+  // Called on disconnect — remove from queue
+  static async dequeueRefresh(userId, provider): Promise<void>
+
+  // Called by cron — process all expiring credentials
+  static async refreshExpiringCredentials(): Promise<RefreshResult[]>
+}
+```
+
+### Cron Processing Flow
+
+```
+Cron trigger (every minute)
+  → Query: oauth-refresh-queue WHERE next_refresh_at <= now (limit 100)
+  → For each entry:
+      ├─ Load credentials from users/{userId}/credentials/{provider}
+      ├─ Per-provider refresh:
+      │   ├─ Google/YouTube: POST oauth2.googleapis.com/token with refresh_token
+      │   └─ Instagram: GET graph.instagram.com/refresh_access_token
+      ├─ Save new credentials (access_token, expires_at)
+      ├─ Update integration timestamps (last_refreshed_at, next_refresh_at)
+      └─ Re-enqueue with new next_refresh_at
+```
+
+### Per-Provider Timing
+
+| Provider | Refresh Timing | Token Lifetime |
+|---|---|---|
+| Google/YouTube | `expiresIn - 600s` (10 min before) | ~1 hour |
+| Instagram | 50 days | 60 days |
+
+### Error Handling
+
+- Expired/revoked tokens: dequeue + return `{ status: 'failed' }`
+- HTTP errors: log + return `{ status: 'failed', error: httpStatus }`
+- Network errors: log + return `{ status: 'failed' }` (retried next cron cycle)
+
+---
+
+## Checklist
+
+- [ ] OAuth callback enqueues refresh with provider-specific timing
+- [ ] Disconnect dequeues the entry
+- [ ] Cron processes max 100 entries per cycle
+- [ ] Failed refreshes are dequeued (user must re-authenticate)
+- [ ] Successful refreshes re-enqueue with next timing
+
+---
+
+**Status**: Stable
+**Last Updated**: 2026-03-14
+**Contributors**: Community