While real-time collaboration makes sense for shared whiteboards like Miro or Figma, it introduces catastrophic friction when applied to enterprise system architecture diagrams and technical presentations:

1. Strict Data Sovereignty & Zero-Trust Policies: Enterprise architects frequently document mission-critical banking ledgers, military-grade IAM hierarchies, or air-gapped VPC network topologies. Legal, compliance, and infosec teams strictly prohibit uploading these unreleased architectures to third-party SaaS cloud storage.
2. The Mandatory Auth Friction Barrier: Requiring engineers or directors to create an account, verify an email, and configure SSO just to inspect a 4K architecture canvas kills presentation momentum.
3. The Fragile Conference Wi-Fi Trap: When presenting to clients, executives, or at tech conferences, relying on an active internet connection to stream high-resolution diagram textures and synchronized audio tracks is a recipe for public failure.

To solve this, we architected FocusFlow—an open-source technical presentation engine—around a strict Local-First, Zero-Cloud Data Sovereignty paradigm.

In this article, we break down our client-side storage architecture: why localStorage and Base64 fail at scale, how to design an $O(1)$ dual-tier IndexedDB engine for multi-megabyte binary assets, how to defend against browser storage eviction (WebKit ITP 7-day rule), and how our direct-to-S3 presigned promotion pipeline bridges local drafts to edge CDN distribution.

+-------------------------------------------------------------------------------+
|                       FocusFlow Dual-Mode Storage Engine                      |
+-------------------------------------------------------------------------------+
|                                                                               |
|  [ MODE A: Local-First / Zero Telemetry ]                                     |
|  +-------------------------+     +-----------------------------------------+  |
|  |   IndexedDB Metadata    |     |          IndexedDB Binary Blobs         |  |
|  |   focusflow_project_idx |     |          focusflow_project_data_*       |  |
|  |   (Sub-10ms O(1) Index) |     | (4K Canvas Bitmaps & WebM Audio Tracks) |  |
|  +-------------------------+     +-----------------------------------------+  |
|               |                                       |                       |
|               +-------------------+-------------------+                       |
|                                   |                                           |
|                     [ User-Triggered Cloud Promotion ]                        |
|                                   |                                           |
|                                   v                                           |
|  [ MODE B: Edge CDN & Direct-to-S3 Binary Streaming ]                         |
|  +---------------------+      +---------------------+      +---------------+  |
|  |   Platform Assets   | ---> | Direct Binary Stream| ---> | Cloudflare R2 |  |
|  |   API (Gateway)     |      | Presigned URL PUT   |      | Global Anycast|  |
|  +---------------------+      +---------------------+      +---------------+  |
|                                                                               |
+-------------------------------------------------------------------------------+

1. The Browser Storage Reality: Why LocalStorage and Base64 Fail at Scale

The most common shortcut in early frontend prototypes is storing application state in localStorage or sessionStorage by serializing state trees to JSON strings:

// ⚠️ ANTI-PATTERN: Blocking the main thread with JSON serialization of binary data
localStorage.setItem(`project_${id}`, JSON.stringify({
  dsl: canvasDSL,
  backdropBase64: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...'
}));

In an infinite canvas application dealing with 4K/8K architecture diagrams and multi-minute audio narration tracks, this approach collapses across three critical failure modes:

1.1 The Synchronous 5MB Ceiling

localStorage is strictly limited to 5MB (or 10MB in select Chromium builds) per origin. A single 4K retina export of an enterprise architecture map typically ranges between 3.5MB and 8MB. Attempting to save a single high-resolution diagram immediately throws an unrecoverable DOMException: QUOTA_EXCEEDED_ERR.

More critically, localStorage operations are fully synchronous and execute on the browser's main thread. Invoking JSON.stringify() on a 5MB payload blocks the JavaScript event loop for 80ms to 250ms, causing noticeable frame drops, stuttering zoom transitions, and broken 60fps/120Hz ProMotion animation loops.

1.2 The Base64 Memory Tax (+33.3% Bloat)

Encoding binary files into ASCII Base64 strings incurs a mathematically unavoidable 33.3% size penalty:

$$\text{Base64 Size} = \lceil \frac{N}{3} \rceil \times 4 \approx 1.333 \times N$$

