Data Service Pattern

Each panel's data comes from a dedicated service module in

src/services/

Circuit Breaker

The circuit breaker prevents cascading failures when an API is down. After N consecutive failures, it enters "cooldown" mode and serves cached data instead of hitting the API.

Create

src/utils/circuit-breaker.ts

interface CircuitState {
  failures: number;
  cooldownUntil: number;
}

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

export interface CircuitBreakerOptions {
  name: string;
  maxFailures?: number;
  cooldownMs?: number;
  cacheTtlMs?: number;
}

export class CircuitBreaker<T> {
  private state: CircuitState = { failures: 0, cooldownUntil: 0 };
  private cache: CacheEntry<T> | null = null;
  private name: string;
  private maxFailures: number;
  private cooldownMs: number;
  private cacheTtlMs: number;

  constructor(options: CircuitBreakerOptions) {
    this.name = options.name;
    this.maxFailures = options.maxFailures ?? 2;
    this.cooldownMs = options.cooldownMs ?? 5 * 60 * 1000;  // 5 minutes
    this.cacheTtlMs = options.cacheTtlMs ?? 10 * 60 * 1000; // 10 minutes
  }

  isOnCooldown(): boolean {
    if (Date.now() < this.state.cooldownUntil) return true;
    if (this.state.cooldownUntil > 0) {
      this.state = { failures: 0, cooldownUntil: 0 };
    }
    return false;
  }

  getCached(): T | null {
    if (this.cache && Date.now() - this.cache.timestamp < this.cacheTtlMs) {
      return this.cache.data;
    }
    return null;
  }

  recordSuccess(data: T): void {
    this.state = { failures: 0, cooldownUntil: 0 };
    this.cache = { data, timestamp: Date.now() };
  }

  recordFailure(error?: string): void {
    this.state.failures++;
    if (this.state.failures >= this.maxFailures) {
      this.state.cooldownUntil = Date.now() + this.cooldownMs;
      console.warn(`[${this.name}] Cooldown for ${this.cooldownMs / 1000}s`);
    }
  }

  async execute<R extends T>(fn: () => Promise<R>, defaultValue: R): Promise<R> {
    if (this.isOnCooldown()) {
      const cached = this.getCached();
      return (cached as R) ?? defaultValue;
    }
    const cached = this.getCached();
    if (cached !== null) return cached as R;
    try {
      const result = await fn();
      this.recordSuccess(result);
      return result;
    } catch (e) {
      console.error(`[${this.name}] Failed:`, e);
      this.recordFailure(String(e));
      return defaultValue;
    }
  }
}

export function createCircuitBreaker<T>(options: CircuitBreakerOptions): CircuitBreaker<T> {
  return new CircuitBreaker<T>(options);
}

Service Module Pattern

Each service is a TypeScript module that exports async data-fetching functions:

// src/services/stock-market.ts
import { createCircuitBreaker } from '../utils/circuit-breaker';

export interface StockQuote {
  symbol: string;
  name: string;
  price: number | null;
  change: number | null;
  sparkline?: number[];
}

const breaker = createCircuitBreaker<StockQuote[]>({
  name: 'StockMarket',
  cacheTtlMs: 60_000, // 1 minute cache
});

export async function fetchStockQuotes(symbols: string[]): Promise<StockQuote[]> {
  return breaker.execute(async () => {
    const params = new URLSearchParams({ symbols: symbols.join(',') });
    const resp = await fetch(`/api/stocks?${params}`);
    if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
    return resp.json();
  }, []);
}

Optional Query Parameter Pattern

When a service function accepts optional filter arguments (e.g.

owner?

repo?

branch?

URLSearchParams

undefined

Template

export async function fetchItems(
  required: string,
  owner?: string,
  repo?: string,
  branch?: string,
): Promise<Item[]> {
  return breaker.execute(async () => {
    // 1. Start with required params
    const params = new URLSearchParams({ required });

    // 2. Conditionally append optional params
    if (owner)  params.set('owner',  owner);
    if (repo)   params.set('repo',   repo);
    if (branch) params.set('branch', branch);

    // 3. Append query string only when there are params
    const qs = params.toString();
    const url = qs ? `/api/items?${qs}` : '/api/items';

    const resp = await fetch(url);
    if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
    return resp.json();
  }, []);
}

Real-world example — GitHub workflow runs

// src/services/code-status.ts
import { createCircuitBreaker } from '../utils/circuit-breaker';

export interface WorkflowRun {
  id: number;
  name: string;
  status: string;
  conclusion: string | null;
  created_at: string;
  html_url: string;
}

const breaker = createCircuitBreaker<WorkflowRun[]>({
  name: 'CodeStatus',
  cacheTtlMs: 60_000, // 1 minute cache
});

/**
 * Fetches recent GitHub workflow runs.
 * owner and repo are optional — if omitted the server uses defaults
 * defined in the API proxy (e.g. from environment variables).
 */
export async function fetchWorkflowRuns(
  owner?: string,
  repo?: string,
): Promise<WorkflowRun[]> {
  return breaker.execute(async () => {
    const params = new URLSearchParams();
    if (owner) params.set('owner', owner);
    if (repo)  params.set('repo',  repo);

    const qs = params.toString();
    const resp = await fetch(qs ? `/api/github?${qs}` : '/api/github');
    if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
    return resp.json();
  }, []);
}

Rules for optional params

params.set(key, value)

if (value)

key=undefined

key=

URLSearchParams

fetch

params.toString()

?

new URLSearchParams().toString()

""

qs ? url?${qs} : url

params.set()

Testing optional params in isolation

Because URL construction is pure logic, test it separately before wiring up the fetch:

function buildGithubParams(owner?: string, repo?: string): string {
  const params = new URLSearchParams();
  if (owner) params.set('owner', owner);
  if (repo)  params.set('repo',  repo);
  return params.toString();
}

// Examples
buildGithubParams();                    // ""
buildGithubParams('acme');              // "owner=acme"
buildGithubParams('acme', 'dashboard'); // "owner=acme&repo=dashboard"
buildGithubParams(undefined, 'dash');   // "repo=dash"

Extract this helper when the same param set is used in multiple service functions.

Key Patterns

1. One circuit breaker per API endpoint — create at module level
2. Export typed interfaces for data shapes
3. Wrap fetch calls in

   breaker.execute(fn, defaultValue)

4. Default values are empty arrays

   []

   or empty objects

   {}

5. Services are stateless modules — no class instances, just exported functions
6. API proxy: Frontend calls

   /api/...

   which proxies to external APIs (hides API keys)
7. Optional params: Use

   URLSearchParams

   + conditional

   params.set()

   — never build query strings by hand

API Proxy Pattern

For APIs requiring keys, create server-side proxy endpoints:

// api/github.ts (Vercel serverless function)
export default async function handler(req, res) {
  // Read optional overrides from the query string; fall back to env defaults
  const owner = (req.query.owner as string) ?? process.env.GITHUB_OWNER;
  const repo  = (req.query.repo  as string) ?? process.env.GITHUB_REPO;
  const token = process.env.GITHUB_TOKEN;

  const url = `https://api.github.com/repos/${owner}/${repo}/actions/runs?per_page=10`;
  const data = await fetch(url, {
    headers: { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json' },
  });
  res.json(await data.json());
}

This keeps API keys server-side, forwards only the safe query parameters the frontend supplies, and provides a single endpoint for the frontend.