---
title: "Data Flow Map"
canonical: "https://pharos.watch/docs/data-flow-map/"
description: "Source-to-UI map for Pharos stablecoin data, covering market prices, peg monitoring, liquidity, report cards, alerts, and generated public artifacts."
---

# End-to-End Data Flow Map

## Overview

This map links each major Pharos data domain from upstream source to frontend consumption:

`external source -> worker cron / sync -> D1 table or cache key -> API endpoint -> frontend hook -> page(s)`

## Core Flows

| Domain | External Sources | Worker Ingest / Compute | Storage Layer | API Surface | Frontend Hook(s) | Primary UI |
|-------|------------------|--------------------------|---------------|-------------|------------------|------------|
| Stablecoin core list + prices | DefiLlama, CoinGecko, CMC, DexScreener, DexPaprika, CoinGecko Onchain, Alchemy Prices, Moralis token prices, Birdeye token prices, Pyth Network, Binance, Kraken, Bitstamp, Coinbase, RedStone, GeckoTerminal pool probes, Curve on-chain, protocol redemption quotes, Chainlink FX/commodity overlays, FX sources (Frankfurter, Open Exchange Rates, `fawazahmed0/currency-api`, ExchangeRate-API), and `gold-api.com` commodity references | `worker/src/cron/sync-fx-rates.ts`, `worker/src/cron/sync-stablecoins.ts`, stage modules under `worker/src/cron/sync-stablecoins/`, `worker/src/lib/address-price-providers/index.ts`, `worker/src/lib/authoritative-price-sources/`, `worker/src/lib/price-consensus.ts`, `worker/src/lib/price-validation.ts` | `cache` keys: `fx-rates`, `stablecoins` | `GET /api/stablecoins` | `useStablecoins` | Homepage, Compare, Dependency Map, many cards |
| Aggregate stablecoin charts | DefiLlama aggregate chart history, D1 `supply_history` overlays for structural supplemental tracked assets, live `stablecoins` cache for the trailing point | `worker/src/cron/sync-stablecoin-charts.ts` + read-time hydration in `worker/src/api/cache-handlers.ts` | `cache` key: `stablecoin-charts` (+ live `stablecoins` cache at read time) | `GET /api/stablecoin-charts` | `useStablecoinCharts` | Homepage charts |
| Stablecoin detail history | DefiLlama detail/chart, CoinGecko fallback, `supply_history` fallback paths | On-demand detail handler plus `worker/src/cron/snapshot-supply.ts` / `worker/src/api/backfill-supply-history.ts` | Handler-computed detail payload, per-coin D1 cache, `supply_history` | `GET /api/stablecoin/:id`, `GET /api/supply-history` | `useStablecoinDetailViewModel`, `useSupplyHistory`, `usePrefetchStablecoin` for hover prefetch only | Stablecoin detail market chart, Compare |
| Per-coin supply history | Cached stablecoins payload snapshot, CoinGecko or DefiLlama backfills | `worker/src/cron/snapshot-supply.ts`, `worker/src/api/backfill-supply-history.ts` | `supply_history` | `GET /api/supply-history` | `useSupplyHistory`, `useCompareDataModel` | Stablecoin detail page, Compare |
| Depeg events + peg summary | Stablecoin cache prices + DEX corroboration | `worker/src/cron/detect-depegs.ts` (+ pending confirmation) | `depeg_events`, `depeg_pending` | `GET /api/depeg-events`, `GET /api/peg-summary` | `useInfiniteDepegEvents`, `usePegSummary` | Depeg page, homepage peg columns, detail cards |
| Depeg Duration Resolver + Reviewer | Confirmed canonical depeg incidents, stablecoin metadata, supply history, DEWS, liquidity, redemption backstops, first-publication manifests, errata, and later canonical outcomes | `worker/src/cron/compute-depeg-resolver.ts` plus `worker/src/cron/compute-depeg-resolver-review.ts` helper after DDRv2 sealing/publication | DDRv2 incident/link/lock-state/public-prediction/publication/errata tables, `depeg_resolver_assessments`, `cache["depeg-resolver:snapshot"]`, `cache["depeg-resolver-review:snapshot"]` | `GET /api/depeg-resolver`, `GET /api/depeg-resolver-review` | `useDepegResolver`, `useDepegResolverReview` | Depeg page DDR and DDRR modules |
| DEX liquidity + DEX implied prices | DefiLlama Yields, DefiLlama Protocols, Curve, Uniswap/Aerodrome/PancakeSwap subgraphs, protocol-native APIs (Fluid, Balancer, Raydium, Orca, Meteora), Fluid DexReservesResolver on supported EVM chains, Aerodrome/Velodrome Slipstream Sugar view contracts on Base/Optimism, plus `CG/GT/DexScreener/CG Tickers -> [discovery cron] -> dex_pool_staging (D1)` | `worker/src/cron/dex-discovery/orchestrator.ts` (`t1/t2/t3` tiered priority + exponential backoff, staleness sorting + live FX/metal validation refs) and `worker/src/cron/dex-liquidity/*` orchestrator merge (`max(0.5, 1 - ageHours / 48)` confidence decay + live FX/metal validation refs); GeckoTerminal request/parse normalization is shared in `worker/src/cron/dex-liquidity/geckoterminal-shared.ts`; direct/API/subgraph/view-contract fetchers (`fetch-fluid.ts`, `fetch-balancer.ts`, `fetch-raydium.ts`, `fetch-orca.ts`, `fetch-meteora.ts`, `fetch-pancakeswap.ts`, `fetch-slipstream.ts`) run during Step 1 of `syncDexLiquidity()`, normalized via `DexApiPool` type (`worker/src/lib/dex-api-common.ts`), preferred over overlapping DL pools only when identity is exact/uniquely derived and measured 24h volume exists, source family `direct_api` | `dex_pool_staging` -> `dex_liquidity`, `dex_liquidity_history`, `dex_prices` | `GET /api/dex-liquidity`, `GET /api/dex-liquidity-history` | `useDexLiquidity`, `useDexLiquidityHistory` | Liquidity page, Compare, report-card inputs, `/status` liquidity health card |
| Blacklist / freeze tracker | Etherscan v2, TronGrid, RPC providers | `worker/src/cron/sync-blacklist.ts` + helper modules under `worker/src/cron/blacklist/` | `blacklist_events`, `blacklist_sync_state` | `GET /api/blacklist`, `GET /api/blacklist-summary` | `useBlacklistEventsPage`, `useBlacklistSummary` | FreezeWatch page |
| Mint/Burn flow tracker | Alchemy logs (configured issuance chains; currently Ethereum plus native Arbitrum for USDai) | `worker/src/cron/sync-mint-burn.ts` + `worker/src/cron/mint-burn/run-state.ts`, slot dispatch via `worker/src/handlers/scheduled/mint-burn-slot.ts` | `mint_burn_events`, `mint_burn_hourly`, `mint_burn_sync_state` | `GET /api/mint-burn-flows`, `GET /api/mint-burn-events` | `useMintBurnFlows`, `useMintBurnFlowsCoin`, `useMintBurnEvents` | Flows page, homepage flow snapshot, coin overlays |
| Live reserve composition | Protocol reserve APIs, dashboards, and on-chain/accounting reads via adapter-specific fetches | `worker/src/cron/sync-live-reserves.ts` | `reserve_composition`, `reserve_sync_state` | `GET /api/stablecoin-reserves/:id`, `GET /api/report-cards`, `GET /api/status` | `useStablecoinReserves`, `useReportCards` | Stablecoin detail reserve card, report-card collateral quality inputs, reserve-drift/status surfaces |
| Redemption backstops + effective exit | Stablecoin cache, DEX liquidity snapshot, live reserve-sync metadata, and redeemability config registry | `worker/src/cron/sync-redemption-backstops.ts` | `redemption_backstop`, `redemption_backstop_history` | `GET /api/redemption-backstops`, `GET /api/report-cards` | `useRedemptionBackstops`, `useReportCards` | Stablecoin detail redemption card, report-card liquidity inputs |
| Stability Index (PSI) | Stablecoin cache + active depeg state + DEWS stress breadth | `worker/src/cron/stability-index.ts`, daily `worker/src/cron/snapshot-psi.ts` | `stability_index_samples`, `stability_index` | `GET /api/stability-index` | `useStabilityIndex`, `useStabilityIndexDetail` | Stability Index pages, digest snapshot |
| DEWS stress signals | Stablecoins + liquidity + blacklist + mint/burn + yield + PSI inputs | `worker/src/cron/compute-dews.ts` | `stress_signals`, `stress_signal_history` | `GET /api/stress-signals` | `useStressSignals`, `useStressSignalDetail` | Depeg tracker risk panels, homepage radar snapshot |
| Yield intelligence | On-chain rate calls, DefiLlama pools, cached supplemental protocol snapshots, CoinGecko price fallback, risk-free rate cache | `worker/src/cron/sync-yield-data.ts`, `worker/src/cron/sync-yield-supplemental.ts`, helper modules under `worker/src/cron/yield-sync/`, `worker/src/cron/fetch-tbill-rate.ts` | `yield_data`, source-aware `yield_history`, `yield_publication_generations`, `yield_source_decisions`, cache `yield-rankings`, structured benchmark cache `risk_free_rates`, legacy USD mirror `risk_free_rate`, supplemental/on-chain health caches | `GET /api/yield-rankings`, `GET /api/yield-history` | `useYieldRankings`, `useYieldHistory` | Yield page, stablecoin detail |
| Daily digest | Anthropic Claude + PSI snapshot context | `worker/src/cron/daily-digest.ts` | `daily_digest` + static build sync to `data/digests.json` | `GET /api/daily-digest`, `GET /api/digest-archive`, `GET /api/digest-snapshot` | `useDailyDigest`, `useDigestArchive`, `useDigestSnapshot` | Digest page + archive |
| Public daily dataset snapshots | Completed D1/cache artifacts: stablecoins cache, report-card cache, prior-day PSI snapshot, optional current DEWS and DEX liquidity rows | `worker/src/cron/snapshot-public-dataset.ts` | `public_snapshots` | `GET /api/snapshots/index`, `GET /api/snapshots/:date.json`, `GET /api/snapshot/:date/stablecoin/:id` | — | External integrations and historical dataset consumers |
| Report cards + dependency graph | Peg summary + DEX liquidity + redemption backstops + bluechip + stablecoin metadata/dependencies | `worker/src/api/report-cards.ts` compute on read; `worker/src/cron/publish-report-card-cache.ts` publishes the shared `report_card_cache` artifact for dependent consumers such as Chain Health and the Telegram safety-alert lane | API read path: cache-driven upstream + in-memory compute; downstream artifacts: `report_card_cache`, `cache["alert:safety-source-cache"]` | `GET /api/report-cards` | `useReportCards` | Safety Scores, Portfolio, Dependency Map, homepage safety snapshot |
| Status reliability | Real-HTTP self probes + status synthesis | `worker/src/cron/status-self-check.ts`, `worker/src/api/status.ts`, `worker/src/api/public-status-history.ts` | `status_state`, `status_transitions`, `status_probe_runs`, `status_discrepancy_state` | Public: `GET /api/health`, `GET /api/public-status-history`; admin: `GET /api/status`, `GET /api/status-history` | Public: `useHealth`, `usePublicEndpointProbes`, `usePublicStatusHistory`; admin: `useStatus`, `useEndpointProbes`, `useStatusHistory` | `/status` public health board, `/admin` operator dashboard |
| Coverage discovery | CoinGecko category API, DL stablecoins residuals | `worker/src/cron/discovery-scan.ts` (weekly, Monday-only), `worker/src/cron/sync-stablecoins/intake.ts` (DL residuals) | `discovery_candidates` | `GET /api/status` (`discoveryCandidates` field), plus direct admin `GET /api/discovery-candidates` / `POST /api/discovery-candidates/:id/dismiss` | — (admin only) | `/admin/` operator dashboard, Pipeline section |
| Chain analytics | Stablecoins cache aggregate `circulating` buckets, `chainCirculating` buckets (already aggregated by DefiLlama), report card cache (safety scores for quality sub-factor) | `worker/src/api/chains.ts` (compute on read from stablecoins + report-card D1 caches and emit freshness metadata); `worker/src/cron/snapshot-chain-supply.ts` writes daily totals to D1 | Live leaderboard: computed on-the-fly from D1 caches with `_meta` freshness; history: `chain_supply_history` | `GET /api/chains` | `useChains`, `useChainProfileData`, `useChainStablecoins` | `/chains/` leaderboard, `/chains/[chain]/` profile pages |

