Cache-First Firebase Development

This skill enforces Firebase read optimization patterns to prevent excessive costs and improve performance through cache-first data loading, comprehensive ReadCounter tracking, and optimized real-time listeners.

Critical Context

This workflow was developed in response to a **58 million Firebase read incident** that resulted in significant unexpected costs. ALL Firebase development must prioritize read efficiency and implement comprehensive caching.

Standard Development Workflow

1. **Planning Phase**

- Think through the problem and read relevant codebase files

- Write a detailed plan to `todo.md` with checkable todo items

- Check in with the user to verify the plan before proceeding

2. **Implementation Phase**

- Work through todo items, marking complete as you go

- Provide high-level explanations of changes at each step

- Keep every change as simple as possible, impacting minimal code

- Focus on simplicity over complexity

3. **Review Phase**

- Add a review section to `todo.md` summarizing changes

- Include relevant information about Firebase read optimization

- Document cache hit rates and cost savings

Mandatory Firebase Requirements

1. Cache-First Data Loading (REQUIRED)

Every component that reads Firestore data MUST:

Load from cache immediately for instant display

Fetch updates from Firestore in background

Use `chatCacheService` pattern as the standard reference

Store data in localStorage with proper serialization

**Implementation Pattern:**

```javascript

const cachedData = cacheService.getCachedData(key);

if (cachedData) {

setData(cachedData);

readCounter.recordCacheHit('collection', 'Component', cachedData.length);

} else {

readCounter.recordCacheMiss('collection', 'Component');

// Fetch from Firestore and cache

}

```

2. ReadCounter Integration (REQUIRED)

ALL Firestore operations must be tracked:

```javascript

// Record cache hits

readCounter.recordCacheHit(collection, component, savedReads);

// Record cache misses

readCounter.recordCacheMiss(collection, component);

// Record actual reads

readCounter.recordRead(operation, collection, component, count);

```

3. Real-Time Listener Optimization (REQUIRED)

Implement optimized listeners:

```javascript

const latestTimestamp = cacheService.getLatestTimestamp(key);

const unsubscribe = service.subscribeToNewData(

key,

(newData, isIncremental) => {

if (isIncremental) {

const updatedData = cacheService.appendNewData(key, newData);

setData(updatedData);

} else {

setData(newData);

cacheService.setCachedData(key, newData);

}

latestTimestamp

);

```

Cache Service Architecture

Every data type needs a dedicated cache service following this pattern:

```javascript

class DataCacheService {

constructor() {

this.CACHE_PREFIX = 'focal_data_';

this.CACHE_VERSION = '1.0';

this.MAX_CACHE_AGE = 7 * 24 * 60 * 60 * 1000; // 7 days

}

getCachedData(key) { /* implementation */ }

setCachedData(key, data) { /* implementation */ }

clearCache(key) { /* implementation */ }

getLatestTimestamp(key) { /* implementation */ }

appendNewData(key, newData) { /* implementation */ }

}

```

Prohibited vs Required Patterns

❌ PROHIBITED

Direct `getDocs()` or `onSnapshot()` without caching layer

Real-time listeners without cache optimization

Pagination without cache management

Any data fetching without ReadCounter tracking

✅ REQUIRED

Cache-first loading for all Firestore data

ReadCounter tracking on all operations

Optimized listeners with `startAfter()` queries

Proper cleanup of listeners

Performance Standards

**Initial Load**: <2 seconds for cached data display

**Cache Hit Rate**: >80% for returning users within 24 hours

**Read Efficiency**: <10 reads per user session for cached content

**Memory Usage**: localStorage cache <10MB per user

Code Review Checklist

Before completing any Firebase-related task, verify:

[ ] Cache-first data loading implemented

[ ] ReadCounter integration on all operations

[ ] Optimized real-time listeners with timestamp filtering

[ ] Proper listener cleanup in useEffect

[ ] Cache hit rate >80% validated

[ ] No direct Firestore queries without caching

[ ] Cost impact assessed and acceptable

Cache Invalidation Strategies

**Time-based**: Automatic expiration (1-7 days)

**Event-based**: Clear on relevant data changes

**Version-based**: Clear on data structure changes

**Manual**: Provide debugging cache clear functions

LocalStorage Management

Use consistent cache key naming: `focal_{dataType}_{identifier}`

Implement cache versioning for structure changes

Set reasonable expiration times

Limit cache size to prevent overflow

Handle Firebase Timestamp serialization properly

Development Commands

```bash

Start development server

npm start

Build for production

npm run build

Run tests

npm test

Run linting

npm run lint

npm run lint:fix

```

Reference Implementation

See `ChatContext` and `ChatCacheService` in the codebase for the standard implementation pattern of cache-first loading with ReadCounter integration.

Constraints

NEVER write Firebase code without planning the caching strategy first

ALWAYS track all Firestore operations with ReadCounter

NEVER create full collection listeners - use optimized queries

ALWAYS implement proper cleanup to prevent memory leaks

NEVER approve code that bypasses these requirements

Cache-First Firebase Development

Cache-First Firebase Development

Critical Context

Standard Development Workflow

Mandatory Firebase Requirements

1. Cache-First Data Loading (REQUIRED)

2. ReadCounter Integration (REQUIRED)

3. Real-Time Listener Optimization (REQUIRED)

Cache Service Architecture

Prohibited vs Required Patterns

❌ PROHIBITED

✅ REQUIRED

Performance Standards

Code Review Checklist

Cache Invalidation Strategies

LocalStorage Management

Development Commands

Start development server

Build for production

Run tests

Run linting

Reference Implementation

Constraints

Reviews (0)