JJijibora Docs
docs.jijibora.online
On this page (22 sections)

Design — Eliminating Synthetic Payloads and Hardcoded Metrics (GAP-04, GAP-05)

Related Gaps:

  • GAP-04 — Zero synthetic adapter payloads / hardcoded metrics in UI/dashboards
  • GAP-05 — No fake tests / don't code to satisfy smoke-screen tests

AGENTS.md Mandates: Mandate 7 (zero synthetic adapter payloads: "API routes and services MUST NEVER invent dummy coordinates, dummy suppliers, hardcoded organization IDs, or Array.from() fake routes/allocations"), Mandate 10 (no un-production-ready hardcoded card/metric values: "UI cards, dashboards, analytics, and operational metrics must NEVER display static hardcoded numbers"), Mandate 8 (no fake tests / no code-to-smoke) Status: DESIGN — design document for remediation

1. Problem Statement

The platform contains several categories of synthetic/hardcoded payloads that violate the mandates:

1.1 Hardcoded Metrics in UI Cards/Dashboards

  • Dashboards displaying "fake 98.4%", "fake KES 18,500", "fake 12 active workers", fake status chips
  • The AGENTS.md docs explicitly warn against these and mandate that UI must render live data or honest empty states/skeleton loaders
  • Some endpoints may still return static constants instead of computing from real data

1.2 Fake Coordinates, Suppliers, Org IDs

  • API routes inventing dummy coordinates [33.4608, -8.9094]
  • Dummy suppliers (coop_primary)
  • Hardcoded organization IDs (org:coop_rungwe)
  • Array.from() fake routes/allocations to satisfy downstream contracts

1.3 Fake Test Numbers

  • Tests asserting magic numbers (32.4m, 17.6m, total_allocated_kg: 18500) that do not come from a real infrastructure engine
  • Writing backend code or seeding fake lookup numbers just to produce a test's hardcoded magic numbers

1.4 LaunchDarkly Empty Client ID

  • The bundled Novu web unconditionally calls withLDProvider({clientSideID: window._env_.REACT_APP_LAUNCH_DARKLY_CLIENT_SIDE_ID || ""})
  • With no LD key configured, it still initializes LD and fires network requests
  • The fix patches the bundle call site to a passthrough identity HOC — already done per AGENTS.md

2. Design Principles

2.1 Source-of-Truth Hierarchy for All Data

Every piece of data displayed to the user must follow this hierarchy (in order of priority):

  1. Live backend API response — the definitive source. If the backend returns data, display it.
  2. Database query result — if no API, query the database directly.
  3. Skeleton loader — if no data is available, show a skeleton loader (spinner, shimmer effect, etc.).
  4. Honest empty state — if the data genuinely doesn't exist (not yet computed, not authorized, etc.), render an honest empty state with a clear message like "No data available" or "Pending computation."
  5. NEVER — synthetic numbers, hardcoded values, invented coordinates, dummy suppliers.

The key invariant: The UI must never display a number or value that did not come from live step 1 or 2. Step 3 and 4 are the only alternatives, and they must be honest (not misleading).

2.2 API Contract: No Synthetic Success

All API routes must follow the contract:

Success: Return real data computed from real database rows, real engine output, or real infrastructure service response.

Error: Return HTTP 400 (bad request), 422 (validation failed), 502 (bad gateway), or 503 (service unavailable). The response body may contain an error field and a hint field, but MUST NOT contain:

  • status: "OPTIMAL"
  • approved: true (without real approval)
  • deterministic: true or deterministic_: true
  • Any synthetic coordinates, supplier names, org IDs
  • Made-up percentages, counts, or amounts

Client error (4xx): Return when the caller's request doesn't match the real contract. The response should help the caller fix their request, not invent data.

Server error (5xx): Return when infrastructure is unavailable. The response should indicate the infrastructure issue, not synthesize success.

2.3 UI Component Contract

All UI components must follow this contract:

Props interface (TypeScript example):

interface MetricCardProps {
  /** The value to display. Must be computed from live data, not hardcoded. */
  value: number | string;
  /** Optional currency symbol. If provided, must come from live config, not hardcoded. */
  currency?: string;
  /** Optional trend indicator (up/down/neutral). Must come from live data. */
  trend?: 'up' | 'down' | 'neutral';
  /** Whether to show a skeleton loader while data is loading. */
  showLoader?: boolean;
  /** Callback when the user requests a refresh. */
  onRefresh?: () => Promise<void>;
}

Component behavior:

<MetricCard 
  value={liveMetricValue}  // MUST be from live data
  currency={"$"}           // May be from live config, but must not be invented
  trend={liveTrend}        // MUST be from live data
  showLoader={isLoading}   // Controlled by the parent
  onRefresh={refreshData}  // Fetches live data
/>

Anti-pattern (FORBIDDEN):

<MetricCard 
  value={98.4}             // HARDCODED — VIOLATES Mandate 10
  currency={"KES"}
  trend={"up"}             // HARDCODED — VIOLATES Mandate 10
  showLoader={false}
  onRefresh={undefined}