## Scheduling Backbone

Cron schedules are declared in `worker/wrangler.toml`, mirrored in `shared/lib/cron-jobs.ts`, and orchestrated by `worker/src/handlers/scheduled.ts`. `docs/worker-infrastructure.md` is the maintained schedule reference; this section is a compact flow map.

- `*/15 * * * *`: sync-fx-rates (cooldown-gated to 30 min) first, then sync-stablecoins (including depeg detection + pending confirmation), then downstream-safe snapshot-supply retry / snapshot-chain-supply / report-card cache publish / DDRv2 incident lock/publication projection and DDRR review snapshot
- `9,24,39,54 * * * *`: isolated status self-check, then cron-staleness-watchdog freshness alerting
- `3 */6 * * *`: blacklist sync (every 6h)
- `4,34 * * * *`: mint/burn critical lane (every 30 minutes)
- `6 */2 * * *`: DEX discovery staging (every 2h)
- `13,43 * * * *`: mint/burn extended lane (every 30 minutes)
- `10,40 * * * *`: DEX liquidity scoring
- `16,46 * * * *`: stablecoin charts (30-minute trigger, 1-hour write cooldown)
- `26,56 * * * *`: DEWS, then PSI, then tape projection on the DB-only decoupled lane
- `20 * * * *`: core yield publication
- `25 */4 * * *`: supplemental yield-source refresh
- `11 */4 * * *`: live reserve sync, then redemption backstop sync, then Kinesis supply sync, then collateral-drift checks/alerts (every 4h)
- `2,7,12,17,22,27,32,37,42,47,52,57 * * * *`: Telegram command/profile/webhook reconciliation, subscriber alerts (DEWS, depeg, safety, and launch promotions), degradation watchdog, expired disambiguation cleanup, and Telegram pulse snapshot publication
- `*/5 * * * *`: manual digest trigger poll (`POST /api/trigger-digest` flag consumer)
- `0 3 * * *`: status-probe TTL prune + cron-history TTL prune + Telegram inactive cleanup + Telegram retention cleanup (daily housekeeping)
- `0 8 * * *`: snapshot-supply fallback, safety-grade snapshot, PSI daily snapshot, snapshot-public-dataset after its DB inputs pass freshness gates, plus T-bill rate then USDS status
- `5 8 * * *`: bluechip sync, daily digest, weekly recap (Mondays)
- `10 8 * * *`: discovery scan (Mondays)
- `0 6 1 * *`: monthly yield coverage audit