A 9MB lossless PNG explodes into 12MB of raw UTF-16 character data in memory. When parsed into JavaScript engine heap memory, strings often consume 2 bytes per character, doubling the actual RAM consumption to ~24MB just for the storage payload representation.

1.3 V8 & JavaScriptCore String Allocation Ceilings

Modern JavaScript engines enforce strict caps on maximum contiguous string lengths (typically 512MB in 64-bit V8, but historically as low as 256MB or constrained by single-object allocation limits on mobile WebKit). When generating single-file presentation bundles with multiple embedded audio clips and 4K textures, serializing everything into a single in-memory JSON string triggers RangeError: Invalid string length or causes tab crashes under iOS Safari's low-memory watchdog.

1.4 The Solution: IndexedDB & The Structured Clone Algorithm

Unlike localStorage, IndexedDB is an asynchronous transactional object store that natively supports the Structured Clone Algorithm.

Instead of converting binary assets into text strings, IndexedDB stores native Blob, ArrayBuffer, and File handles as direct, disk-backed references. Binary data is streamed directly to and from browser disk storage with zero string-encoding overhead, zero main-thread blocking, and negligible heap memory footprint.

2. Designing an O(1) Dual-Tier Storage Engine

When users open FocusFlow, the dashboard must load within milliseconds, displaying a gallery of past architectural presentations with titles, scene counts, timestamps, and thumbnails.

If each project record in IndexedDB contains the full 4K background diagram and multiple audio blobs, querying the project list would force the browser to deserialize gigabytes of binary data from disk into memory, destroying cold-start performance.

To guarantee $O(1)$ startup latency regardless of project count, we decoupled storage into a Dual-Tier Repository Architecture:

IndexedDB Storage Partitioning:
├── "focusflow_project_index"                  <-- Lightweight Metadata Index (<50KB)
│     [ { id: "p1", title: "Core", sceneCount: 5, thumbnail: "..." }, ... ]
│
├── "focusflow_project_data_proj_17290001"     <-- Full Project Record 1 (12.4MB)
│     ├── dsl: { meta, elements, scenes }
│     ├── imageBlob: Blob (4.2MB PNG)
│     └── sceneAudioBlobs: { "scene-01": Blob (1.1MB WebM), ... }
│
└── "focusflow_project_data_proj_17290002"     <-- Full Project Record 2 (8.1MB)
      ├── dsl: ...
      └── imageBlob: Blob (3.8MB PNG)

2.1 The Repository Interface (IProjectRepository)

We formalized our storage abstraction behind an asynchronous interface, allowing seamless switching between local IndexedDB, mock fixtures for headless testing, and cloud REST backends:

export interface ProjectMetaIndex {
  id: string;
  title: string;
  createdAt: number;
  updatedAt: number;
  sceneCount: number;
  thumbnail?: string; // Ultra-compact 128x72 webp data URL (<4KB)
  isCloud: boolean;
}

export interface ProjectRecord {
  id: string;
  title: string;
  createdAt: number;
  updatedAt: number;
  sceneCount: number;
  dsl: FocusFlowDSL;
  imageBlob?: Blob;
  audioBlob?: Blob;
  sceneAudioBlobs?: Record<string, Blob>;
  thumbnail?: string;
  isCloud: boolean;
}

export interface IProjectRepository {
  readonly storageType: 'indexeddb' | 'cloud' | 'memory';
  listProjects(): Promise<ProjectMetaIndex[]>;
  loadProject(id: string): Promise<ProjectRecord | null>;
  saveProject(record: ProjectRecord): Promise<void>;
  deleteProject(id: string): Promise<void>;
  duplicateProject(id: string): Promise<string>;
}

2.2 Implementing Zero-Overhead Indexing with idb-keyval

Using a lightweight key-value wrapper over IndexedDB (idb-keyval), our IndexedDbStorageAdapter updates the lightweight index in lockstep with the full project shard:

import { get, set, del } from 'idb-keyval';
import type { IProjectRepository, ProjectMetaIndex, ProjectRecord } from './project-repository.interface';

const INDEX_KEY = 'focusflow_project_index';
const PROJECT_PREFIX = 'focusflow_project_data_';

export class IndexedDbStorageAdapter implements IProjectRepository {
  readonly storageType = 'indexeddb' as const;

