init deployment doc

Squashed commit of the following:

commit 1228a1d15f8ee7dec41d8af456d598173222821b
Author: Lukas Herman <[email protected]>
Date:   Mon Dec 22 22:10:02 2025 -0500

    init chart deployment

Author: lherman-cs

components/mdx/mermaid.tsx

@@ -0,0 +1,60 @@
+'use client';
+
+import { use, useEffect, useId, useState } from 'react';
+import { useTheme } from 'next-themes';
+
+export function Mermaid({ chart }: { chart: string }) {
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  if (!mounted) return;
+  return <MermaidContent chart={chart} />;
+}
+
+const cache = new Map<string, Promise<unknown>>();
+
+function cachePromise<T>(
+  key: string,
+  setPromise: () => Promise<T>,
+): Promise<T> {
+  const cached = cache.get(key);
+  if (cached) return cached as Promise<T>;
+
+  const promise = setPromise();
+  cache.set(key, promise);
+  return promise;
+}
+
+function MermaidContent({ chart }: { chart: string }) {
+  const id = useId();
+  const { resolvedTheme } = useTheme();
+  const { default: mermaid } = use(
+    cachePromise('mermaid', () => import('mermaid')),
+  );
+
+  mermaid.initialize({
+    startOnLoad: false,
+    securityLevel: 'loose',
+    fontFamily: 'inherit',
+    themeCSS: 'margin: 1.5rem auto 0;',
+    theme: resolvedTheme === 'dark' ? 'dark' : 'default',
+  });
+
+  const { svg, bindFunctions } = use(
+    cachePromise(`${chart}-${resolvedTheme}`, () => {
+      return mermaid.render(id, chart.replaceAll('\\n', '\n'));
+    }),
+  );
+
+  return (
+    <div
+      ref={(container) => {
+        if (container) bindFunctions?.(container);
+      }}
+      dangerouslySetInnerHTML={{ __html: svg }}
+    />
+  );
+}

content/deployment.mdx

@@ -1,3 +1,103 @@
 ---
 title: Deployment
 ---
+
+**WIP**
+
+## Deployment Architectures
+
+### 1. Single Node (Quick Start)
+
+Best for testing, demos, or low-traffic internal tools. Caddy handles SSL
+termination and proxies signaling traffic to PulseBeam.
+
+```mermaid
+graph TD
+    User((User)) -- "HTTPS (443)" --> Caddy[Caddy Proxy]
+
+    subgraph Host ["Single VM / Docker Host"]
+        Caddy -- "localhost:3000" --> PB[PulseBeam]
+    end
+
+```
+
+```yaml
+version: "3.8"
+services:
+  pulsebeam:
+    image: ghcr.io/pulsebeamdev/pulsebeam:pulsebeam-v0.3.0
+    restart: unless-stopped
+    network_mode: "host"
+
+  caddy:
+    image: caddy:2
+    restart: unless-stopped
+    network_mode: "host"
+    volumes:
+      - caddy_data:/data
+    command:
+      - caddy
+      - reverse-proxy
+      - --from
+      - demo.pulsebeam.dev
+      - --to
+      - localhost:3000
+
+volumes:
+  caddy_data:
+```
+
+### 2. Multi-Node (Production/High Availability)
+
+For production environments requiring high availability, we recommend replacing
+Caddy with HAProxy. The reverse proxy must be configured with consistent hashing
+to ensure each participant connects to the correct node.
+
+In the future, we will remove this limitation by allowing a single room to be
+handled by multiple nodes.
+
+```mermaid
+graph TD
+    %% Styling
+    classDef haproxy fill:#fdfdfd,stroke:#005c94,stroke-width:2px;
+    classDef sfu fill:#f9f9f9,stroke:#333,stroke-width:2px;
+
+    Client((Client)) -- "HTTPS" --> CLB[Cloud Load Balancer]
+
+    subgraph HA_Layer [HAProxy Fleet]
+        HA1[HAProxy 1]
+        HA2[HAProxy 2]
+    end
+
+    subgraph SFU_Fleet [PulseBeam SFU Fleet]
+        direction LR
+        PB1[Node A]
+        PB2[Node B]
+        PB3[Node C]
+    end
+
+    CLB --> HA1
+    CLB --> HA2
+
+    %% Logical routing
+    HA1 -. "Hash(Room-ID)" .-> PB1
+    HA2 -. "Hash(Room-ID)" .-> PB1
+    HA1 -. "Hash(Room-ID)" .-> PB3
+
+    class HA1,HA2 haproxy;
+    class PB1,PB2,PB3 sfu;
+```
+
+## Port & Firewall Requirements
+
+| Port     | Protocol | Traffic | Scope    | Purpose                           |
+| -------- | -------- | ------- | -------- | --------------------------------- |
+| **443**  | **UDP**  | Inbound | Public   | ICE over UDP                      |
+| **443**  | **TCP**  | Inbound | Public   | ICE over TCP fallback             |
+| **3000** | **TCP**  | Inbound | Internal | Proxied HTTP signaling            |
+| **6060** | **TCP**  | Inbound | Private  | Metrics, health checks, and pprof |
+
+> **Note on Networking:** `network_mode: "host"` is required to eliminate the
+> overhead of Container’s network virtualization. For high-throughput real-time
+> traffic, removing NAT indirection is critical for performance and ensures the
+> SFU can correctly discover its public IP for ICE candidate gathering.

mdx-components.tsx

@@ -1,9 +1,11 @@
 import defaultMdxComponents from 'fumadocs-ui/mdx';
+import { Mermaid } from '@/components/mdx/mermaid';
 import type { MDXComponents } from 'mdx/types';
 
 export function getMDXComponents(components?: MDXComponents): MDXComponents {
   return {
     ...defaultMdxComponents,
+    Mermaid,
     ...components,
   };
 }