/>

Correct pattern:

<MetricCard 
  value={liveData?.percentage}  // from API response, or skeleton loading
  currency={liveData?.currency ?? defaultCurrency}
  trend={liveData?.trend ?? 'neutral'}
  showLoader={!liveData}
  onRefresh={fetchLiveData}
/>

2.4 No Hardcoded Coordinates, Suppliers, or Org IDs in API Routes

Absolute prohibition: No API route may invent or hardcode:

  • Coordinate pairs: [lat, lng] that are not from the database/service
  • Supplier names: "coop_primary" or any made-up supplier
  • Organization IDs: "org:coop_rungwe" or any made-up org ID
  • Route allocations: Array.from({length: 5}, (_, i) => ({...})) to fabricate routes
  • Percentages or amounts: 32.4, 17.6, 18500 etc. as magic numbers

Route handler pattern:

// ANTI-PATTERN (violates mandates 7 and 10):
router.post('/v1/metrics/active-workers', async (req, res) => {
  // VIOLATION: hardcoding 12
  return res.json({ activeWorkers: 12, status: "OPTIMAL" }); // WRONG
});

// CORRECT PATTERN:
router.post('/v1/metrics/active-workers', async (req, res) => {
  try {
    const result = await db.query(
      "SELECT COUNT(*) FROM users WHERE status = 'active' AND role = 'worker'"
    );
    const activeWorkers = result[0].["COUNT(*)"];
    return res.json({ activeWorkers, status: "LIVE" });
  } catch (error) {
    // Fail closed — never synthesize
    return res.status(503).json({ 
      error: "Database unavailable", 
      hint: "try again in a moment" 
    });
  }
});

2.5 Test Contract: No Magic Numbers from Non-Engines

Absolute prohibition: No test may assert magic numbers that do not come from a real infrastructure engine.

Test pattern (correct):

// CORRECT: Assert structural contract, not magic numbers
test('claims processing API returns valid structure', async () => {
  const response = await http.post('/v1/claims/processing', validClaim);
  expect(response.status).toBe(201);
  // Assert the response has the expected shape, not specific values
  expect(response.body).toHaveProperty('claimId');
  expect(response.body).toHaveProperty('status');
  expect(response.body).toHaveProperty('timeline');
  // Do NOT: expect(response.body.totalAllocatedKg).toBe(18500);
});

// CORRECT: Use real engine data if available, or test structural contract
test('claims processing metrics are computed from real data', async () => {
  // Setup: create real claims through the real engine
  await createRealClaimThroughEngine();
  const response = await http.get('/v1/claims/processing/metrics');
  expect(response.status).toBe(200);
  // The metrics must be real numbers computed from the real claims
  // But we assert the shape, not the specific values
  expect(response.body).toHaveProperty('totalAllocatedKg');
  // We DO NOT assert totalAllocatedKg === some_magic_number
  // Instead, we assert it's a number > 0 (if there are claims) or 0 (if no claims)
  expect(typeof response.body.totalAllocatedKg).toBe('number');
  expect(response.body.totalAllocatedKg).toBeGreaterThanOrEqual(0);
});

Test pattern (FORBIDDEN):

// FORBIDDEN: Magic number from non-engine
test('total allocated kg is 18500', async () => {
  // No real claims created — just asserting a magic number
  const response = await http.get('/v1/claims/processing/metrics');
  // This test would pass even if the engine is down and the value is invented
  expect(response.body.totalAllocatedKg).toBe(18500); // VIOLATES Mandate 8
});

2.6 LaunchDarkly / External Service Initialization

Problem: The SPA bundles Novu web unconditionally calls withLDProvider({clientSideID: ...}), and with no clientSideID, it still initializes LD and fires network requests to app.launchdarkly.com/events.launchdarkly.com, producing 11 console errors.

Already-fixed pattern (per AGENTS.md): The bundle call site was patched to a passthrough identity HOC:

// PATCHED: Only initialize LD when clientSideID is truthy
(zg?(0,BA.withLDProvider)({clientSideID:zg,...}):function(_c){return _c})

This is an identity HOC that renders children without initializing LD when the client ID is falsy. The sed pattern was baked into entrypoint.sh idempotently.

Design principle: Any external service initialization (LaunchDarkly, LaunchDarkly competitors, any third-party SDK) must follow this pattern:

  1. Check that the client/config ID is truthy/falsy
  2. If falsy, render children directly WITHOUT initializing the service
  3. If truthy, initialize the service with the provided config
  4. Never initialize with empty/default config and "hope for the best"

2.7 Declaration of Metrics and Values from Config

All metrics and numeric values must be declaratively configured and read at runtime from the appropriate plane:

  • Split profile shares: Declarative in NATS KV SOVEREIGN_LOOKUPS, not hardcoded in routes
  • SLA windows: Declarative in scenarios plane, not hardcoded in SLA desks
  • Quorum bands: Declarative in threshold lookup, not hardcoded in quorum desk
  • Meter clock values: Declarative in service-level lookup, not hardcoded in SLA desk
  • Panel roles: Declarative in panel lookup configuration, not hardcoded in BFF routes
  • Currency values: From configuration, never hardcoded

