Forem: Emmanuel

Your Financial Data Should Live on Your Device. Here Is the Architecture That Makes That Possible.

Emmanuel — Fri, 27 Mar 2026 21:25:07 +0000

How a carefully layered architecture delivers instant offline access, end-to-end privacy, and optional cloud sync, without asking you to choose between them.

Estimated reading time: 10 minutes

The Privacy Paradox of Financial Apps

Every financial app on the market asks you the same question on page one: "Create an account." Before you can track a single expense, you hand over an email address. Before you can set a savings goal, your data lands on someone else's server. You are trusting that company's security practices, their terms of service, their business model, and their continued existence — all to do basic arithmetic with your own money.

Most apps treat this as inevitable. A login wall is the cost of admission. Your data goes to their database. You hope for the best.

Talliofi refuses that deal. Your data never leaves your device unless you explicitly ask it to. No account. No telemetry. No analytics. If you want cloud sync across devices, you bring your own Supabase instance. If you do not, everything stays local. Forever.

This sounds simple in a pitch deck. In code, it requires an architecture that most web apps never need to consider. This article is a complete walkthrough of how we built it.

What "Local-First" Actually Means

The local-first software movement, articulated by Ink & Switch in 2019, makes one core argument: the best software keeps your data on your device and treats sync as a convenience, not a requirement. The app works on a plane. It works when your connection drops mid-session. It works ten years from now, even if the company behind it disappears.

For Talliofi, local-first is not a philosophy; it is a set of concrete engineering constraints:

No login required to use the full app. Open it, enter data, close the tab, come back next month. Everything is there.
The device is the source of truth. IndexedDB, not a server, holds the canonical state.
Sync is additive, not required. The app does not degrade without it.

This inverts the standard web app model. In a typical application, the server is the source of truth and the client is a view layer. In Talliofi, the client is the source of truth. The server, if present at all, is a backup.

Layer 1: IndexedDB as the Source of Truth

Talliofi uses Dexie, a thin TypeScript-friendly wrapper over IndexedDB, as its primary database. The schema spans 11 tables:

export class TalliofiDatabase extends Dexie {
  plans!: Table<Plan, string>;
  expenses!: Table<ExpenseItem, string>;
  goals!: Table<Goal, string>;
  assets!: Table<Asset, string>;
  liabilities!: Table<Liability, string>;
  snapshots!: Table<MonthlySnapshot, string>;
  netWorthSnapshots!: Table<NetWorthSnapshot, string>;
  changelog!: Table<ChangeLogEntry, string>;
  recurringTemplates!: Table<RecurringTemplate, string>;
  attachments!: Table<ExpenseAttachment, string>;
  vault!: Table<EncryptedVaultRecord, string>;
}

The schema is versioned. Dexie runs migrations sequentially when the schema version increases:

db.version(1).stores({ plans: 'id, name', expenses: 'id, planId', /* ... */ });
// ...
db.version(9).stores({
  // Adds compound index for date-range queries — critical for reports
  expenses: 'id, planId, [planId+transactionDate]',
});

That [planId+transactionDate] compound index in version 9 is a good example of performance-driven schema evolution. Expense reports filter by plan and date range constantly. Without the compound index, every date-range query scans all expenses for a plan. With it, IndexedDB finds the exact range in a single lookup. Schema versions let you add this kind of optimization incrementally, without a big-bang migration.

The result: opening Talliofi after a week away feels instant. No API call, no loading spinner, no authentication handshake. IndexedDB serves data in milliseconds.

Layer 2: TanStack Query as a Smart Cache, Not the Source of Truth

Here is the architectural distinction that most React apps get wrong: TanStack Query is a cache, not a database.

In a typical React + React Query app:

Component -> useQuery -> fetch from API -> display

In Talliofi:

Component -> useQuery -> read from Dexie -> display

The query function talks to IndexedDB, not a network endpoint. TanStack Query still earns its keep: caching, deduplication, background refresh, and stale-time management are genuinely useful even when the data source is local:

export function useExpensesByDateRange(
  planId: string | undefined,
  startDate: string,
  endDate: string,
) {
  return useQuery({
    queryKey: queryKeys.expensesRange(planId!, startDate, endDate),
    queryFn: () =>
      getExpenseRepo().getByPlanIdAndDateRange(planId!, startDate, endDate),
    enabled: !!planId && !!startDate && !!endDate,
    staleTime: PLAN_DATA_STALE_TIME_MS,
  });
}

The staleTime constant means Talliofi does not re-read from IndexedDB on every render. Fresh data serves from the in-memory cache. When a mutation writes to IndexedDB, it invalidates the relevant query keys, triggering a re-read. The component always shows the latest data without polling.

This separation is also what makes the next layer possible.

Layer 3: The Repo Router, One Interface, Three Backends

The central abstraction that makes local-first + optional sync work is the repo router. Every data access in the entire app goes through a function like this:

function isCloudMode(): boolean {
  const mode = useSyncStore.getState().storageMode;
  return mode === 'cloud' || mode === 'encrypted';
}

export function getExpenseRepo(): typeof expenseRepo {
  return isCloudMode() ? supabaseExpenseRepo : expenseRepo;
}

Components and hooks never import a specific repo directly. They call getExpenseRepo(). The function returns the right implementation based on the user's chosen storage mode. Three modes exist:

Mode	Backend	When to use
`local`	Dexie only	Privacy-first, no cloud account needed
`cloud`	Supabase (unencrypted)	Multi-device sync, standard cloud trust
`encrypted`	Supabase (AES-256-GCM)	Multi-device sync, zero-knowledge privacy

The Dexie repo and the Supabase repo implement the same interface. Adding a new entity type means writing a new Dexie repo, a new Supabase repo, and registering both in the router. The components never change.

The Data Flow

User action (add expense)
        |
        v
useCreateExpense() hook
        |
        v
getExpenseRepo() --> local?  --> expenseRepo (Dexie)
                 \-- cloud?  --> supabaseExpenseRepo (Supabase)
        |
        v
TanStack Query cache invalidated
        |
        v
UI re-renders with fresh data
        |
        v (async, fire-and-forget)
changelog table --> sync engine --> Supabase (on next push)

The sync engine runs in the background. A successful write to Dexie also writes to the local changelog. The sync engine periodically pushes changelog entries to Supabase and pulls remote changes. The UI never waits for sync to complete, local writes are instant.

Layer 4: The Sync Engine, Changelog Over Full-Table Sync

Syncing all data on every cycle works for small datasets but collapses as data grows. Talliofi uses a changelog-based approach instead.

Every create, update, and delete operation appends an entry to a local changelog table:

interface ChangeLogEntry {
  id: string;
  planId: string;
  entityType: 'expense' | 'bucket' | 'plan' | 'goal' | 'asset' | 'liability';
  entityId: string;
  operation: 'create' | 'update' | 'delete';
  timestamp: string;
  payload?: string; // Serialized entity data (encrypted if mode is 'encrypted')
}

On sync, the engine pushes only entries newer than the last sync watermark, a timestamp stored per plan. On pull, it fetches remote entries newer than the watermark and applies them locally.

Conflict resolution uses last-writer-wins with a special case for deletes:

if (row.operation === 'delete' && localEntry) {
  await table.delete(row.entity_id); // Delete always wins
} else if (localEntry && localEntry.timestamp >= row.timestamp) {
  continue; // Local is newer, skip remote
} else {
  await table.put(entity); // Apply remote entry
}

This is a deliberate trade-off worth naming. Last-writer-wins is simple and predictable, but concurrent edits from two devices will produce a winner and a loser. For a personal finance app used primarily on one device at a time, this is exactly the right call. CRDTs or operational transforms would add enormous complexity for a conflict profile that almost never occurs in practice.

Layer 5: End-to-End Encryption with Web Crypto API

The encrypted storage mode goes further: payloads are encrypted client-side before they ever reach Supabase. The server stores opaque ciphertext. Even a full database breach yields nothing useful.

The implementation uses only the browser's native Web Crypto API, no external cryptography libraries:

export async function deriveKey(
  password: string,
  salt: Uint8Array,
): Promise<CryptoKey> {
  const encoder = new TextEncoder();
  const keyMaterial = await crypto.subtle.importKey(
    'raw',
    encoder.encode(password),
    'PBKDF2',
    false,
    ['deriveKey'],
  );
  return crypto.subtle.deriveKey(
    {
      name: 'PBKDF2',
      salt,
      iterations: 600_000, // OWASP recommended minimum for SHA-256
      hash: 'SHA-256',
    },
    keyMaterial,
    { name: 'AES-GCM', length: 256 },
    false,
    ['encrypt', 'decrypt'],
  );
}

The encrypted payload structure:

export interface EncryptedPayload {
  iv: string;         // Base64-encoded random IV (unique per encryption)
  ciphertext: string; // Base64-encoded AES-GCM ciphertext (includes auth tag)
  salt: string;       // Base64-encoded salt for key derivation
}

Four design decisions anchor this layer:

600,000 PBKDF2 iterations. OWASP's current recommendation for PBKDF2-SHA-256. This makes brute-force attacks on the password computationally expensive. Key derivation takes a noticeable moment on first login. We accept that cost.

AES-GCM, not AES-CBC. GCM provides authenticated encryption, decryption verifies the ciphertext has not been tampered with. If an attacker modifies stored data, decryption fails loudly rather than silently producing garbage. This matters when untrusted network paths are involved.

No external crypto libraries. The Web Crypto API ships in every modern browser, is implemented in C++ rather than JavaScript, and carries zero supply-chain risk. Depending on crypto-js for security-critical code adds unnecessary attack surface.

"Bring Your Own Supabase." The user provides their own Supabase project URL and anon key. Talliofi never touches a server we control. The user owns the entire backend. This is the strongest possible privacy guarantee short of no sync at all.

The UX Result

The architecture produces a specific, demonstrable user experience:

First load: Fully functional within 200ms. No API call required.
Offline use: Identical to online use. Adding, editing, deleting data, rendering reports — all local.
Return after absence: Open the app after a week and see your data instantly, then sync in the background if enabled.
No account, no friction: New users start planning immediately. Onboarding never asks for an email address.

This experience is only possible because IndexedDB is the source of truth and the network is a sync layer, not a dependency.

What This Architecture Costs

No free lunch. Local-first has real trade-offs, and pretending otherwise would be dishonest.

Storage is bounded. IndexedDB limits vary by browser and device. For a personal finance app with text-based records, this is not a practical concern, years of expenses fit in a few megabytes. Receipt images are a different story. Talliofi stores attachments as base64, which works but is inefficient. A blob-storage backend would be cleaner.

Sync conflicts are possible. Two devices editing the same expense simultaneously will resolve by timestamp. Most users will never notice. Power users who genuinely edit from two devices at once will occasionally see a stale value overwritten. The app surfaces sync status but does not expose conflict details to the user.

Testing is more complex. Code that writes to IndexedDB requires a DOM-capable test environment. Vitest with jsdom handles this, but setup is more involved than mocking a fetch call. The repo abstraction helps, unit tests inject a mock repo, integration tests hit a real in-memory IndexedDB instance.

Migration is manual. Schema migrations in Dexie are code, not SQL. Version 9 has 9 sequential migration steps. Manageable today, but it demands discipline as the schema evolves.

Why This Pattern Scales

The three-mode architecture earns its complexity when you see what it enables for free:

Full offline support: Already there. No extra code needed.
Export/import: Read from Dexie, serialize to JSON/CSV. Works offline.
Multi-plan scenarios: Each plan is an isolated namespace in IndexedDB. Switching plans is instant.
Multi-currency: Exchange rates cached locally. Currency conversion works offline with last-known rates.
Encryption: Wraps the existing Supabase layer. The Dexie layer stays untouched.

