fix(org): favicon fallback, OG logo styling, and Discord embed CDN URLs (#714)

* fix(org): serve OG images from CDN for Discord embeds

Discord times out on slow dynamic OG generation (~3-5s). Persist generated
images to R2, point meta tags at the media CDN, and warm the API endpoint
on org-site page loads so crawlers get a fast static PNG URL.

Co-authored-by: Rotimi Best <[email protected]>

* docs: add org-site Open Graph and favicon guides

Document user-facing sharing behavior and contributor architecture
for dynamic OG images, favicon fallback, R2/CDN caching, and embed
cache invalidation.

Co-authored-by: Rotimi Best <[email protected]>

* fix(org-site): address PR review on OG CDN fallback and docs

- Fall back to API OG URL when CDN object is not yet available (HEAD check)
- Cancel warm-fetch response body to avoid connection pool exhaustion
- Align tenant-router OG edge cache TTL with one-hour API revalidation
- Fix favicon docs navigation and add Custom Domain tab screenshot
- Replace Chiberry Artistry example with AI Academy

Co-authored-by: Rotimi Best <[email protected]>

* fix(org-site): accept docker hostnames for OG warm URL

Use isValidHttpUrl for PRIVATE_SERVER_URL so internal values like
http://api:3081 work for SSR warm fetches in Docker Compose.

Co-authored-by: Rotimi Best <[email protected]>

---------

Co-authored-by: Cursor Agent <[email protected]>
Co-authored-by: Rotimi Best <[email protected]>

apps/api/src/services/org/og-cache.ts

@@ -0,0 +1,86 @@
+import { GetObjectCommand, HeadObjectCommand } from '@aws-sdk/client-s3';
+
+import { getStorageConfig, getS3Client } from '@cio/core/config/storage';
+import { uploadToS3 } from '@cio/core/utils/s3';
+import { getOrgSiteOgObjectKey } from '@cio/utils/org-site/og-public-url';
+
+const OG_ETAG_METADATA_KEY = 'og-etag';
+
+export function getOrgSiteOgPublicUrl(siteName: string): string | null {
+  const mediaPublicBaseUrl = getStorageConfig().mediaPublicBaseUrl;
+  if (!mediaPublicBaseUrl) {
+    return null;
+  }
+
+  return `${mediaPublicBaseUrl.replace(/\/$/, '')}/${getOrgSiteOgObjectKey(siteName)}`;
+}
+
+async function readCachedOrgSiteOgBuffer(siteName: string, etag: string): Promise<Buffer | null> {
+  const config = getStorageConfig();
+  const key = getOrgSiteOgObjectKey(siteName);
+
+  try {
+    const head = await getS3Client().send(
+      new HeadObjectCommand({
+        Bucket: config.bucketMedia,
+        Key: key
+      })
+    );
+
+    if (head.Metadata?.[OG_ETAG_METADATA_KEY] !== etag) {
+      return null;
+    }
+
+    const object = await getS3Client().send(
+      new GetObjectCommand({
+        Bucket: config.bucketMedia,
+        Key: key
+      })
+    );
+
+    const body = object.Body;
+    if (!body) {
+      return null;
+    }
+
+    const bytes = await body.transformToByteArray();
+    return Buffer.from(bytes);
+  } catch {
+    return null;
+  }
+}
+
+export async function persistOrgSiteOgImage(siteName: string, buffer: Buffer, etag: string): Promise<string | null> {
+  const config = getStorageConfig();
+  const publicUrl = getOrgSiteOgPublicUrl(siteName);
+  if (!publicUrl) {
+    return null;
+  }
+
+  const uploadResult = await uploadToS3({
+    Bucket: config.bucketMedia,
+    Key: getOrgSiteOgObjectKey(siteName),
+    Body: buffer,
+    ContentType: 'image/png',
+    CacheControl: 'public, max-age=3600, stale-while-revalidate=86400',
+    Metadata: {
+      [OG_ETAG_METADATA_KEY]: etag
+    }
+  });
+
+  if (!uploadResult.success) {
+    console.error('persistOrgSiteOgImage error:', uploadResult.error);
+    return null;
+  }
+
+  return publicUrl;
+}
+
+export async function getCachedOrgSiteOgBuffer(siteName: string, etag: string): Promise<Buffer | null> {
+  try {
+    return await readCachedOrgSiteOgBuffer(siteName, etag);
+  } catch (error) {
+    console.error('getCachedOrgSiteOgBuffer error:', error);
+    return null;
+  }
+}

apps/api/src/services/org/og.ts

@@ -7,6 +7,7 @@ import { getActiveOrganizationPlan, getOrganizationBySiteName } from '@cio/db/qu
 import { extractOrgTagline, renderOrgSiteOg } from '@api/utils/org-site-og';
 import { isOrgOnFreePlan } from '@cio/utils/plans';
 import { env } from '@cio/core/config/env';
+import { getCachedOrgSiteOgBuffer, getOrgSiteOgPublicUrl, persistOrgSiteOgImage } from '@api/services/org/og-cache';
 
 const DEFAULT_OG_IMAGE = 'https://brand.cdn.clsrio.com/og/classroomio-opengraph.jpg';
 const OG_VIEWPORT = { width: 1200, height: 630, deviceScaleFactor: 2 } as const;
@@ -20,6 +21,8 @@ export function getOrgSiteOgFallbackImageUrl(): string {
   return DEFAULT_OG_IMAGE;
 }
 
+export { getOrgSiteOgPublicUrl };
+
 function buildOrgSiteOgEtag(payload: {
   siteName: string;
   orgName: string;
@@ -59,8 +62,15 @@ export async function generateOrgSiteOgImage(siteName: string): Promise<{ buffer
     ...renderInput
   });
 
+  const cachedBuffer = await getCachedOrgSiteOgBuffer(siteName, etag);
+  if (cachedBuffer) {
+    return { buffer: cachedBuffer, etag };
+  }
+
   const { html, styles } = renderOrgSiteOg(renderInput);
   const buffer = await getCloudflarePngBuffer(html, styles, OG_VIEWPORT);
 
+  await persistOrgSiteOgImage(siteName, buffer, etag);
+
   return { buffer, etag };
 }