## Freshness Contract (Frontend)

API hooks that use `useApiQuery` follow the interval supplied by their caller:

- `staleTime = interval`
- `refetchInterval = 2 * interval`

Defined centrally in `src/hooks/use-api-query.ts`. Cron-backed hooks should pass the producer cadence unless a documented route-specific exception applies. Current exceptions include `/api/health` (1-minute diagnostic polling, not cron-backed) and `/api/usds-status` (15-minute UI polling over a daily source snapshot).

## Notes

- **DEX price bridge**: The half-hourly DEX liquidity cron now rebuilds `dex_prices.price_sources_json` from the final retained priced-pool surface after dedupe, caps, scoring filters, and unit normalization, publishing one aggregate per protocol. The quarter-hourly pricing cron reads these via `loadDexPriceSources()` and promotes at most one individually-weighted consensus source per protocol: `fluid-dex` (weight 3), `balancer-dex` (weight 3), `curve-dex` (weight 3), `uniswap-v3-dex` (weight 2), `uniswap-v4-dex` (weight 2), `raydium-dex` (weight 2), `orca-dex` (weight 2), `meteora-dex` (weight 2), `pancakeswap-dex` (weight 2), `aerodrome-dex` (weight 2), `velodrome-dex` (weight 2). These promoted protocol sources only enter primary consensus when corroborated or when no non-DEX voices exist, and the overlapping `dex-promoted` aggregate (weight 1) is withheld only when at least one promoted protocol lane is admitted for the same asset. Rejected protocol candidates no longer suppress a valid aggregate DEX fallback. DEX admission/merge skip reasons are emitted into logs and cron metadata so stale rows, malformed snapshots, TVL filters, missing registry mappings, and duplicate identities can be traced without scraping the raw tables.
- Cache passthrough endpoints include freshness metadata via `_meta` and/or `X-Data-Age`.
- Chain profile pages intentionally coordinate two APIs: `GET /api/chains` for the summary card and `GET /api/stablecoins` for composition. The detailed sections stay hidden until both snapshots share the same `updatedAt`, which keeps incomplete or mismatched data from being presented as a full per-chain breakdown.
- `chain_supply_history` remains a forward-only internal dataset until the post-2026-04-08 baseline. Earlier rows were written before shared chain-label canonicalization and are not approved for public charting.
- `/api/dex-liquidity` is meta-aware on the frontend: the page uses worker freshness metadata (and degraded-run `Warning` headers) rather than client fetch time to assess staleness.
- Liquidity history now carries `coverageClass` / `coverageConfidence`; trend and durability consumers should treat low-confidence snapshots as informational, not authoritative baselines.
- Admin/backfill endpoints bypass edge cache via `cacheBypass` flags in `shared/lib/api-endpoints/`.
- The stablecoins cache loader distinguishes `ok`, `degraded`, and `error` states. Operator-facing or published consumers (`/status`, daily digest, safety snapshot) now fail closed on non-`ok` cache reads instead of treating broken cache state as an empty valid dataset.
- `consensusSources` flows from the price-consensus cron stage through the `stablecoins` cache → `/api/stablecoins` and `/api/peg-summary` → `useStablecoins` / `usePegSummary` hooks → `PriceTransparencyCard` on the detail page and `CoverageBadge` source-count enrichment on the coverage page.
- `priceSourceConfidenceProfile` flows from DEX-inclusive primary pricing through the `stablecoins` cache and `/api/stablecoins`. It is omitted for non-DEX prices and currently remains a data/API transparency field rather than a UI dependency.