Every feature that reads or writes data gets offline support automatically because IndexedDB is always the first stop. The sync engine handles getting changes to the cloud eventually. Features ship faster because the hard problem, "where does the data live?", is already solved.

Start Here

If you are building a web app where data privacy matters, the local-first model is worth the investment. The core pattern is five layers deep, but each layer is straightforward on its own:

IndexedDB (via Dexie) as the source of truth — not the server.
TanStack Query as a cache — with query functions that read from IndexedDB, not fetch from APIs.
A repo interface — implemented by both a local Dexie repo and a remote sync repo.
A routing function — that selects the right repo based on user preference.
A sync engine — that runs in the background, never in the critical path.

The user gets privacy by default and cloud sync as a deliberate choice. That is a better deal than most apps offer. And it is achievable with standard web platform APIs — no proprietary infrastructure, no vendor lock-in, no trust required.

Your data, on your device, on your terms. That should not be a radical idea. But until more apps are built this way, it still is.

Visit Talliofi Website

How a Branded Cents Type Eliminated an Entire Class of Bugs Across 97 Files

Emmanuel — Fri, 27 Mar 2026 21:07:09 +0000

TypeScript branded types turned compile-time into our most reliable financial auditor here is the pattern, the code, and the lessons from deploying it across a real production PWA.

Estimated reading time: 9 minutes

The Penny That Should Not Exist

Open your browser console right now and type 0.1 + 0.2. Go ahead, I will wait.

You got 0.30000000000000004. Not 0.3. Every developer discovers this at some point and shrugs it off. But when you are building software that handles someone's rent payment, their emergency fund, their debt payoff plan that invisible four-quadrillionth of a cent compounds. It hides in running totals. It lurks in tax calculations. It turns a perfectly balanced budget into one that is off by a penny, and the user stares at the screen wondering if they can trust anything your app is telling them.

I hit this wall while building Talliofi, a local-first financial planning PWA built with React 19 and TypeScript. The app handles income, expenses, budgets, goals, net worth tracking, and multi-currency conversion. Money touches every feature. And every feature was a potential floating-point landmine.

The fix was not a library. It was not a dependency. It was twelve lines of TypeScript that now protect 928 occurrences of monetary values across 97 files in the codebase.

Why Floating-Point Arithmetic Hates Your Money

This is not a new problem. IEEE 754 double-precision floating-point numbers cannot represent most decimal fractions exactly. The number 0.1 in binary is a repeating fraction, like trying to write one-third in decimal. You get close, never exact.

For most applications, "close" is fine. For money, "close" is a lawsuit.

The classic fix is to work in the smallest unit of currency. Instead of storing $19.99 as 19.99, you store 1999, an integer representing cents. Integer arithmetic in JavaScript is exact up to Number.MAX_SAFE_INTEGER (about 9 quadrillion cents, or $90 trillion). That is plenty of headroom for a personal finance app.

But here is the thing nobody tells you: converting to integer cents solves the math problem, not the human problem.

A developer on your team writes a function that accepts a number. Is that number dollars or cents? Is it pre-tax or post-tax income? The type system says number, which tells you nothing. Someone passes in 19.99 where 1999 was expected, and you have a bug that is off by a factor of 100 — far worse than a floating-point rounding error.

I needed the compiler itself to refuse bad money.

The Naive Fix (And Why It Still Fails)

The first attempt is always the same. You create a convention: "All monetary values end in Cents." You name your variables amountCents, incomeCents, balanceCents. You write it in the README. You mention it in code review.

Then someone writes:

const taxRate = 0.22;
const grossIncome: number = 500000; // cents
const tax: number = grossIncome * taxRate; // 110000 -- correct, but is it Cents?
const netIncome: number = grossIncome - tax; // works fine... this time

Everything compiles. Everything runs. The bug arrives three weeks later when a different developer passes netIncome into a function that expects dollars instead of cents. Or when tax gets rounded to a float and passed into another calculation that assumes integer cents.

Naming conventions are documentation. Documentation lies. Types do not.

Enter TypeScript Branded Types

A branded type is a TypeScript pattern that creates a distinct type from a primitive without any runtime overhead. The entire implementation in Talliofi looks like this:

// The branded type: a number that has been validated as integer cents
export type Cents = number & { readonly __brand: 'Cents' };

// The only way to create a Cents value -- our validation gate
export function cents(value: number): Cents {
  if (!Number.isSafeInteger(value)) {
    throw new Error(`Invalid cents value: ${value}`);
  }
  return value as Cents;
}

That & { readonly __brand: 'Cents' } intersection is the key. At runtime, it does not exist. There is no extra property on the number. JavaScript has no idea it is there. But TypeScript treats Cents as a distinct type from number. You cannot pass a raw number where Cents is expected without an explicit cast or going through the cents() constructor.

The constructor is your validation gate. Every monetary value in the system must pass through it. If you try to create Cents from 19.99 (a float), NaN, Infinity, or a number beyond safe integer range it throws at runtime. Two layers of protection: compile-time type checking and runtime validation.

For non-technical readers, think of it like a currency exchange booth at an airport. You cannot just hand someone random paper and call it money. You go through the booth, they validate it, stamp it, and now it is recognized currency. The cents() function is that booth.

Why Even Addition Gets Its Own Function

Once you have a branded type, you cannot just add two Cents values with +. The result of a + b in TypeScript is number, not Cents. Your carefully validated types would leak back to raw numbers after a single operation.

So every arithmetic operation gets a wrapper:

export const addMoney = (a: Cents, b: Cents): Cents => cents(a + b);
export const subtractMoney = (a: Cents, b: Cents): Cents => cents(a - b);

// Multiplication and percentage introduce fractions -- Math.round keeps us in integers
export const multiplyMoney = (amount: Cents, factor: number): Cents =>
  cents(Math.round(amount * factor));
export const percentOf = (amount: Cents, percent: number): Cents =>
  cents(Math.round(amount * (percent / 100)));

// Summing an array -- starts from validated zero, accumulates through addMoney
export const sumMoney = (amounts: readonly Cents[]): Cents =>
  amounts.reduce((sum, amt) => addMoney(sum, amt), cents(0));

Notice something subtle: multiplyMoney and percentOf accept a plain number as the second argument, not Cents. That is intentional. A tax rate is not money. A multiplication factor is not money. The type signatures enforce this distinction. You cannot accidentally pass a Cents value where a percentage belongs.

Here is the gotcha that surprises most developers: addMoney re-validates through cents() on every operation. That means overflow protection is automatic. If two enormous Cents values added together exceed Number.MAX_SAFE_INTEGER, the cents() constructor throws immediately rather than silently producing a corrupt value. Our test suite verifies this explicitly:

it('addMoney throws when result exceeds MAX_SAFE_INTEGER', () => {
  const large = cents(Number.MAX_SAFE_INTEGER - 1);
  expect(() => addMoney(large, cents(2))).toThrow('Invalid cents value');
});

Division by zero? Also caught. Math.round(100 / 0) produces Infinity, and cents(Infinity) throws. No special handling needed — the validation gate catches everything.

The Performance Play: Caching Intl.NumberFormat

Formatting money for display happens constantly in a financial app. Every list item, every chart tooltip, every summary card. Creating a new Intl.NumberFormat object on every render is expensive — these constructors parse locale data and build internal state.

Talliofi caches formatters by locale and currency:

const formatterCache = new Map<string, Intl.NumberFormat>();

export function formatMoney(
  amount: Cents,
  options: { locale?: string; currency: CurrencyCode },
): string {
  const { locale = 'en-US', currency } = options;
  const key = `${locale}:${currency}`;   // e.g., "en-US:USD" or "de-DE:EUR"
  let formatter = formatterCache.get(key);
  if (!formatter) {
    formatter = new Intl.NumberFormat(locale, { style: 'currency', currency });
    formatterCache.set(key, formatter);
  }
  return formatter.format(centsToDollars(amount));
}

The function signature enforces correctness: it accepts Cents, not number. You cannot accidentally format raw dollars or an unconverted value. The conversion to display-friendly dollars happens once, at the very last moment, inside this function. Everywhere else in the system, money stays in its branded integer form.

With six supported currencies and their associated locales, the cache holds at most a handful of entries. The memory cost is negligible. The performance gain on rendering a list of 200 expenses is noticeable.

Being Honest About Uncertainty: The ConversionResult Pattern

Multi-currency support introduced a design question I had not anticipated. When you convert USD to EUR and the exchange rate is unavailable (the user is offline, the rate API is down, the currency pair is not configured), what do you return?

Returning the original amount silently is dangerous the user would see "$500" labeled as "EUR 500" and never know the conversion failed. Throwing an error is disruptive for a display-only calculation. Returning null forces every consumer to handle the missing case.

Talliofi uses a tagged result:

export interface ConversionResult {
  readonly amount: Cents;
  /** Whether the amount was actually converted using a real exchange rate */
  readonly converted: boolean;
}

Callers get their Cents value regardless, but they also get a boolean that says "I actually converted this" versus "I just gave you back the original because I did not have a rate." The UI can then decide how to present this showing a warning icon, displaying "approximate" text, or fetching fresh rates.

This pattern is worth stealing for any domain where a function might produce a plausible-looking result from incomplete data. Do not hide uncertainty. Type it.

What 928 Occurrences Across 97 Files Looks Like

The Cents type is not a novelty confined to a utility file. It flows through the entire domain:

// Plans track income in Cents
export interface Plan {
  readonly grossIncomeCents: Cents;
  // ...
}

// Every expense uses Cents -- no raw numbers allowed
export interface ExpenseItem {
  readonly amountCents: Cents;
  // ...
}

// Split transactions carry Cents per split
export interface ExpenseSplit {
  readonly amountCents: Cents;
  // ...
}

// Goals, assets, liabilities, snapshots -- all branded
export interface Goal {
  readonly targetAmountCents: Cents;
  readonly currentAmountCents: Cents;
}

From income calculations to tax estimates to budget summaries to multi-month trend charts, every monetary value in Talliofi is Cents. The branded type creates a closed system. Money enters through cents() or dollarsToCents(), stays branded through all calculations, and only converts back to a display-friendly number at the very edge — inside formatMoney(). A new developer joining the project cannot accidentally create monetary bugs without the compiler flagging it.

What Almost Broke Me

The hardest part was not the type system. It was the migration.

When I introduced the branded type, every function that touched money needed to change. Not just the types, the call sites. Every place that did income - expenses had to become subtractMoney(income, expenses). Every array.reduce((sum, x) => sum + x.amount, 0) had to become sumMoney(items.map(i => i.amountCents)).

The compiler caught every one. That was the point. But "the compiler tells you where to fix things" is different from "the compiler fixes things for you." It was a methodical, file-by-file grind.

The lesson: introduce branded types early. The cost of adopting them grows linearly with your codebase. In a fresh project, it is nearly free. In a project with 97 files touching money, it is a weekend.

What I Learned (If I Built This Again)

1. Brand early, brand aggressively. I would introduce Cents in the very first commit, before any business logic exists. The migration cost is real and grows with time.

2. The constructor is the entire security model. The cents() function is one of the most important functions in the codebase. It is small, it is simple, and it is the single chokepoint for monetary validation. Guard it. Test it. Never bypass it.

3. This pattern generalizes far beyond money. Percentages (0–100 vs 0–1), timestamps (milliseconds vs seconds), distances (meters vs feet), IDs (user IDs vs order IDs), any domain where raw numbers carry implicit meaning is a candidate for branding.

4. Readonly interfaces compound the safety. Every domain type in Talliofi uses readonly properties. Combined with branded types, this means monetary values cannot be created incorrectly (branded constructor) or mutated incorrectly (readonly fields). Two fences, one enclosure.

5. The converted: boolean pattern pays for itself. Anywhere your code produces a "best effort" result, tag it with a confidence signal. Do not make downstream consumers guess whether the value is real or approximate.

Start Here