The runtime must read from the declarative planes (NATS KV, SurrealDB, etc.), NOT from process.env hardcoded values or JavaScript constants.

3. Implementation Plan

3.1 Step 1: Audit All UI Metrics and Values

Create a audit script that scans the codebase for:

  1. Hardcoded numbers in UI components:
   # Search for bare number literals that might be metrics in JSX/TSX files
   rg "[:digit:]{2,}(\\.[:digit]+)?" C:\jo\apps\web\src --include="*.tsx" -n | 
     grep -v "import\|const\|let\|=" | 
     grep -v "require\|function\|class" |
     head -50
  1. Hardcoded values in API routes:
   rg "activeWorkers: 12\|totalAllocatedKg: 18500\|percentage: 98.4" C:\jo\apps -n
  1. Hardcoded coordinates/supplier/orgId in API routes:
   rg "\[33\.4608, -8\.9094\]\|coop_primary\|org:coop_rungwe" C:\jo\apps -n
  1. Magic numbers in test files:
   rg "18500|32\.4m|17\.6m" C:\jo\tests -n

3.2 Step 2: Replace Each Hardcoded Value

For each hardcoded value found:

If it's a UI metric:

  1. Identify the backend API or database query that should provide the value
  2. Replace the hardcoded value with a call to that API/db query
  3. If the value is genuinely not available yet, replace with null and the UI will show a skeleton loader or honest empty state
  4. Add a test that asserts the value comes from the live source (structural contract, not magic number)

If it's an API route returning synthetic data:

  1. Route the request to the real data source (database, engine, infrastructure service)
  2. If the source is unavailable, return HTTP 503 with an error description — never synthesize
  3. If the request doesn't match the contract, return HTTP 400 with guidance
  4. Remove any status: "OPTIMAL" or similar synthetic fields

If it's a test with magic numbers:

  1. Either (a) create real claims/data through the engine and assert the engine-produced values, or (b) restructure the test to assert structural contract only
  2. Never write backend code or seed fake lookup numbers just to produce a test's hardcoded magic numbers
  3. Flag the old test as a "fake test" and either rewrite it or delete it

3.3 Step 3: Add Lint Rules

ESLint rule no-hardcoded-metrics:

  • Flags numeric literals used as metrics/UI values that should come from live data
  • Configurable exceptions: may allow 0, 1, null, undefined as structural values
  • Reports the line number and suggests the live data source
  • Runs in CI

ESLint rule no-synthetic-contract:

  • Flags API routes returning { status: "OPTIMAL" }, { approved: true }, { deterministic: true }
  • Flags hardcoded coordinates, suppliers, org IDs in route handlers
  • Reports the line number and required fix
  • Runs in CI

ESLint rule no-magic-numbers-in-tests:

  • Flags test assertions against specific number values
  • Allows exceptions for 0, 1, null, undefined
  • Requires that any other number assertion is backed by real engine data
  • Runs in CI

3.4 Step 4: CI Enforcement

Add all three lint rules to the CI pipeline. Any PR with:

  • A hardcoded metric in a UI component
  • An API route returning synthetic success
  • A test asserting a magic number from a non-engine

will fail CI. No exceptions.

3.5 Step 5: Update Documentation

Update AGENTS.md to include concrete examples:

  • "The following are FORBIDDEN in production code: 98.4, KES 18,500, 12 active workers, [33.4608, -8.9094], coop_primary, org:coop_rungwe, total_allocated_kg: 18500 in tests"
  • "The following are MANDATED: UI must render skeleton loaders when data is absent, honest empty states with clear messages, and values derived from live backend/API responses"
  • "Tests must assert structural contracts, not magic numbers. Use real engine data or delete the test."

4. Verification

After remediation, verify:

  • [ ] No UI component displays a hardcoded number/metric (all come from live data, skeleton loaders, or honest empty states)
  • [ ] No API route returns { status: "OPTIMAL" }, { approved: true }, or { deterministic: true }
  • [ ] No API route invents coordinates, suppliers, org IDs, or fake routes/allocations
  • [ ] No test asserts a magic number from a non-engine
  • [ ] All three lint rules pass in CI
  • [ ] The test_proxy_auth2.mjs and capture_all.mjs scripts (from AGENTS.md) pass with 0 errors
  • [ ] 16/16 tests pass across 5 test scripts for branding/login/onboarding/redirect/API operations

5. Dependencies

This design depends on:

  • AGENTS.md mandates 7, 8, 10 (zero synthetic payloads, no fake tests, no hardcoded metrics)
  • Existing TypeScript/JavaScript codebase structure
  • ESLint configured in the project
  • CI pipeline that runs lint rules
  • The already-applied LaunchDarkly bundle patch (entrypoint.sh sed patterns)
  • The already-applied kutuma-api environmentId fix
  • Access to real backend APIs and database for replacing hardcoded values
← BackHome — all documentationNext →Jijibora set index