  // O(1) instantaneous metadata query (< 5ms)
  async listProjects(): Promise<ProjectMetaIndex[]> {
    try {
      const list = await get<ProjectMetaIndex[]>(INDEX_KEY);
      return (list || []).map((item) => ({ ...item, isCloud: false }));
    } catch (err) {
      console.error('[IndexedDb] Failed to read project index:', err);
      return [];
    }
  }

  // Loaded on-demand ONLY when the user enters the active canvas editor
  async loadProject(id: string): Promise<ProjectRecord | null> {
    try {
      const record = await get<ProjectRecord>(`${PROJECT_PREFIX}${id}`);
      if (!record) return null;
      return { ...record, isCloud: false };
    } catch (err) {
      console.error(`[IndexedDb] Failed to load record ${id}:`, err);
      return null;
    }
  }

  async saveProject(record: ProjectRecord): Promise<void> {
    const now = Date.now();
    record.updatedAt = now;

    // 1. Asynchronously persist full project record with binary blobs
    await set(`${PROJECT_PREFIX}${record.id}`, { ...record, isCloud: false });

    // 2. Atomically update the lightweight index
    const index = await this.listProjects();
    const existingIdx = index.findIndex((item) => item.id === record.id);
    const meta: ProjectMetaIndex = {
      id: record.id,
      title: record.title,
      createdAt: record.createdAt,
      updatedAt: now,
      sceneCount: record.sceneCount,
      thumbnail: record.thumbnail,
      isCloud: false,
    };

    if (existingIdx >= 0) {
      index[existingIdx] = meta;
    } else {
      index.unshift(meta);
    }

    await set(INDEX_KEY, index);
  }

  async deleteProject(id: string): Promise<void> {
    await del(`${PROJECT_PREFIX}${id}`);
    const index = await this.listProjects();
    await set(INDEX_KEY, index.filter((item) => item.id !== id));
  }
}

3. Navigating Quotas, Eviction Policies, and Durable Storage

One of the most dangerous myths in frontend development is that IndexedDB is permanent. In reality, browsers treat client-side storage as a dynamic, evictable cache unless explicitly granted persistent status.

3.1 WebKit ITP (7-Day Eviction Rule)

On Safari (macOS and iOS), WebKit's Intelligent Tracking Prevention (ITP) enforces an aggressive eviction policy: if a user does not interact with an origin for 7 days after navigating via script or third-party referrers, all client-side script-writable storage—including IndexedDB—is liable to be completely deleted.

3.2 Chromium Pool-Based LRU Eviction

Chromium-based browsers allocate storage based on total available hard drive capacity:

• An origin is typically granted up to 60% of total disk space (or 20% on shared pools).
• When the device encounters low disk space pressure, Chromium groups origins into an LRU (Least Recently Used) list and silently wipes IndexedDB data starting from the oldest inactive origin until sufficient disk space is reclaimed.

3.3 Requesting Persistent Storage with navigator.storage.persist()

To prevent unexpected data loss, FocusFlow transparently inspects storage quota and requests Durable (Persistent) Storage upon the first project save:

export async function ensureDurableStorage(): Promise<{
  persisted: boolean;
  quotaMB: number;
  usageMB: number;
}> {
  if (!navigator.storage || !navigator.storage.estimate) {
    return { persisted: false, quotaMB: 0, usageMB: 0 };
  }

  // 1. Inspect current quota and disk consumption
  const estimate = await navigator.storage.estimate();
  const quotaMB = Math.round((estimate.quota || 0) / (1024 * 1024));
  const usageMB = Math.round((estimate.usage || 0) / (1024 * 1024));

  // 2. Check if the origin already has persistent storage permissions
  let isPersisted = await navigator.storage.persisted?.();

  // 3. If not persistent, request durability from the browser
  if (!isPersisted && navigator.storage.persist) {
    isPersisted = await navigator.storage.persist();
    console.info(`[Storage] Persistent storage granted: ${isPersisted}`);
  }

  return {
    persisted: !!isPersisted,
    quotaMB,
    usageMB,
  };
}

When navigator.storage.persist() returns true:

• Chromium marks the origin as exempt from opportunistic LRU eviction under low-disk conditions.
• Safari preserves data past the 7-day inactivity cliff if the user has bookmarked the page, added it to the home screen (PWA), or explicitly granted permissions.

4. The Mode-A to Mode-B Promotion Pipeline: Direct-to-S3 Presigned Streaming

While Mode-A (Local-First IndexedDB) guarantees 100% data sovereignty and offline operation, users often need to collaborate or share completed presentations with team members or clients.

A naive cloud sync architecture uploads the entire project payload directly to a Node.js/NestJS API endpoint:

[ Browser ] -- (POST /api/projects with 15MB Multipart Body) --> [ Node.js API Gateway ] --> [ AWS S3 / R2 ]

This architecture creates severe bottlenecks:

• Multi-megabyte HTTP request payloads saturate API Gateway concurrency pools.
• Heavy memory allocation spikes trigger garbage collection freezes in Node.js microservices.
• Network upload latency doubles because data is transferred sequentially across two hops.

4.1 The 3-Step Presigned Direct-Upload Architecture

To bypass the API gateway completely, FocusFlow implements a Presigned Direct-to-S3 Promotion Pipeline:

1. Handshake: Request Presigned URL
[ Browser ] -----------------------------------------> [ NestJS API Gateway ]
            <-- Returns { uploadUrl, assetId, publicUrl } --

2. Direct Binary Transfer (Zero Gateway Overhead)
[ Browser ] -- (PUT uploadUrl with raw binary Blob) --> [ Cloudflare R2 / S3 ]
            <-- HTTP 200 OK ---------------------------

3. Two-Phase Commit
[ Browser ] -- (POST /assets/confirm { assetId }) ----> [ NestJS API Gateway ]
            <-- Confirmed Permanent CDN URL -----------

4.2 Implementation: promoteLocalProjectToCloud

Here is the core logic from FocusFlow's production cloud-sync.ts:

import axios from 'axios';
import {
  platformAssetsControllerRequestPresignedUpload,
  platformAssetsControllerConfirmUpload,
} from '@/api/generated/platform-assets/platform-assets';
import { RequestPresignedUploadDtoType } from '@/api/model/requestPresignedUploadDtoType';
import { IndexedDbStorageAdapter } from './indexeddb-storage-adapter';
import { CloudRestStorageAdapter } from './cloud-rest-storage-adapter';
import type { ProjectRecord } from './project-repository.interface';

export async function uploadBlobToCloud(
  blob: Blob,
  filename: string,
  type: RequestPresignedUploadDtoType,
  workspaceId: string,
  projectId?: string,
): Promise<string> {
  const mimeType = blob.type || (type === RequestPresignedUploadDtoType.BACKGROUND_IMAGE ? 'image/png' : 'audio/webm');
  const sizeBytes = blob.size;

  // Step 1: Request presigned upload URL from Platform Assets API
  const presigned = await platformAssetsControllerRequestPresignedUpload({
    workspaceId,
    name: filename,
    mimeType,
    sizeBytes,
    type,
    projectId,
  });

  // Step 2: Stream raw binary directly to S3/R2 (Bypassing API Gateway)
  await axios.put(presigned.uploadUrl, blob, {
    headers: {
      'Content-Type': mimeType,
    },
    // Crucial: Prevent default auth interceptors from adding Authorization tokens to third-party S3 URLs
    transformRequest: [(data) => data],
  });

  // Step 3: Confirm asset upload and register immutable CDN record
  const confirmed = await platformAssetsControllerConfirmUpload({
    workspaceId,
    assetId: presigned.assetId,
  });

  return confirmed.publicUrl || presigned.publicUrl;
}