If you take one thing from this article, take the twelve lines. Copy the Cents type and the cents() constructor into your next TypeScript project that touches money. Write the arithmetic wrappers. Make your compiler do the auditing.

The pattern is small. The protection is not.

The best type systems do not just describe your code. They make entire categories of mistakes impossible to write.

Visit Talliofi website

Building a Local-First 3D Dashboard with IndexedDB: 89% Cache Hit Rate

Emmanuel — Tue, 20 Jan 2026 17:21:25 +0000

How we achieved sub-100ms data loads and offline resilience with IndexedDB

Problem: Our 3D globe dashboard made API calls on every interaction, causing 500-2000ms delays and complete failure when offline.

Solution: Implemented a local-first architecture with 4 IndexedDB databases, cloud sync, and a cache version manager.

Result: 89% cache hit rate, <50ms data loads, full offline functionality, and seamless cloud backup.

The Problem: Network-Dependent 3D Visualization

Our 3D Global Dashboard displays bird migration paths sourced from the GBIF API (2.5 billion observations). Users can also play geography quizzes, discover countries, and unlock achievements.

// ❌ Original approach: Always fetch from API
async getMigrationData(speciesId: string): Promise<MigrationPath[]> {
  const response = await fetch(`/api/gbif/species/${speciesId}/migrations`);
  return response.json();
}

The problems:

500-2000ms latency for every species lookup
Complete failure offline — no airplane mode support
Redundant requests — same data fetched repeatedly
API rate limiting — GBIF has request limits
Poor UX — loading spinners everywhere

The Solution: Local-First Architecture

Local-first means treating the network as an optimization, not a dependency. All IndexedDB access, cache eviction, and cloud synchronization are owned by dedicated services, giving us a single place to reason about data lifecycle, performance, and consistency.

User Action → Local State → IndexedDB → UI Update (instant)
                              ↓
                        Cloud Sync (async, debounced)

Benefits:

Instant UI updates — no waiting for network
Offline resilience — everything works without internet
Reduced API calls — cache serves most requests
Better UX — responsive interactions, background sync

Architecture: 4 Specialized Databases

We split data across 4 IndexedDB databases based on data characteristics:

Database	Purpose	TTL	Sync to Cloud
`quiz-stats-db`	Game sessions & scores	Permanent	Yes
`country-discoveries-db`	Country interactions	Permanent	Yes
`achievements-db`	Gamification progress	Permanent	Yes
`cache-version-manager`	Tracks cache versions	Permanent	No

Chrome DevTools Application tab showing the 4 specialized databases

Why separate databases?

Single responsibility (stats, discoveries, achievements)
Independent versioning and migrations
Easier debugging and maintenance
Clear ownership per service

Implementation: The idb Library

We use the idb library—a thin Promise wrapper around IndexedDB:

pnpm add idb

Database Schema Definition

// src/app/core/services/country-discovery.service.ts

import { openDB, IDBPDatabase, DBSchema } from 'idb';

// Define the schema with TypeScript
interface CountryDiscoveryDB extends DBSchema {
  discoveries: {
    key: string;  // countryCode
    value: CountryDiscovery;
    indexes: {
      'by-method': string;
      'by-first-discovered': Date;
      'by-last-interacted': Date;
    };
  };
}

interface CountryDiscovery {
  countryCode: string;
  countryName: string;
  discoveryMethod: 'click' | 'hover' | 'search' | 'quiz' | 'migration';
  firstDiscoveredAt: Date;
  lastInteractedAt: Date;
  interactionCount: number;
}

Database Initialization

// src/app/core/services/country-discovery.service.ts

@Injectable({ providedIn: 'root' })
export class CountryDiscoveryService {
  private readonly DB_NAME = 'country-discoveries-db';
  private readonly DB_VERSION = 1;
  private db: IDBPDatabase<CountryDiscoveryDB> | null = null;

  async initialize(): Promise<void> {
    this.db = await openDB<CountryDiscoveryDB>(
      this.DB_NAME,
      this.DB_VERSION,
      {
        upgrade(db, oldVersion, newVersion, transaction) {
          // Create object store if it doesn't exist
          if (!db.objectStoreNames.contains('discoveries')) {
            const store = db.createObjectStore('discoveries', {
              keyPath: 'countryCode',
            });

            // Create indexes for efficient queries
            store.createIndex('by-method', 'discoveryMethod');
            store.createIndex('by-first-discovered', 'firstDiscoveredAt');
            store.createIndex('by-last-interacted', 'lastInteractedAt');
          }
        },
      }
    );
  }
}

Persistent Local State

User Data (Permanent Storage)

User-generated data (quiz scores, discoveries, achievements) lives permanently in IndexedDB and syncs to Supabase:

// src/app/core/services/user-stats.service.ts

import { openDB, IDBPDatabase, DBSchema } from 'idb';

interface QuizStatsDB extends DBSchema {
  sessions: {
    key: string;
    value: GameSession;
    indexes: {
      'by-mode': string;
      'by-date': number;
      'by-completed': boolean;
    };
  };
  meta: {
    key: string;
    value: UserStatsV1;
  };
}

@Injectable({ providedIn: 'root' })
export class UserStatsService {
  private readonly DB_NAME = 'quiz-stats-db';
  private readonly DB_VERSION = 1;
  private db: IDBPDatabase<QuizStatsDB> | null = null;

  // Reactive state with signals
  private readonly _stats = signal<UserStatsV1 | null>(null);
  private readonly _recentSessions = signal<GameSession[]>([]);

  // Public readonly signals for components
  readonly stats = this._stats.asReadonly();
  readonly recentSessions = this._recentSessions.asReadonly();

  /**
   * Save a completed game session
   */
  async saveSession(session: GameSession): Promise<void> {
    if (!this.db) await this.initialize();

    // Atomic transaction: save session AND update aggregated stats
    const tx = this.db!.transaction(['sessions', 'meta'], 'readwrite');

    try {
      // Save the session
      await tx.objectStore('sessions').put(session);

      // Update aggregated stats
      const currentStats = await tx.objectStore('meta').get('user_stats_v1');
      const updatedStats = this.calculateUpdatedStats(currentStats, session);
      await tx.objectStore('meta').put(updatedStats);

      await tx.done;

      // Update signals (triggers UI updates)
      this._stats.set(updatedStats);
      this._recentSessions.update(sessions => [session, ...sessions].slice(0, 20));

      // Queue cloud sync (debounced)
      this.cloudSyncService.queueSync();

    } catch (error) {
      tx.abort();
      throw error;
    }
  }

  // Recent sessions are queried via IndexedDB cursors to avoid loading large datasets into memory.
}

API Cache with TTL (7-Day Expiration)

External API responses are cached with automatic expiration:

// src/app/features/bird-migration/services/gbif-adapter.service.ts

import { openDB, IDBPDatabase, DBSchema } from 'idb';

interface GbifCacheDB extends DBSchema {
  occurrences: {
    key: string;
    value: CacheEntry<GbifSearchResponse>;
    indexes: {
      'by-timestamp': number;
      'by-expires': number;
    };
  };
  species: {
    key: string;
    value: CacheEntry<GbifSpeciesSearchResult[]>;
    indexes: {
      'by-timestamp': number;
      'by-expires': number;
    };
  };
}

interface CacheEntry<T> {
  cacheKey: string;
  data: T;
  timestamp: number;
  expiresAt: number;
}

@Injectable({ providedIn: 'root' })
export class GbifAdapterService {
  private readonly DB_NAME = 'gbif-cache';
  private readonly DB_VERSION = 1;
  private readonly DEFAULT_TTL = 7 * 24 * 60 * 60 * 1000;  // 7 days in ms
  private readonly MAX_ENTRIES = 500;

  private db: IDBPDatabase<GbifCacheDB> | null = null;

  /**
   * Get data from cache, checking TTL
   */
  private async getFromCache<T>(
    storeName: 'occurrences' | 'species',
    cacheKey: string,
  ): Promise<T | null> {
    if (!this.db) await this.initialize();

    const entry = await this.db!.get(storeName, cacheKey);

    if (!entry) return null;  // Cache miss

    // Check if expired
    if (Date.now() > entry.expiresAt) {
      await this.db!.delete(storeName, cacheKey);
      return null;  // Treat as cache miss
    }

    return entry.data as T;  // Cache hit
  }

  /**
   * Store data in cache with TTL
   */
  private async storeInCache<T>(
    storeName: 'occurrences' | 'species',
    cacheKey: string,
    data: T,
    ttl: number = this.DEFAULT_TTL,
  ): Promise<void> {
    if (!this.db) await this.initialize();

    const entry: CacheEntry<T> = {
      cacheKey,
      data,
      timestamp: Date.now(),
      expiresAt: Date.now() + ttl,
    };

    await this.db!.put(storeName, entry);

    // Cleanup if too many entries
    await this.enforceMaxEntries(storeName);
  }

  /**
   * Main data fetching method with cache-first strategy
   */
  async searchOccurrences(
    speciesKey: number,
    options: SearchOptions = {},
  ): Promise<GbifSearchResponse> {
    const cacheKey = this.generateCacheKey('occurrences', {
      speciesKey,
      ...options,
    });

    // 1. Try cache first
    const cached = await this.getFromCache<GbifSearchResponse>(
      'occurrences',
      cacheKey,
    );

    if (cached) {
      this.logger.debug(`Cache hit for ${cacheKey}`);
      return cached;  // Return immediately, no network request
    }

    // 2. Cache miss: fetch from API
    this.logger.debug(`Cache miss for ${cacheKey}, fetching from API`);
    const response = await this.fetchFromGbifApi(speciesKey, options);

    // 3. Store in cache for future requests
    await this.storeInCache('occurrences', cacheKey, response);

    return response;
  }

  /**
   * Clean up old entries when cache grows too large
   */
  private async enforceMaxEntries(
    storeName: 'occurrences' | 'species',
  ): Promise<void> {
    const count = await this.db!.count(storeName);
    if (count <= this.MAX_ENTRIES) return;

    // Delete oldest entries using IndexedDB cursor
    const tx = this.db!.transaction(storeName, 'readwrite');
    const index = tx.objectStore(storeName).index('by-timestamp');

    let cursor = await index.openCursor();
    let deleted = 0;
    const toDelete = count - this.MAX_ENTRIES + 50;

    while (cursor && deleted < toDelete) {
      await cursor.delete();
      deleted++;
      cursor = await cursor.continue();
    }
  }
}

Data Freshness & Consistency

Cache Version Management

When your app updates, you may need to invalidate caches. We built a central version manager:

// src/app/core/services/cache-version.service.ts

import { openDB, IDBPDatabase } from 'idb';

interface CacheDatabase {
  name: string;
  clearOnVersionChange: boolean;
}

@Injectable({ providedIn: 'root' })
export class CacheVersionService {
  private readonly VERSION_DB_NAME = 'cache-version-manager';
  private readonly CURRENT_VERSION = '1.2.0';  // Bump this to invalidate caches

  // User data databases (preserved on version change)
  private readonly databases: CacheDatabase[] = [
    { name: 'quiz-stats-db', clearOnVersionChange: false },
    { name: 'country-discoveries-db', clearOnVersionChange: false },
    { name: 'achievements-db', clearOnVersionChange: false },
  ];

  /**
   * Check version and migrate if needed (called on app init)
   */
  async checkAndMigrate(): Promise<void> {
    const storedVersion = await this.getStoredVersion();

    if (storedVersion !== this.CURRENT_VERSION) {
      this.logger.info(
        `Cache version changed: ${storedVersion} → ${this.CURRENT_VERSION}`
      );

      await this.migrateToNewVersion(storedVersion);
      await this.setStoredVersion(this.CURRENT_VERSION);
    }
  }

  private async migrateToNewVersion(oldVersion: string | null): Promise<void> {
    // Clear API caches (they'll be refetched with fresh data)
    for (const db of this.databases) {
      if (db.clearOnVersionChange) {
        await this.clearDatabase(db.name);
        this.logger.info(`Cleared cache: ${db.name}`);
      }
    }
    // User data is preserved—no action needed
  }

  /**
   * Clear only API caches (useful for "refresh data" button)
   */
  async clearApiCaches(): Promise<void> {
    for (const db of this.databases) {
      if (db.clearOnVersionChange) {
        await this.clearDatabase(db.name);
      }
    }
  }
}

// src/app/app.config.ts

import { APP_INITIALIZER } from '@angular/core';
import { CacheVersionService } from './core/services/cache-version.service';

export const appConfig: ApplicationConfig = {
  providers: [
    {
      provide: APP_INITIALIZER,
      useFactory: (cacheVersion: CacheVersionService) => {
        return () => cacheVersion.checkAndMigrate();
      },
      deps: [CacheVersionService],
      multi: true,
    },
  ],
};

Sync & Performance Strategy

Cloud Sync with Debouncing

User data syncs to Supabase with a 5-second debounce to batch rapid changes:

// src/app/core/services/cloud-sync.service.ts

@Injectable({ providedIn: 'root' })
export class CloudSyncService {
  private readonly supabase = inject(SupabaseService);

  // Sync state (reactive)
  readonly syncStatus = signal<'idle' | 'syncing' | 'synced' | 'error'>('idle');
  readonly lastSyncTime = signal<Date | null>(null);

  private syncDebounceTimer: ReturnType<typeof setTimeout> | null = null;
  private readonly SYNC_DEBOUNCE_MS = 5000;  // 5 seconds

  constructor() {
    // Auto-sync when user logs in
    effect(() => {
      const isAuthenticated = this.supabase.isAuthenticated();
      if (isAuthenticated) {
        this.syncFromCloud();  // Pull latest cloud data
      }
    });
  }

  /**
   * Queue a sync (debounced to batch rapid changes)
   */
  queueSync(): void {
    if (!this.supabase.isAuthenticated()) return;

    if (this.syncDebounceTimer) {
      clearTimeout(this.syncDebounceTimer);
    }

    this.syncDebounceTimer = setTimeout(() => {
      this.syncToCloud();
    }, this.SYNC_DEBOUNCE_MS);
  }

  /**
   * Push local data to cloud
   */
  async syncToCloud(): Promise<void> {
    if (!this.supabase.isAuthenticated()) return;

    this.syncStatus.set('syncing');

    try {
      const [sessions, stats, discoveries, achievements] = await Promise.all([
        this.userStatsService.getRecentSessions(1000),
        this.userStatsService.getStats(),
        this.discoveryService.getAllDiscoveries(),
        this.achievementsService.getAllAchievements(),
      ]);

      await Promise.all([
        this.supabase.uploadQuizSessions(sessions),
        this.supabase.uploadUserStats(stats),
        this.supabase.uploadDiscoveries(discoveries),
        this.supabase.uploadAchievements(achievements),
      ]);

      this.syncStatus.set('synced');
      this.lastSyncTime.set(new Date());

    } catch (error) {
      this.syncStatus.set('error');
      this.logger.error('Cloud sync failed', 'CloudSyncService', error);
    }
  }

  // Cloud data is merged using a simple "newest wins" strategy based on timestamps,
  // keeping conflict resolution predictable and debuggable.
}

Multi-Layer Caching for Three.js

For Three.js assets, we add an in-memory cache on top of IndexedDB and the browser's HTTP cache. This avoids repeated GPU uploads and keeps texture loads effectively instant after the first render.

// In-memory texture cache (fastest layer)
private textureCache = new Map<string, Texture>();

The cache hierarchy: Memory (instant) → Browser HTTP Cache (fast) → Network (slow)

Browser Console Helpers

For debugging, we expose helpers to the browser console:

// src/app/dev-helpers.ts

export function setupDevHelpers(injector: Injector): void {
  const cacheVersion = injector.get(CacheVersionService);
  const cloudSync = injector.get(CloudSyncService);

  (window as any).cacheVersion = {
    check: () => cacheVersion.getStoredVersion(),
    getDatabases: () => cacheVersion.getDatabases(),
    clearApiCaches: () => cacheVersion.clearApiCaches(),
  };

  (window as any).cloudSync = {
    status: () => cloudSync.syncStatus(),
    syncNow: () => cloudSync.forceSyncNow(),
  };

  // Deletes all IndexedDB databases for a clean slate
  (window as any).clearLocalData = async () => { /* ... */ };
}

Performance Results

Cache Hit Rates

Data Type	Hit Rate	Avg Load Time (Cache)	Avg Load Time (Network)
Country data	95%	<10ms	200ms
Quiz sessions	100%	<5ms	N/A (local-only)
Bird migrations	89%	<50ms	800ms
Species lookups	92%	<20ms	400ms
Textures	99%	<1ms	150ms

Overall Impact

Metric	Before	After	Improvement
First interaction delay	500-2000ms	<50ms	90% faster
Offline functionality	None	Full	100% offline
API requests per session	~200	~20	90% reduction
Data freshness	Always current	7-day max stale	Acceptable

Why Not Service Workers?

We intentionally avoided Service Workers for caching application data. IndexedDB gives us explicit control over TTLs, migrations, and conflict resolution, while keeping logic in the same mental model as our Angular services. Service Workers are excellent for static assets, but harder to reason about for evolving domain data.

Tradeoffs and Gotchas

When Local-First Makes Sense

Read-heavy workloads — Same data accessed multiple times
Offline requirements — Users need to work without internet
API rate limits — External APIs restrict request frequency
Latency-sensitive UX — Users expect instant feedback

When to Skip Local-First

Real-time collaborative data — Stale data causes conflicts
Sensitive data — IndexedDB is readable by browser extensions
Small datasets — Network is fast enough, caching adds complexity
Frequently changing data — 7-day TTL would serve stale data

Common Mistakes

1.Not handling quota exceeded errors

try {
  await db.put(storeName, data);
} catch (error) {
  if (error.name === 'QuotaExceededError') {
    await this.evictOldEntries();
    await db.put(storeName, data);
  }
}

2.Forgetting to close database connections

// Good: close when done
db.close();

3.Blocking the main thread with large reads

// Good: use cursors for large datasets
let cursor = await db.transaction('items').store.openCursor();
while (cursor && items.length < 100) {
  items.push(cursor.value);
  cursor = await cursor.continue();
}

4.Not versioning cache entries — Always include timestamp and expiresAt

Key Takeaways

Separate databases by data lifecycle — Permanent user data vs. expiring caches 2.Always check TTL before returning cached data — Stale data is worse than slow data
Debounce cloud sync — Batch rapid local changes (we use 5 seconds)
Newest wins for conflict resolution — Simple and predictable
Handle quota errors gracefully — IndexedDB has storage limits

The 3D Global Dashboard now loads data in <50ms, works completely offline, and seamlessly syncs to the cloud when connected. Users on spotty connections finally have a reliable experience.

GlobePlay - Interactive Geography, Bird Migration & Quiz

Explore 241 countries, trace bird migration paths, and test your geography knowledge on an interactive 3D globe. Built with Three.js and Angular.

globeplay.world

Angular Signals + Three.js: How We Hit 60fps Without Going Zoneless

Emmanuel — Thu, 15 Jan 2026 17:07:05 +0000

How we optimized WebGL rendering in Angular using OnPush, Signals, and render-on-demand—without the experimental zoneless API

This article assumes familiarity with Angular change detection and basic Three.js concepts.

Context: Production Angular app (~500 DAU) with an interactive WebGL globe used in long-running sessions (30–90 minutes).

Problem: Our Three.js globe ran at 30fps because Zone.js triggered change detection on every requestAnimationFrame tick 60 unnecessary CD cycles per second. At 30fps, the globe felt laggy and drained laptop batteries.

A 3D scene should not re-render 60 times per second if nothing changed.

Solution: Combined ChangeDetectionStrategy.OnPush with Angular Signals and a render-on-demand pattern that only draws frames when the scene actually changes.

Ownership: The GlobeSceneService is the single owner of the render lifecycle and performance budget.

Start/stop animation loop on init/destroy
Expose requestRender() and requestFrameIfNeeded() APIs
Track metrics and expose health signals

This makes rendering behavior predictable, debuggable, and enforceable across the application.

Result: Consistent 60fps, 90% GPU reduction when idle, and zero Zone.js interference with the render loop.

The Problem: Zone.js Meets requestAnimationFrame

Three.js applications need a continuous animation loop. The standard pattern looks like this:

// Standard Three.js animation loop
function animate() {
  requestAnimationFrame(animate);  // Schedule next frame
  controls.update();               // Update camera controls
  renderer.render(scene, camera);  // Render the scene
}
animate();

This works great—until you put it inside an Angular application.

The issue: Zone.js schedules requestAnimationFrame callbacks inside the Angular zone, which may trigger change detection depending on component strategy. At 60fps, that's 60 change detection cycles per second, even if nothing in your Angular templates changed.

The symptoms:

GPU usage at 20%+ even when idle (no user interaction)
FPS drops to 30fps on mid-range devices
Battery drain on laptops and mobile devices
UI jank when Angular templates try to update during renders

Why Not Just Use Experimental Zoneless?

Angular 18+ offers provideExperimentalZonelessChangeDetection(). It sounds perfect—no Zone.js, no problem. But there are real tradeoffs:

It's experimental — API may change, limited community support
Third-party libraries — Many Angular libraries assume Zone.js exists
Migration effort — Existing apps need significant refactoring
Testing complexity — Test utilities behave differently

We chose a hybrid approach: keep Zone.js for the benefits it provides (automatic change detection for UI interactions), but prevent it from interfering with Three.js.

The Solution: Three Interlocking Patterns

Our solution combines three patterns:

OnPush change detection — Only update components when inputs/signals change
Signal-based state — Fine-grained reactivity without Zone.js triggers
Render-on-demand — Only render Three.js frames when the scene changes

Let's look at each one.

Pattern 1: OnPush Everything

Every component uses ChangeDetectionStrategy.OnPush:

// src/app/pages/globe/globe.ts

import {
  Component,
  ChangeDetectionStrategy,
  signal,
  computed,
  effect
} from '@angular/core';

@Component({
  selector: 'app-globe',
  standalone: true,
  templateUrl: './globe.html',
  changeDetection: ChangeDetectionStrategy.OnPush,  // ← Critical
})
export class GlobePage {
  // Component implementation
}

With OnPush, Angular only checks the component when:

An @Input() reference changes
A signal the template reads updates
An event handler in the template fires
You manually call ChangeDetectorRef.markForCheck()

Crucially, requestAnimationFrame callbacks don't trigger OnPush components.

Pattern 2: Signals for Reactive State

Instead of RxJS BehaviorSubjects or plain properties, we use Angular Signals throughout:

// src/app/pages/globe/services/globe-scene.service.ts

import { Injectable, signal } from '@angular/core';

@Injectable({ providedIn: 'root' })
export class GlobeSceneService {
  // Reactive state with signals
  readonly isInitialized = signal(false);
  readonly cameraInteractionState = signal<boolean>(false);

  // Private mutable state for Three.js (not reactive)
  private scene!: Scene;
  private camera!: PerspectiveCamera;
  private renderer!: WebGLRenderer;
  private controls!: OrbitControls;

  // Animation state
  private needsRender = true;
  private isAnimating = false;
}

Signals provide:

Automatic template updates — Templates re-render when signals they read change
Fine-grained reactivity — Only affected components update, not the whole tree
No subscription management — Unlike RxJS, no need to unsubscribe

Pattern 3: Render-on-Demand

This is the core optimization: instead of rendering every frame, we only render when something changes.