export async function promoteLocalProjectToCloud(
  localProjectId: string,
  workspaceId: string,
): Promise<ProjectRecord> {
  const localAdapter = new IndexedDbStorageAdapter();
  const cloudAdapter = new CloudRestStorageAdapter();

  const record = await localAdapter.loadProject(localProjectId);
  if (!record) throw new Error(`Project ${localProjectId} not found in local IndexedDB`);

  // 1. Resolve and upload background architecture image if stored locally
  let resolvedImageBlob = record.imageBlob;
  const assetUrl = record.dsl.asset?.url;
  if (!resolvedImageBlob && assetUrl?.startsWith('blob:')) {
    const resp = await fetch(assetUrl);
    if (resp.ok) resolvedImageBlob = await resp.blob();
  }

  if (resolvedImageBlob && record.dsl.asset) {
    const cloudImageUrl = await uploadBlobToCloud(
      resolvedImageBlob,
      'backdrop-architecture.png',
      RequestPresignedUploadDtoType.BACKGROUND_IMAGE,
      workspaceId,
      record.id,
    );
    // Rewrites ephemeral blob: URL to permanent Anycast CDN URL
    record.dsl.asset.url = cloudImageUrl;
    record.imageBlob = undefined; // Free local binary memory
  }

  // 2. Upload individual scene audio narration blobs
  if (record.sceneAudioBlobs) {
    for (const [sceneId, audioBlob] of Object.entries(record.sceneAudioBlobs)) {
      const cloudAudioUrl = await uploadBlobToCloud(
        audioBlob,
        `narration-${sceneId}.webm`,
        RequestPresignedUploadDtoType.AUDIO_NARRATION,
        workspaceId,
        record.id,
      );
      const scene = record.dsl.scenes.find((s) => s.id === sceneId);
      if (scene) scene.audioUrl = cloudAudioUrl;
    }
    record.sceneAudioBlobs = undefined;
  }

  // 3. Persist pure structured DSL to cloud API
  record.isCloud = true;
  await cloudAdapter.saveProject(record);

  return record;
}

5. Air-Gapped Distribution: The Single-File Standalone Exporter

What if your customer operates in an air-gapped facility with zero WAN access? Or what if an architect needs to submit a portfolio review on Upwork or attach a presentation to an email?

To provide ultimate data portability, FocusFlow features an Offline Single-File Exporter:

# Compiles the full presentation into a standalone HTML file (< 5MB)
focusflow export --input project.json --output hms_presentation.html --standalone

5.1 Architecture of a Standalone Single-File Bundle

The resulting .html file is 100% self-contained:

1. Inlined Canvas Player Runtime: A stripped-down, zero-dependency version of our 60fps frustum camera engine and canvas renderer (~180KB minified).
2. Inlined Structured DSL: The scene timelines, camera coordinates, element boxes, and callouts embedded in a <script id="focusflow-dsl" type="application/json"> block.
3. Inlined 4K Textures & Audio Blobs: Binary assets serialized using chunked Base64 buffers and converted to object URLs via URL.createObjectURL(new Blob([...])) upon document initialization.

Because the output is a single standard HTML document:

• It opens instantly in any browser by double-clicking.
• It requires no local web server (file:// protocol compatible).
• It bypasses CORS restrictions entirely.
• It can be archived in Git repositories or stored permanently on cold-storage USB media.

6. Architecture Checklist: Best Practices for Local-First Web Apps

Building high-performance local-first web applications requires breaking free from traditional cloud-first assumptions. Here is the operational checklist we enforce in FocusFlow:

Conclusion & Resources

By putting Local-First Architecture and Data Sovereignty at the core of our technical design, FocusFlow gives developers and architects complete ownership of their technical assets. You get the fluid, 60fps interactivity of a modern web canvas without sacrificing data privacy, offline reliability, or enterprise compliance.

• 🚀 FocusFlow Web Studio: https://focusflow.tumio.site
• 💻 Open-Source GitHub Repository: https://github.com/tumio-ltd/focusflow
• 📖 Architecture Deep Dive (Part 1 - 60fps Frustum Camera): https://tumio.hashnode.dev/building-a-60fps-canvas-frustum-camera-for-4k-system-architecture-presentations

When presenting intricate microservices, Kubernetes topologies, or distributed event buses to engineering teams, static diagrams often fail to convey runtime flows, while traditional slide decks lack the spatial pan-and-zoom context needed for architectural depth.

We built FocusFlow—an open-source, canvas-native presentation studio designed specifically for high-framerate system architecture walkthroughs. In this post, we'll dive into the math, architecture, and rendering performance optimizations behind FocusFlow's custom Canvas 2D frustum camera.

1. The Architectural Challenge: Why Not WebGL or DOM?

Modern web presentation tools usually take one of two approaches:

1. DOM/SVG-heavy trees: Each box or arrow is an HTML element or SVG node. While flexible and easy to style with CSS, animating 500+ elements across 4K displays quickly chokes layout passes and composition layers, causing frame drops below 30fps.

2. Heavyweight 3D WebGL (Three.js/Babylon): Excellent for 3D shaders and meshes, but overkill for crisp 2D vector diagrams, text anti-aliasing, and sub-pixel snapping. It also introduces substantial memory overhead on lower-end laptops.

We chose pure Canvas 2D with hardware-accelerated offscreen composition, governed by a virtual camera model that treats system architecture diagrams as continuous spatial worlds.

2. The Frustum Camera & Smooth Matrix Interpolation

Instead of moving each diagram node individually, the camera calculates a global 2D affine transformation matrix for each frame.

Given a target node bounding box \(B = {x_{min}, y_{min}, x_{max}, y_{max}}\) and viewport dimensions \(V = {W, H}\), the camera solves for optimal padding and bounding center:

export interface BoundingBox {
  minX: number;
  minY: number;
  maxX: number;
  maxY: number;
}

export interface ViewportSize {
  width: number;
  height: number;
}

export function computeTargetFrustum(box: BoundingBox, viewport: ViewportSize, padding = 0.15): { x: number; y: number; zoom: number } {
  const boxWidth = box.maxX - box.minX;
  const boxHeight = box.maxY - box.minY;
  const centerX = (box.minX + box.maxX) / 2;
  const centerY = (box.minY + box.maxY) / 2;

  const availableWidth = viewport.width * (1 - padding * 2);
  const availableHeight = viewport.height * (1 - padding * 2);

  const zoomX = availableWidth / Math.max(boxWidth, 1);
  const zoomY = availableHeight / Math.max(boxHeight, 1);
  const zoom = Math.min(zoomX, zoomY, 3.0); // Clamped to max 3.0x zoom

  return {
    x: viewport.width / 2 - centerX * zoom,
    y: viewport.height / 2 - centerY * zoom,
    zoom,
  };
}

Critically Damped Spring Interpolation

Standard linear (lerp) interpolation feels robotic, while CSS ease curves can feel disconnected when interrupted mid-flight by user interactions. FocusFlow employs a critically damped spring physics solver for smooth camera transitions:

export class SpringCamera {
  private currentX = 0;
  private currentY = 0;
  private currentZoom = 1;

  private targetX = 0;
  private targetY = 0;
  private targetZoom = 1;

  private vx = 0;
  private vy = 0;
  private vZoom = 0;

  private readonly stiffness = 180;
  private readonly damping = 26;

  public update(dt: number) {
    // Spring physics step
    const ax = this.stiffness * (this.targetX - this.currentX) - this.damping * this.vx;
    const ay = this.stiffness * (this.targetY - this.currentY) - this.damping * this.vy;
    const az = this.stiffness * (this.targetZoom - this.currentZoom) - this.damping * this.vZoom;

    this.vx += ax * dt;
    this.vy += ay * dt;
    this.vZoom += az * dt;

    this.currentX += this.vx * dt;
    this.currentY += this.vy * dt;
    this.currentZoom += this.vZoom * dt;
  }
}

3. Spatial Boundary Caching & Cull Optimization

Rendering complex architecture diagrams at 60fps requires aggressive view-frustum culling. Every node whose bounding box lies outside the visible viewport is omitted from the draw pass:

export function isNodeVisible(nodeBox: BoundingBox, viewportBox: BoundingBox): boolean {
  return !(
    nodeBox.maxX < viewportBox.minX ||
    nodeBox.minX > viewportBox.maxX ||
    nodeBox.maxY < viewportBox.minY ||
    nodeBox.minY > viewportBox.maxY
  );
}

With spatial partitioning (R-tree), scene query times drop from \(\mathcal{O}(N)\) to \(\mathcal{O}(\log N)\), keeping the total per-frame render loop well under 8ms even with thousands of architecture components.

4. Try It Live & Source Code

FocusFlow is fully open-source under MIT:

• Live Interactive Demo: https://focusflow.tumio.site

• GitHub Repository: https://github.com/tumio-ltd/focusflow

We are actively developing timeline markers and audio-sync narration features for upcoming v1.1 releases. We'd love your thoughts and feedback!