Always stop the animation loop on component or service destroy using DestroyRef.onDestroy() (services) or ngOnDestroy() (components) to prevent duplicate render loops during navigation.

// src/app/pages/globe/services/globe-scene.service.ts

@Injectable({ providedIn: 'root' })
export class GlobeSceneService {
  // Animation state
  private animationId?: number;
  private lastFrameTime = 0;
  // Soft cap at ~60fps (used for throttling, not locking. 1000ms / 60)
  private readonly frameInterval = 16.67;
  private needsRender = true;  
  private isAnimating = false;


  // Start the animation loop
  startAnimation(): void {
    if (this.isAnimating) return;
    this.isAnimating = true;
    this.animate();
  }


  // Stop the animation loop
  stopAnimation(): void {
    if (this.animationId !== undefined) {
      cancelAnimationFrame(this.animationId);
      this.animationId = undefined;
      this.isAnimating = false;
    }
  }

 // In GlobeSceneService (service owns render lifecycle)
  private readonly destroyRef = inject(DestroyRef);

  constructor() {
    // Ensure we stop the loop when the service is destroyed
    this.destroyRef.onDestroy(() => this.stopAnimation());
  }



  private animate(currentTime: number = 0): void {
    this.animationId = requestAnimationFrame((time) => this.animate(time));

    // Frame throttling: skip if called too soon
    const deltaTime = currentTime - this.lastFrameTime;
    if (deltaTime < this.frameInterval) {
      return;  // Skip this frame
    }

    const deltaTimeSeconds = deltaTime / 1000.0;
    this.lastFrameTime = currentTime;

    // Update OrbitControls (may set needsRender via 'change' event)
    this.controls.update();

    // Check for active animations (e.g., bird migrations)
    const hasActiveMigrations =
      this.globeMigrationService.isInitialized() &&
      this.globeMigrationService.hasActiveAnimations();

    // Animate migration paths if active
    if (hasActiveMigrations) {
      this.globeMigrationService.animate(deltaTimeSeconds);
      this.needsRender = true;
    }

    // ONLY RENDER IF SOMETHING CHANGED
    if (this.needsRender || hasActiveMigrations) {
      this.renderer.render(this.scene, this.camera);
      this.needsRender = false;  // Reset flag after render
    }
  }


  requestRender(): void {
    this.needsRender = true;
  }
}

The key insight: the animation loop runs continuously, but renderer.render() only executes when needsRender is true.

Why not use RxJS for the animation loop?
You can model requestAnimationFrame with RxJS (e.g., an observable driven by animationFrameScheduler), but for hot, imperative rendering loops the extra abstraction adds overhead and complexity. Three.js expects imperative control, and an imperative loop avoids the costs of Observable allocation, scheduling, and operator chains on each tick. We use RxJS for state and event streams and keep the render loop imperative for minimal overhead.

Triggering Renders: The Event-Driven Approach

needsRender is set explicitly in response to real scene changes:

1. Camera Movement (OrbitControls)

// src/app/pages/globe/services/globe-scene.service.ts

private setupControls(): void {
  this.controls = new OrbitControls(this.camera, this.renderer.domElement);

  // Configure controls
  this.controls.enableDamping = true;
  this.controls.dampingFactor = 0.05;
  this.controls.minDistance = 3;
  this.controls.maxDistance = 15;

  // Track interaction state for UI
  this.controls.addEventListener('start', () => {
    this.cameraInteractionState.set(true);  // Signal update for UI
  });

  this.controls.addEventListener('end', () => {
    this.cameraInteractionState.set(false);
  });

  // CRITICAL: Request render when camera moves
  this.controls.addEventListener('change', () => {
    this.needsRender = true;  // ← Triggers actual render
  });
}

2. User Interactions in Components

// src/app/pages/globe/globe.ts

@Component({...})
export class GlobePage {
  private globeSceneService = inject(GlobeSceneService);

  // When user selects a country
  onCountryClick(country: string): void {
    this.selectedCountry.set(country);
    this.applyCountryHighlight(country);
    this.globeSceneService.requestRender();  // ← Request render
  }

  // When quiz state changes
  constructor() {
    effect(() => {
      const selectedCandidate = this.quizStateService.selectedCandidate();
      const gameState = this.quizStateService.gameState();

      if (!selectedCandidate || gameState === 'idle' || gameState === 'ended') {
        this.quizIntegration.clearQuizCandidateHighlight();
        this.globeSceneService.requestRender();  // ← Request render
      }
    });
  }
}

Signals + Effects for Angular-Three.js Bridge

Angular Signals and effect() create a clean bridge between Angular's reactive system and Three.js's imperative API:

// src/app/pages/globe/globe.ts

@Component({...})
export class GlobePage {
  // Angular signals for UI state
  protected readonly selectedCountry = signal<string | null>(null);
  protected readonly isLoading = signal(false);

  // Computed values for templates
  protected readonly migrationCardData = computed<readonly MigrationCardData[]>(() => {
    const activePaths = this.migrationState.activePaths();
    const migrations = this.migrationState.migrations();
    const species = this.migrationState.species();

    return activePaths.slice(0, 3).map((activePath) => {
      const migration = migrations.find(m => m.id === activePath.migrationId);
      const speciesData = species.find(s => s.id === migration?.speciesId);

      return {
        speciesName: speciesData?.commonName ?? 'Unknown',
        scientificName: speciesData?.scientificName ?? '',
        distance: migration?.totalDistance ?? 0,
        // ... more computed fields
      };
    });
  });

  constructor() {
    // Effect: Sync Angular state → Three.js scene
    effect(() => {
      const selectedIds = this.countrySelectionService.selectedCountries();

      // Update Three.js texture based on Angular signal
      if (this.countryIdTextureService.getSelectionMaskTexture()) {
        this.countryIdTextureService.updateSelectionMask(selectedIds);
        // Note: updateSelectionMask internally calls requestRender()
      }
    });
  }
}

The effect() function watches signals and runs whenever they change. This is how Angular state flows into Three.js without Zone.js interference.

App Configuration: Event Coalescing

We keep Zone.js but optimize it with event coalescing:

// src/app/app.config.ts

import {
  ApplicationConfig,
  provideZoneChangeDetection,
} from '@angular/core';

export const appConfig: ApplicationConfig = {
  providers: [
    // Keep Zone.js, but coalesce events for better performance
    provideZoneChangeDetection({ eventCoalescing: true }),

    // ... other providers
  ],
};

eventCoalescing: true batches multiple synchronous events into a single change detection cycle. This reduces CD overhead without removing Zone.js entirely.

Performance Results

Before Optimization

Metric	Value	Notes
FPS	30fps	Zone.js CD overhead
GPU Idle	20%+	Continuous rendering
CD Cycles	60/sec	Every rAF triggers CD
Battery	Poor	Constant GPU/CPU usage

After Optimization

Metric	Value	Improvement
FPS	60fps	2x faster
GPU Idle	2-5%	90% reduction
CD Cycles	On-demand	~99% reduction
Battery	Excellent	Only active when needed

How to Measure

// Add to your scene service for debugging
private logPerformance(): void {
  const info = this.renderer.info;
  console.log({
    drawCalls: info.render.calls,
    triangles: info.render.triangles,
    geometries: info.memory.geometries,
    textures: info.memory.textures,
  });
}

In production, we collect FPS, frame time, draw calls, and memory usage into a lightweight performance monitor backed by signals. This lets us surface real-time health indicators in the UI and catch regressions early:

readonly currentFPS = computed(() => this.metrics().fps);
readonly isPerformanceGood = computed(() => this.metrics().fps >= 55);

Additional Optimizations (Optional)

Adaptive geometry: Dynamically reduce sphere segments on low-memory or mobile devices (48–128 segments based on navigator.deviceMemory and hardwareConcurrency), cutting vertex count by up to 75%.
InstancedMesh for particles: Batch hundreds of migration particles into a single draw call instead of individual meshes:

new THREE.InstancedMesh(geometry, material, MAX_PARTICLES);

Tradeoffs and Gotchas

When This Pattern Works Best

3D visualizations with intermittent user interaction
Data dashboards where renders are event-driven
Games with predictable update cycles
Existing Angular apps where full zoneless migration is risky

When to Consider Full Zoneless

New greenfield projects without third-party Zone.js dependencies
Extreme performance requirements where even coalesced Zone.js is too much
Simple apps without complex async operations

Common Mistakes

Forgetting to call requestRender() after scene changes
Calling requestRender() in a loop instead of once after batch updates
Not using OnPush on components that read Three.js state
Putting Three.js objects in signals — signals are for primitive/serializable state

The `requestRender()` Checklist

Call it after:

Changing material properties
Moving objects
Updating textures
Adding/removing scene objects
Changing lights

Don't call it:

Inside the animation loop (it's already handled)
Multiple times in the same synchronous block (once is enough)
For Angular-only state changes (signals handle that)

Key Takeaways

You don't need experimental zoneless — OnPush + Signals + render-on-demand achieves 90% of the benefit
Render-on-demand is the key — The animation loop runs, but actual rendering is conditional
Signals bridge Angular and Three.js — Use effect() to sync reactive state to the scene
Event coalescing helps — provideZoneChangeDetection({ eventCoalescing: true })
Measure everything — Use renderer.info and a performance monitor to validate improvements

The 3D Global Dashboard now runs at consistent 60fps with 2-5% GPU usage when idle. Users report dramatically better battery life, and the UI remains responsive even during complex animations without sacrificing Angular's developer ergonomics or maintainability.

GlobePlay - Interactive Geography, Bird Migration & Quiz

Explore 241 countries, trace bird migration paths, and test your geography knowledge on an interactive 3D globe. Built with Three.js and Angular.

globeplay.world

O(1) Country Selection on a 3D Globe with GPU Picking and Hemisphere Detection

Emmanuel — Sun, 11 Jan 2026 20:45:11 +0000

How we achieved 99.5% faster country selection using ID textures and fixed the "clicking Asia selects Argentina" bug

Problem: Selecting countries on our 3D globe took 45ms using CPU raycasting against 241 meshes. Worse, clicking on a visible country sometimes selected one on the opposite side of the globe.

Solution: Replaced O(n) raycasting with O(1) GPU pixel reading using a pre-generated ID texture where each country has a unique RGB color. Added dot product hemisphere detection to ensure only front-facing countries respond to clicks.

Result: Selection time dropped from 45ms to <1ms (99.5% faster), and the "see-through globe" bug is completely fixed.

Role: Solo Full-Stack Engineer | Timeline: 3 days | Team: 1 (me)

Impact: Reduced country selection latency from 45ms to <1ms (99.5% improvement), eliminated a confusing UX bug where users could accidentally select countries on the opposite hemisphere, and established a pattern for GPU-accelerated picking that scales to any number of selectable objects.

The Problem: Two Bugs, One Globe

Our 3D Global Dashboard lets users click countries to explore facts, play quizzes, and view bird migration paths. Two issues made this interaction frustrating:

Bug 1: Slow Selection (45ms per click)

The standard Three.js approach uses raycasting:

// Traditional approach: O(n) raycasting
const raycaster = new Raycaster();
raycaster.setFromCamera(mouse, camera);

// Test ray against ALL 241 country meshes
const intersects = raycaster.intersectObjects(countries.children, true);

if (intersects.length > 0) {
  return intersects[0].object.name;  // First hit wins
}

With 241 country meshes (each with complex polygon geometry), this took 45ms per click on average. Users felt the lag.

Bug 2: See-Through Selection (The Niger/Nigeria Problem)

Raycasting returns all intersections along the ray, sorted by distance. But on a sphere, a ray can pass through both the front and back surfaces:

Camera → [Front: Nigeria] → [Back: Argentina]
         ↑ User sees this   ↑ Ray hits this too!

If the front mesh had a gap (between Nigeria and Niger, for example), the ray would pass through and hit Argentina on the back of the globe. Users clicking on Africa would suddenly see South American country data.

Investigation: Finding the Bottlenecks

Profiling the Raycasting

Chrome DevTools Performance panel revealed the issue immediately:

Click Event Timeline:
├── Event dispatch:        2ms
├── Raycaster setup:       1ms
├── intersectObjects():   41ms  ← BOTTLENECK
├── Process result:        1ms
└── Total:                45ms

The intersectObjects() call with recursive: true was testing the ray against every triangle in every country mesh. With 241 countries averaging ~500 triangles each, that's ~120,000 triangle intersection tests per click.

Reproducing the See-Through Bug

User reports said "I clicked on Nigeria but got Argentina." Debug logging revealed the issue: multiple intersections for a single click—one on the visible country, another on the opposite hemisphere. When the front mesh had gaps (between Niger and Nigeria), the ray passed through and selected Argentina on the back of the globe.

Understanding the Geometry: Why Rays Pierce Spheres

A ray from the camera can intersect a sphere at two points: entry and exit.

        Camera
           \
            \  Ray
             \
              ↘
         ┌─────────┐
        /   GLOBE   \
       /      ●      \    ← Entry point (front)
      │    Center    │
       \      ●      /    ← Exit point (back)
        \           /
         └─────────┘

Three.js raycasting returns both intersections; gaps in front-facing meshes allow rays to hit the back of the globe geometrically correct, but UX-incorrect.

The Math Behind It

For a ray R(t) = origin + t * direction and a sphere centered at C with radius r:

|R(t) - C|² = r²

Solving for t gives 0, 1, or 2 solutions:
- 0 solutions: ray misses sphere entirely
- 1 solution: ray tangent to sphere (rare edge case)
- 2 solutions: ray enters AND exits sphere (common case)

When clicking on a globe, we almost always get two intersection points. The question becomes: which one did the user intend to click?

Solution 1: GPU-Based ID Texture Picking

Instead of testing a ray against 241 meshes, we render a special "ID texture" where each country is a unique solid color. Then we simply read the pixel under the mouse.

How It Works

1. Pre-generate a texture where each country = unique RGB color
2. Load texture and build color→country lookup map
3. On click: read the pixel at mouse position
4. Decode RGB → country ID (O(1) lookup)

Generating the ID Texture

We pre-generate a 2048x1024 equirectangular texture where each country is filled with a unique color. The generation script:

// scripts/generate-country-id-map.ts

interface CountryIdData {
  metadata: {
    generatedAt: string;
    totalCountries: number;
    encoding: string;
  };
  countries: Record<string, {
    name: string;
    index: number;
    encodedColor: { r: number; g: number; b: number; hex: string };
  }>;
}

function generateCountryIdMap(geojson: FeatureCollection): CountryIdData {
  const countries: CountryIdData['countries'] = {};
  let index = 1;  // Start at 1, reserve 0 for "no country"

  for (const feature of geojson.features) {
    const countryCode = feature.properties.ISO_A3;

    // Encode index as RGB (24-bit color = 16.7M unique values)
    const r = (index >> 16) & 0xff;
    const g = (index >> 8) & 0xff;
    const b = index & 0xff;

    countries[countryCode] = {
      name: feature.properties.NAME,
      index,
      encodedColor: {
        r, g, b,
        hex: `#${index.toString(16).padStart(6, '0')}`
      }
    };

    index++;
  }

  return {
    metadata: {
      generatedAt: new Date().toISOString(),
      totalCountries: index - 1,
      encoding: 'RGB24'
    },
    countries
  };
}

This produces two files:

country-id-map.png — The texture with unique colors per country
country-id-lookup.json — The mapping from RGB values to country codes

Each country rendered as a unique RGB color for O(1) GPU picking

The TypeScript Interface

// src/lib/services/country-id-texture.service.ts

export interface CountryLookupData {
  metadata: {
    generatedAt: string;
    totalCountries: number;
    encoding: string;
    format: string;
  };
  countries: Record<string, {
    name: string;
    index: number;
    encodedColor: {
      r: number;
      g: number;
      b: number;
      hex: string;
      css: string;
    };
    properties: {
      iso_a3?: string;
      name_long?: string;
      continent?: string;
      region?: string;
      subregion?: string;
    };
  }>;
}

The Service Implementation

// src/lib/services/country-id-texture.service.ts (simplified)

@Injectable({ providedIn: 'root' })
export class CountryIdTextureService {
  private indexToIdMap = new Map<number, string>();

  decodeCountryId(r: number, g: number, b: number): string | null {
    const index = (r << 16) | (g << 8) | b;
    return this.indexToIdMap.get(index) ?? null;
  }
}

The full service handles asset loading, adaptive resolution (2048x1024 for desktop, 1024x512 for mobile), and selection mask generation. The key insight is the constant-time RGB → ID decode using bit shifting.

Texture Configuration: Required Settings

The ID texture requires specific WebGL settings to preserve exact color values:

// Required for correctness:
this.countryIdTexture.format = RGBAFormat;
this.countryIdTexture.minFilter = NearestFilter;  // Prevents color blending
this.countryIdTexture.magFilter = NearestFilter;
this.countryIdTexture.wrapS = ClampToEdgeWrapping;
this.countryIdTexture.wrapT = ClampToEdgeWrapping;
this.countryIdTexture.generateMipmaps = false;    // Mipmaps blend colors

Important: Using LinearFilter instead of NearestFilter would interpolate colors at country borders, corrupting the encoded IDs. This is the most common mistake when implementing GPU picking.

Reading the Pixel on Click

selectCountryAtPoint(x: number, y: number): string | null {
  // Render ID texture to offscreen buffer
  this.renderer.setRenderTarget(this.pickingTexture);
  this.renderer.render(this.pickingScene, this.camera);
  this.renderer.setRenderTarget(null);

  // Read single pixel (flip Y for WebGL coordinates)
  const pixelBuffer = new Uint8Array(4);
  this.renderer.readRenderTargetPixels(
    this.pickingTexture,
    x,
    this.pickingTexture.height - y,
    1, 1,
    pixelBuffer
  );

  return this.countryIdTextureService.decodeCountryId(
    pixelBuffer[0], pixelBuffer[1], pixelBuffer[2]
  );
}

Why This Is O(1)

Operation	CPU Raycasting	GPU Picking
Per-click work	Test ray vs 241 meshes	Read 1 pixel
Complexity	O(n) where n = meshes	O(1) constant
Time	45ms	<1ms
Scales with mesh count	Yes (linear)	No (constant)

The GPU has already rasterized the scene. Reading a pixel is a single memory lookup, regardless of how many countries exist.

Selection Mask: Visual Feedback for Selections

When a user selects a country, we need to highlight it visually. Rather than modifying mesh materials (expensive), we use a second texture as a "selection mask."

Internally, we generate the mask by scanning the ID texture and painting white pixels for selected countries. This avoids per-mesh material updates and keeps selection rendering GPU-bound.

The selection mask is then blended with the globe material in the shader:

// In globe fragment shader
uniform sampler2D selectionMask;

void main() {
  vec4 baseColor = texture2D(baseMap, vUv);
  vec4 selection = texture2D(selectionMask, vUv);

  // Blend selection highlight
  vec3 finalColor = mix(baseColor.rgb, vec3(0.2, 0.8, 0.4), selection.r * 0.5);

  gl_FragColor = vec4(finalColor, 1.0);
}

Solution 2: Front-Facing Hemisphere Detection

GPU picking solves the performance problem, but we still use raycasting for some interactions (hover tooltips, quiz mode). The see-through bug needed a geometric fix.

The Insight: Dot Product

A point on the globe is "front-facing" if it's on the same hemisphere as the camera. We can test this with a dot product:

Camera direction: normalize(camera.position)
Point direction:  normalize(intersection.point)

dot(camera_dir, point_dir) > 0  →  Same hemisphere (front)
dot(camera_dir, point_dir) < 0  →  Opposite hemisphere (back)
dot(camera_dir, point_dir) = 0  →  On the "equator" (edge case)

Why Dot Product Works

The dot product of two unit vectors equals the cosine of the angle between them:

dot(A, B) = |A| * |B| * cos(θ) = cos(θ)  (when A and B are normalized)

cos(0°) = 1      → Vectors point same direction (front-facing)
cos(90°) = 0     → Vectors perpendicular (edge of visible hemisphere)
cos(180°) = -1   → Vectors point opposite directions (back-facing)

For our globe centered at origin:

The camera position vector points FROM the globe center TO the camera
The intersection point vector points FROM the globe center TO the clicked point
If both vectors point "outward" in roughly the same direction, the point is front-facing

Note: This approach assumes the globe is centered at the origin and the camera orbits around it, which is typical for planetary visualizations.

Hemisphere Detection Diagram

                    Camera
                      ◉
                     /|
                    / |
         cameraDir/  |
                 /   |
                ↙    |
          ┌─────────────────┐
         /    FRONT          \
        /   (dot > 0)    ●A   \    A: Front-facing (✓ selectable)
       │        ↗              │       dot(cameraDir, pointA) > 0
       │   Globe               │
       │   Center              │
       │        ↘              │
        \   (dot < 0)    ●B   /    B: Back-facing (✗ filtered out)
         \    BACK           /        dot(cameraDir, pointB) < 0
          └─────────────────┘

The Implementation

// src/app/pages/globe/services/globe-interaction.service.ts

/**
 * Check if a point on the globe is facing the camera (front hemisphere)
 * Uses dot product: positive = front-facing, negative = back-facing
 *
 * @param point The intersection point on the globe surface
 * @param camera The camera to check against
 * @returns true if the point is on the camera-facing side
 */
private isPointFrontFacing(
  point: Vector3,
  camera: PerspectiveCamera,
): boolean {
  // Globe is centered at origin (0, 0, 0)
  // Vector from globe center to intersection point (normalized)
  const pointDirection = point.clone().normalize();

  // Vector from globe center to camera position (normalized)
  const cameraDirection = camera.position.clone().normalize();

  // Dot product > 0 means the point is on the same hemisphere as the camera
  return pointDirection.dot(cameraDirection) > 0;
}

Integrating with Raycasting

async handleCountrySelection(
  event: MouseEvent,
  renderer: { domElement: HTMLCanvasElement },
  camera: PerspectiveCamera,
  countries: Group,
): Promise<string | null> {
  // Get mouse coordinates and convert to normalized device coordinates
  const canvas = renderer.domElement;
  const rect = canvas.getBoundingClientRect();
  const mouse = new Vector2(
    ((event.clientX - rect.left) / canvas.width) * 2 - 1,
    -((event.clientY - rect.top) / canvas.height) * 2 + 1
  );

  // Setup raycaster
  const raycaster = new Raycaster();
  raycaster.near = 0.1;
  raycaster.far = 10;  // Limit ray distance for performance
  raycaster.setFromCamera(mouse, camera);

  const intersects = raycaster.intersectObjects(countries.children, true);

  // Find FIRST intersection that is front-facing
  for (const intersect of intersects) {
    const obj = intersect.object;

    // Skip border lines and non-country meshes
    if (obj.name === 'unified-borders' || obj.userData?.['isUnifiedBorder']) {
      continue;
    }

    if (obj.name.startsWith('selection-mesh-') && obj.type === 'Mesh') {
      // Important: Only accept front-facing intersections
      if (!this.isPointFrontFacing(intersect.point, camera)) {
        continue;
      }
      return this.extractCountryName(obj);
    }
  }

  return null;
}

Applying to Hover Detection Too

The same fix applies to hover tooltips:

async handleCountryHover(
  event: MouseEvent,
  camera: PerspectiveCamera,
  countries: Group,
): Promise<string | null> {
  // Early exit if in quiz mode (different hover behavior)
  if (this.interactionModeService.isQuizMode()) return null;

  const intersects = raycaster.intersectObjects(countries.children, true);

  for (const intersect of intersects) {
    // Same front-facing check
    if (!this.isPointFrontFacing(intersect.point, camera)) {
      continue;
    }

    // Return country name for tooltip
    return this.extractCountryName(intersect.object);
  }

  return null;
}

Visual Explanation

Before fix:
  User views Africa → Click gap between Niger/Nigeria
                   → Ray passes through gap
                   → Hits Argentina on back
                   → Shows Argentina data ❌

After fix:
  User views Africa → Click gap between Niger/Nigeria
                   → Ray passes through gap
                   → Hits Argentina on back
                   → Argentina fails dot product (back-facing)
                   → Returns null (no selection) ✓

  User rotates globe → Views South America → Click Argentina
                    → Argentina passes dot product (front-facing)
                    → Shows Argentina data ✓

Why Not Just...?

Why not limit ray distance?

Setting raycaster.far = 2 (just past the globe surface) doesn't work because:

The exact distance varies with camera zoom
The back of the globe might still be within range at certain angles
You'd miss legitimate clicks on countries at the "edges" of visibility

Why not use backface culling?

Three.js meshes have a side property (FrontSide, BackSide, DoubleSide). Setting material.side = FrontSide makes back-facing triangles invisible, but:

Raycasting still hits back-facing triangles (culling is render-time only)
Country meshes need DoubleSide for proper rendering from all angles

Even if back-facing triangles aren't rendered, raycasting operates on geometry, not fragments—so invisible faces still participate in intersection tests.

Why not just take the first intersection?

We do take the first intersection—but only after filtering out back-facing ones. The key insight is that "first by distance" isn't the same as "first that's visible to the user."

Performance Results

Selection Latency

Method	Time	Complexity
CPU Raycasting (before)	45ms	O(n)
GPU Pixel Read (after)	<1ms	O(1)
Improvement	99.5% faster	—

Bug Fix Verification

After the fix:

Visible countries are always selectable
Back-facing countries are never selectable (until you rotate to face them)
Gaps between borders no longer cause incorrect picks
Hover tooltips follow the same front-facing rule

Memory Overhead

Asset	Size	Notes
ID Texture (desktop)	~8MB	2048x1024 RGBA
ID Texture (mobile)	~2MB	1024x512 RGBA
Lookup JSON	~50KB	Gzipped to ~15KB
Selection Mask	~8MB	Same size as ID texture

The ~16MB GPU memory overhead is acceptable for the performance and UX gains.

How to Verify

# In Chrome DevTools Performance panel:
1. Start recording
2. Click 10 countries rapidly
3. Stop recording
4. Expand "Event Log" → filter for "click"
5. Check "Total Time" for each click event

# Expected:
# Before: 40-50ms per click
# After: <5ms per click (including render)

Tradeoffs and Gotchas

When GPU Picking Works Best

Large number of selectable objects: The more objects, the bigger the win over raycasting
Simple selection (point picking): More complex queries (area selection, proximity) still need CPU
Static or infrequently changing scenes: Regenerating the ID texture is expensive
Known set of selectable objects: IDs must be pre-assigned

When to Stick with Raycasting

Few objects (<50): Raycasting is fast enough, GPU picking adds complexity
Dynamic scenes: Objects added/removed frequently make ID texture maintenance costly
Need intersection details: Raycasting gives you the exact point, normal, UV coordinates
Complex queries: "Find all objects within radius" requires CPU

Common Mistakes

Forgetting to flip Y coordinates: WebGL's origin is bottom-left, DOM's is top-left

// ❌ Wrong: DOM coordinates directly
renderer.readRenderTargetPixels(texture, x, y, 1, 1, buffer);

// ✅ Correct: Flip Y for WebGL
renderer.readRenderTargetPixels(texture, x, texture.height - y, 1, 1, buffer);

Using wrong texture filters: ID textures need NearestFilter to prevent color interpolation

// ❌ Wrong: Linear filtering blends colors at edges
texture.minFilter = LinearFilter;

// ✅ Correct: Nearest filtering preserves exact colors
texture.minFilter = NearestFilter;
texture.magFilter = NearestFilter;

Not handling edge case: index 0: Reserve RGB(0,0,0) for "no country" (ocean, background)

decodeCountryId(r: number, g: number, b: number): string | null {
  const index = (r << 16) | (g << 8) | b;
  if (index === 0) return null;  // Background/ocean
  return this.indexToIdMap.get(index) ?? null;
}

Enabling mipmaps: Mipmaps blend colors at lower detail levels, corrupting IDs

// ❌ Wrong: Mipmaps blend colors
texture.generateMipmaps = true;

// ✅ Correct: No mipmaps for ID textures
texture.generateMipmaps = false;

The Dot Product Edge Case

At exactly 90 degrees (dot product = 0), the point is on the "equator" between hemispheres. We use > 0 rather than >= 0 to be conservative—if you're looking edge-on at a country, you probably didn't mean to click it.

Key Takeaways

GPU picking trades memory for speed: An extra texture gives O(1) selection regardless of mesh count
Encode IDs in RGB channels: 24 bits = 16.7 million unique IDs, more than enough for most applications
Dot product solves hemisphere visibility: Simple vector math prevents "see-through" selection bugs
Use NearestFilter for ID textures: Linear filtering corrupts the encoded colors
Always flip Y for WebGL: DOM and WebGL coordinate systems have opposite Y directions
Adaptive resolution matters: Mobile devices need smaller textures to stay within memory budgets
Selection masks provide efficient feedback: Update a texture instead of modifying mesh materials

The 3D Global Dashboard now responds to clicks in under 1ms, and users can only select countries they can actually see. The Niger/Nigeria bug is gone.

GlobePlay - Interactive Geography, Bird Migration & Quiz

Explore 241 countries, trace bird migration paths, and test your geography knowledge on an interactive 3D globe. Built with Three.js and Angular.

globeplay.world

From Clunky Notes to Clean Markdown: I Built the Editor I Always Wanted

Emmanuel — Wed, 30 Jul 2025 01:07:07 +0000

The Problem: My Workflow Was Broken

Ever wished you could seamlessly convert rich-text notes into perfect Markdown? We've all been there. You're trying to quickly draft a README, a blog post, or project documentation. You start in a rich-text editor for the ease of formatting, but eventually, you need to convert it to clean, portable Markdown.

That's where the pain starts. You copy-paste the content and spend the next 15 minutes manually fixing broken lists, wrestling with mangled code blocks, and cleaning up weird HTML artifacts. I was tired of this clunky, inefficient workflow. I wanted a tool that provided the fluid, visual experience of a WYSIWYG editor but was built from the ground up to produce perfect Markdown.

So, I decided to build it myself. In this article, I'll walk you through how I built the Markdown Converter: Effortless & Perfect, the tech stack I chose, the architectural challenges I overcame, and how it all came together.

Better by Design: The Right Architecture for a Superior Tool

To build a better editor, I focused on two things: a solid technical foundation and a user experience that genuinely solves problems.

The app is built using key design patterns like the Component-Service architecture and Dependency Injection to keep the UI logic separate from the business logic. This makes the code clean, testable, and scalable. For a snappy, modern feel, it uses Angular Signals for efficient, reactive state management.

This architecture supports what makes the converter different from the countless others out there:

A True Rich-Text First Experience: Instead of a plain textbox, you get a powerful, TipTap-based WYSIWYG editor. It’s as easy to use as a word processor but outputs perfect Markdown. This wasn't a straightforward integration, however. TipTap, while incredibly powerful and headless, is primarily built with other frameworks like React and Vue in mind. Getting it to play nicely with Angular required some dedicated effort. I had to research and eventually leverage an Angular community npm package (ngx-tiptap) I found on GitHub, which provided the necessary bindings to make TipTap truly feel at home within an Angular application. This meant diving into its specific implementation nuances and adapting it to my component structure, adding a challenging but ultimately rewarding layer to the development process.
An Intelligent Import System: Go beyond copy-paste. You can import directly from a file, fetch content from a URL, or use built-in templates for READMEs, blog posts, and more to accelerate your workflow.

The Struggle: A Dark Mode That Was Actively Hostile

One of the biggest challenges was implementing a truly high-quality dark mode. My first attempt was simple: add a .dark class to the element and use Tailwind's dark: variants. This worked for the main UI, but the notification toasts were a disaster.

The Problem: The initial notifications used light-colored text on vibrant backgrounds (e.g., white text on a green success toast). In dark mode, this created a jarring, low-contrast experience that was genuinely hard to read.

The Solution: I had to re-architect the notification styling. Instead of just inverting colors, I created a new color strategy focused on readability.

High-Contrast Backgrounds: I chose new medium-brightness background colors for each notification type.
Dark Text on Color: The key insight was to switch to dark gray text on these colored backgrounds, which provided excellent contrast and made the text pop.
CSS Specificity: To enforce these new styles, I had to carefully manage my CSS rules, sometimes using !important to override base styles that were bleeding through from the component library.

Here’s a snippet of the CSS that solved it. Notice the use of dark gray (#374151) for text, even in dark mode.

CSS

/* Dark mode notification architecture */
html.dark .alert-success {
  background-color: #16a34a;  /* Vibrant but readable background */
  color: #374151;            /* High contrast dark gray text */
}

html.dark .alert-success .alert-title {
  color: #374151 !important;  /* Override base styles */
}

This experience was a powerful lesson: a feature isn't "done" until it works well for everyone in every context. This kind of problem-solving—identifying an issue, architecting a solution, and documenting it—is exactly what makes a good developer great.

The Result: The Markdown Editor I Always Wanted

After weeks of development and refinement, the Markdown Converter: Effortless & Perfect is live. It’s a fast, responsive, and feature-rich tool that has genuinely improved my own workflow.

Here is the powerful Import Modal in action, showing the file, URL, and template options:

And here's the final dark mode, with the high-contrast notifications we just discussed:

I'm incredibly proud of how it turned out. The architecture is solid, the feature set is robust, and it solves the exact problem I set out to fix.

Key Learnings & What's Next

This project was a fantastic learning experience. My main takeaways were:

Architecture First: A clean separation of concerns from day one prevents countless headaches later.
The Last 10% is Everything: A feature like "dark mode" is more than a toggle; it requires deep thought about accessibility and user experience to be truly complete.
Embrace the Ecosystem: Leveraging powerful open-source libraries like TipTap and Turndown allowed me to focus on building unique features instead of reinventing the wheel.

As for the future, I'm already planning features like real-time collaboration to enable seamless team workflows, cloud sync for universal access, and an extensible plugin system for greater customization.

Now It's Your Turn!

Thank you for reading about my project! I built this tool for developers and writers like you.

🚀 Check out the live demo and try it for yourself!

⭐ Dive into the source code on GitHub. I welcome feedback, issues, and of course, stars!

🤔 What features would you love to see in a tool like this to further streamline your workflow?

Let me know your thoughts in the comments below!

Never Sleep Again: How I Built AwakeLock, a Robust, Multi-Layered Solution for Web Wake Locks

Emmanuel — Wed, 30 Jul 2025 01:06:05 +0000

Have you ever been frustrated by your screen dimming or your device falling asleep in the middle of a critical presentation, a long running data process, or while you're simply trying to follow a recipe online? It's a common nuisance that can disrupt workflows and user experience. As a developer, I decided to tackle this head on, building AwakeLock – a sophisticated, multi-layered JavaScript library designed to prevent device sleep with intelligent fallbacks, performance monitoring, and seamless framework integrations.

This article will dive into how AwakeLock solves this pervasive problem, its core architecture, the clever strategies it employs, and why it's a project that showcases robust engineering for any developer or recruiter looking for a deep technical understanding.

The Problem: When Your Device Just Won't Stay Awake

Modern web applications increasingly need to keep a device active. Think about:

Dashboards: Monitoring real-time data or analytics.
Presentations: Displaying slides without interruption.
Long Forms/Workflows: Preventing session timeouts or lost progress.
Media Playback: Ensuring audio or video continues uninterrupted.
Kiosks or Information Displays: Keeping the screen on indefinitely.

Relying solely on native browser APIs can be unreliable due to varying support and strict permission models. That's where AwakeLock steps in to provide a bulletproof solution.

My Solution: AwakeLock's Intelligent Wake Lock System

AwakeLock is more than just a wrapper around navigator.wakeLock.request(). It's a comprehensive library that ensures your device stays awake through a hierarchical system of strategies, intelligent fallbacks, and proactive performance management. Its main purpose is to provide a reliable, cross-browser, and easy-to-use API for maintaining a wake lock.

Diving Deep: AwakeLock's Architecture and Technical Prowess

Building a truly robust wake lock solution required careful architectural design and a deep understanding of browser quirks. Here’s how AwakeLock is structured:

Project Structure at a Glance

The project is meticulously organized for clarity and maintainability. Key directories include src/ for all source code, src/strategies/ for different wake lock implementations, src/frameworks/ for framework-specific integrations, and tests/ for comprehensive testing.

awake-lock/

├── src/                       # Source code

│   ├── strategies/            # Wake lock strategy implementations

│   ├── frameworks/            # Framework-specific integrations

│   ├── utils/                 # Utility modules

│   ├── WakeLock.ts           # Main WakeLock class

│   ├── PerformanceMonitor.ts # Performance tracking

│   ├── PermissionManager.ts  # Permission handling

├── tests/                     # Test suite

├── examples/                  # Usage examples

├── dist/                      # Build outputs (ESM, CJS, UMD)

└── docs/                      # Documentation

The Central Brain: `WakeLock` Class

The src/WakeLock.ts file houses the WakeLock class, which acts as the central orchestrator. It coordinates all subsystems: managing strategies and fallbacks, emitting events, integrating with performance monitoring, and handling permissions and battery optimizations.

TypeScript

export class WakeLock extends EventEmitter<WakeLockEvents> {

  private readonly options: Required<WakeLockOptions>;

  private readonly permissionManager: PermissionManager;

  private readonly performanceMonitor: PerformanceMonitor;

  private readonly strategies: FallbackStrategy[];

private activeSentinel: InternalWakeLockSentinel | null = null;

  private currentStrategy: FallbackStrategy | null = null;

}

The Strategy Pattern: A Multi-Layered Approach

This is where AwakeLock truly shines. It employs the Strategy Pattern with a hierarchical fallback system to ensure maximum compatibility and reliability. If one method fails, it seamlessly tries the next.

ScreenWakeLockStrategy (Priority 1): Utilizes the native Screen Wake Lock API (navigator.wakeLock.request('screen')). This is the most efficient and preferred method, supported in modern Chrome, Edge, and Safari versions.
VideoElementStrategy (Priority 2): Creates a tiny, hidden video element with silent playback. Surprisingly effective, especially for mobile Safari where native API support might be limited.
AudioContextStrategy (Priority 3): Generates a silent audio context oscillator, leveraging the Web Audio API to keep the device awake.
TimerStrategy (Priority 4): As a universal last resort, this strategy uses periodic no-op setInterval operations combined with touch events and CPU activity to signal activity.

This robust fallback mechanism is crucial for ensuring a consistent experience across the fragmented browser landscape.

Strategy Selection Flow

Code snippet

flowchart TD

    A[Request Wake Lock] --> B{Screen Wake Lock API Available?}

    B -->|Yes| C[Use ScreenWakeLockStrategy]

    B -->|No| D{Video Element Supported?}

    D -->|Yes| E[Use VideoElementStrategy]

    D -->|No| F{Audio Context Available?}

    F -->|Yes| G[Use AudioContextStrategy]

    F -->|No| H[Use TimerStrategy]

    C --> I{Success?}

    E --> I

    G --> I

    H --> I

    I -->|Yes| J[Wake Lock Active]

    I -->|No| K[Try Next Strategy]

    K --> D

Permission and Performance Management

AwakeLock includes dedicated modules for PermissionManager to handle browser permission states and user interaction requirements, and PerformanceMonitor to track metrics like CPU usage, memory consumption, and battery levels. This allows for intelligent decisions, such as automatically releasing the wake lock on low battery (below 15% threshold) to preserve device life.

Framework Integrations

To make AwakeLock effortless to use in popular frontend frameworks, I built specific integrations:

✅ React

TypeScript

const { request, release } = useWakeLock();

✅ Vue

TypeScript

const { request } = useWakeLock(); // composition API

✅ Angular

TypeScript

this.wakeLockService.request().subscribe();

These integrations significantly enhance developer experience and adoption.

Key Design Patterns Utilized

The architecture consciously employs several classic design patterns:

Strategy Pattern: For interchangeable wake lock implementations.
Observer Pattern: For a decoupled event notification system.
Facade Pattern: To provide a simple API that hides underlying complexity.
Template Method Pattern: For a consistent request/release lifecycle across strategies.
Singleton Pattern: For framework services maintaining a single instance.

This structured approach ensures the library is robust, extensible, and maintainable.

Challenges Faced & How I Overcame Them

Building a cross-browser, reliable wake lock solution came with its share of hurdles:

Browser Inconsistencies: The biggest challenge was the fragmented support for native Wake Lock APIs and the varying behaviors of background processes across browsers. My solution was the multi-layered strategy pattern, ensuring that if one method fails or isn't supported, AwakeLock intelligently falls back to the next reliable option.
Resource Management: Preventing memory leaks and optimizing for battery life were crucial. I overcame this by implementing modern cleanup mechanisms using pagehide and visibilitychange events, ensuring resources are released efficiently when no longer needed.
Permission Handling: Browsers often require explicit user interaction for sensitive APIs. The PermissionManager was built to gracefully handle these scenarios, guiding users through necessary prompts and ensuring a smooth experience.

Why AwakeLock Stands Out: A Brief Comparison with NoSleep.js

While projects like NoSleep.js have been valuable, AwakeLock offers a more comprehensive and robust solution:

Multi-Strategy Reliability: Unlike simpler solutions that often rely on a single method (e.g., a hidden video), AwakeLock employs a prioritized, multi-layered strategy system for superior compatibility and resilience across browsers.
Intelligent Resource Management: AwakeLock actively monitors performance and optimizes battery usage, automatically releasing the wake lock on low battery, a feature typically absent in basic implementations.
Seamless Framework Integration: It provides first-class, idiomatic integrations for React, Vue, and Angular, simplifying usage and ensuring proper lifecycle management within modern web applications.
Optimized & Modern: Built with a focus on a tiny bundle size (7KB gzipped) and modern tooling, AwakeLock is highly performant and maintains clean, up-to-date practices.

Innovation & Impact: Why AwakeLock Matters

What makes AwakeLock truly unique and a project I'm particularly proud of:

Robust Fallback System: The intelligent priority-based strategy selection ensures maximum compatibility across over 95% of browsers.
Comprehensive Monitoring: Integrating performance and battery monitoring sets it apart, allowing for responsible resource usage.
Framework Agnostic & Specific: While core functionality is framework-agnostic, providing first-class integrations for React, Vue, and Angular makes it incredibly accessible to a broad developer audience.
Significant Performance Optimizations: Through meticulous build optimizations, I achieved a remarkable 59% bundle size reduction, resulting in a tiny 7KB gzipped UMD build. This minimal footprint ensures it's lightweight and performant.
Developer Experience Focus: From zero build warnings to comprehensive testing and clear documentation, the project prioritizes a smooth developer experience.

AwakeLock demonstrates a deep understanding of browser APIs, robust architectural design, and a commitment to performance and developer-friendliness.

Explore AwakeLock: See the Code in Action

AwakeLock is production-ready, thoroughly tested, and actively maintained.

Project Demo: See AwakeLock in action with React on StackBlitz: Live Demo and on Netlify
GitHub Repository: Want to dive into the code, contribute, or fork the project? Check out the full source code on GitHub: Source Code

I invite you to explore the repository, run the examples, and even contribute if you find an opportunity for improvement. Your feedback is highly welcome!

Conclusion: A Reliable Solution for a Common Web Challenge

Building AwakeLock has been an incredible journey, solidifying my skills in robust library design, cross-browser compatibility, performance optimization, and developer tooling. It represents a practical solution to a common web development challenge, delivered with a focus on reliability, extensibility, and user experience.

I hope this deep dive into AwakeLock's architecture provides valuable insights into how complex browser behaviors can be tamed with thoughtful engineering and a multi-layered approach. Feel free to reach out with any questions or thoughts!

Forem: Emmanuel

Your Financial Data Should Live on Your Device. Here Is the Architecture That Makes That Possible.

The Privacy Paradox of Financial Apps

What "Local-First" Actually Means

Layer 1: IndexedDB as the Source of Truth

Layer 2: TanStack Query as a Smart Cache, Not the Source of Truth

Layer 3: The Repo Router, One Interface, Three Backends

The Data Flow

Layer 4: The Sync Engine, Changelog Over Full-Table Sync

Layer 5: End-to-End Encryption with Web Crypto API

The UX Result

What This Architecture Costs

Why This Pattern Scales

Start Here

How a Branded Cents Type Eliminated an Entire Class of Bugs Across 97 Files

The Penny That Should Not Exist

Why Floating-Point Arithmetic Hates Your Money

The Naive Fix (And Why It Still Fails)

Enter TypeScript Branded Types

Why Even Addition Gets Its Own Function

The Performance Play: Caching Intl.NumberFormat

Being Honest About Uncertainty: The ConversionResult Pattern

What 928 Occurrences Across 97 Files Looks Like

What Almost Broke Me

What I Learned (If I Built This Again)

Start Here

Building a Local-First 3D Dashboard with IndexedDB: 89% Cache Hit Rate

The Problem: Network-Dependent 3D Visualization

The Solution: Local-First Architecture

Architecture: 4 Specialized Databases

Implementation: The idb Library

Database Schema Definition

Database Initialization

Persistent Local State

User Data (Permanent Storage)

API Cache with TTL (7-Day Expiration)

Data Freshness & Consistency

Cache Version Management

Sync & Performance Strategy

Cloud Sync with Debouncing

Multi-Layer Caching for Three.js

Browser Console Helpers

Performance Results

Cache Hit Rates

Overall Impact

Why Not Service Workers?

Tradeoffs and Gotchas

When Local-First Makes Sense

When to Skip Local-First

Common Mistakes

Key Takeaways

GlobePlay - Interactive Geography, Bird Migration & Quiz

Angular Signals + Three.js: How We Hit 60fps Without Going Zoneless

The Problem: Zone.js Meets requestAnimationFrame

Why Not Just Use Experimental Zoneless?

The Solution: Three Interlocking Patterns

Pattern 1: OnPush Everything

Pattern 2: Signals for Reactive State

Pattern 3: Render-on-Demand

Triggering Renders: The Event-Driven Approach

1. Camera Movement (OrbitControls)

2. User Interactions in Components

Signals + Effects for Angular-Three.js Bridge

App Configuration: Event Coalescing

Performance Results

Before Optimization

After Optimization

How to Measure

Additional Optimizations (Optional)

Tradeoffs and Gotchas

When This Pattern Works Best

When to Consider Full Zoneless

Common Mistakes

The requestRender() Checklist

Key Takeaways

GlobePlay - Interactive Geography, Bird Migration & Quiz

O(1) Country Selection on a 3D Globe with GPU Picking and Hemisphere Detection

The Problem: Two Bugs, One Globe

Bug 1: Slow Selection (45ms per click)

Bug 2: See-Through Selection (The Niger/Nigeria Problem)

The `requestRender()` Checklist

The Central Brain: `WakeLock` Class