Hedgehog

Hedgehog connects stock holdings to real-world events priced on Kalshi. It shows event reach, upcoming close times, the evidence behind a link, daily portfolio moves and historical calibration. It never trades.

The source files specify an npm-workspaces monorepo: web/ is the frontend (Next.js App Router and Tailwind); server/ is the backend (Express, scheduled jobs and data math); shared/ defines API response types. These names take precedence over the request's frontend/backend folder names.

Quick start

cp .env.example .env
docker compose up --build -d

Open http://localhost:3000, create an account or continue as a guest, enter tickers and dollar values, and map your exposure. Docker starts a private local TimescaleDB database when DATABASE_URL is empty. For Tiger Data, set DATABASE_URL to your service connection string. See ACCOUNTS.md for account features and a manual test checklist, and DEPLOY.md for tag approval, data loading, validation, portability and deployment.

For local development, use Node 24 and npm ci, then configure DATABASE_URL. Start npm run dev -w server and npm run dev -w web in separate terminals (the combined launcher is not Windows-compatible). The server applies migrations on startup; npm run migrate also applies them explicitly on Linux. npm run check:core runs dependency-free core accuracy checks. npm test runs Vitest known-answer and accuracy tests. npm run lint runs strict TypeScript checks; npm run build checks the backend and builds Next.js.

For Vercel, use Root Directory . and the root vercel.json. It deploys the web app and an internal Express API in one project, with a runtime service binding and authenticated Vercel Cron schedules. These schedules require Pro or Enterprise. See Vercel deployment for environment variables, migrations and testing.

Data and accuracy

Kalshi's public events and market candlesticks supply dollar bid/ask quotes; midpoint probabilities never use last trades. Yahoo Finance supplies daily closes for stocks, SPY and crude oil futures. FRED supplies the two-year Treasury yield DGS2. The seeded ticker list follows the designs; the demo portfolio and human-authored sector mapping still require review. No synthetic prices, moves or sensitivities are shipped to the UI.

Direct links require reviewed company tags. Measured links require shared reviewed tags and a historical regression with enough aligned observations and a 95% interval excluding zero. Unmeasured shared-topic links expose no sensitivity. Every screen uses one vocabulary, set by the Overview: Direct (red), Related (blue, a measured link) and Topic (dashed, unmeasured). The event page also restates each measured coefficient as a sentence, using only the stored coefficient, its 95% range and the number of trading days. Regressions use returns or daily yield changes with a SPY control; the SPY driver uses five-year beta. Driver coefficients do not become event-outcome dollar forecasts.

Holdings can be listed securities, cash or savings, Treasuries or CDs, bonds, or property. Securities are measured against five drivers: the S&P 500, crude oil, the 2-year and 10-year Treasury yields, and the weekly 30-year mortgage rate. Every measurement stores a typical effect, so each holding's drivers are ranked and the screens say which matters most: the 10-year yield for a long bond fund, crude oil ahead of the stock market for an oil producer. Holdings without a ticker are never regressed. Where their own terms give an exact figure it is shown as Calculated (interest per point of rate, a bond's price change from modified duration, interest on an adjustable mortgage); otherwise they are topic links with no number, and property links only to markets that name its state or the whole country.

Trust returns spread, activity, depth and category calibration components. Category history below 30 markets is excluded and the other components are rescaled. Missing quote data leaves trust unavailable. Track records use midpoint candles ending at or within one minute before the timestamp 24 hours before close; absent quotes are skipped. Backfill retains failed pages for explicit manual resumption. The 70% headline has its own 65–75% bucket.

Move components reconcile mathematically, with unavailable values when aligned closing prices or beta history are missing. The Earnings screen follows the design: upcoming reports for holdings whose next earnings call Kalshi has dated, then one company's preview. It shows only markets about reported results. Kalshi lists no company revenue brackets, so the lead card reads an operating metric from its ladder of "above X" markets and states where even odds fall, using the two markets either side of 50%. Earnings ladders normalize only a complete quoted, mutually exclusive range ladder: its buckets plus any open-ended end caps. Past report dates come from SEC EDGAR 8-K filings carrying Item 2.02; each move runs from the last close before the filing date to the first close after it. Report dates load only when SEC_USER_AGENT is set. The calendar places each event on Kalshi's own event date (occurrence time, strike date or expected expiration) and names the field used, falling back to the market close.

The Forecasts page uses a vertical table with one row per event family across dates, times and targets. S&P price/range/threshold/up-down formats share one row; other repeated series/metric formats are also consolidated. Snowflake evaluates the full contract set together for one best-effort driver forecast and uncalibrated self-rated confidence. Expand a row to see its estimated stock effects and every original contract's odds and scenario. The backend computes dollar effects from reliable sensitivities; event odds remain separate Kalshi bid–ask midpoints and overlapping scenarios are never summed. Verified S&P/Treasury scenarios and manual assumptions remain available. Assumptions are cached by holdings/models/contract identity, so quote changes do not regenerate them. Stocks without reliable measurements get no dollar estimate. Expand Additional forecast tools for manual scenarios and the next-session baseline. See FORECASTS.md for methods and testing steps.

Page data reads share a private browser memory cache for five minutes. Returning to a loaded page shows its saved response immediately; identical concurrent requests share one fetch. Filters, tickers and pagination have separate entries, with a limit of 200 responses. Reload requests fresh data while keeping the previous result visible. Portfolio/account writes clear the cache, and account changes prevent older requests from restoring it. Authentication checks stay live, health reads expire after 30 seconds, and pending AI responses and request errors are not cached. The cache lasts until expiry or a full browser refresh; source asOf timestamps remain unchanged. Snowflake's separate persistent holdings-based cache still controls whether AI runs again.

Earnings also has a private backend cache shared by its company list and detail endpoints, so F5 can reuse data after browser memory is cleared. It checks current manual and brokerage holdings before each read and caches the resulting snapshot for five minutes, with at most 32 portfolio snapshots. The page's Reload button rebuilds that snapshot once; switching companies then uses normal cached reads. Cache expiry or a backend restart requires a fresh build. In the Network panel, the earnings responses' Server-Timing header shows earnings_cache_hit and, for saved company details, earnings_detail_cache_hit; sql_count reports database work. Authenticated requests still validate the session before reading cached data.

Calendar likewise reuses a private backend exposure snapshot after F5. All date windows and All future dates (/exposure) share the snapshot, bounded to 32 portfolio snapshots and five minutes each. Reads check current manual and brokerage holding contents; changes rebuild the snapshot, as does crossing the New York date boundary. Date windows are calculated on each read. The Reload button bypasses this cache; a normal browser refresh reuses it. Source timestamps are preserved, failures are not cached or retried, and authentication stays live. Inspect exposure_cache_hit, exposure_build, holdings and sql_count in Calendar or exposure responses' Server-Timing header. The first read after expiry or a backend restart still rebuilds the data.

Overview uses that same exposure/calendar snapshot and also caches saved briefing JSON across F5. Briefing metadata has a separate private five-minute cache bounded to 32 snapshots, keyed by owner, current manual/imported holding contents, New York date and voice configuration. Only metadata is retained in memory; audio stays in its durable holdings-based cache. Missing briefings and errors are not retained, so scheduled generation becomes visible on the next read. The page starts its three reads together; Reload rebuilds exposure once, reads upcoming events from that new snapshot, and refreshes briefing metadata while keeping loaded cards visible. Reload briefing remains the explicit action to prepare a missing briefing; neither F5 nor page Reload regenerates saved audio. Look for exposure_cache_hit on exposure/calendar and briefing_cache_hit on briefing, with sql_count showing only the current holdings check on warm guest reads. Authentication is checked separately on every signed-in request.

Moves also caches backend responses across F5 for five minutes, retaining at most 32 snapshots. Each owner, holdings revision, requested date and day/week/month/quarter range has a separate result; the default latest-session request stays distinct from an explicit date. Every read checks current manual and imported holdings. When another day becomes eligible for completed closing prices (5 p.m. New York), the cache key changes so latest-session selection can advance. Reload bypasses the cache to pick up newly loaded prices, measurements, odds and settlements; expiry also rebuilds. Responses preserve their original source dates and asOf, and unavailable numbers stay unavailable. Authentication remains live, simultaneous ordinary reads share a build, and failures are neither cached nor automatically retried. Check moves_cache_hit, moves_build and sql_count in the response's Server-Timing header. The background exposure read for Moves categories already uses Calendar's backend cache.

Forecasts shares a private backend snapshot across its rankings, result details, additional tools and completed AI status reads, so F5 reuses their data. Each read checks current manual and imported holdings; owner, holdings contents, completed-price cutoff and Snowflake account/model configuration identify the snapshot. Snapshots last up to five minutes, with limits of 32 portfolio snapshots and 128 lazy reads each. They expire earlier when a cached contract closes or a quoted probability reaches the existing 30-minute quote-age limit. Rankings, results and assessments reuse short price history and measurements; the longer baseline history loads only when its tools are opened. Pending AI results are not retained, so status checks can see completion without rebuilding rankings/models. Ordinary Reload refreshes the page snapshot and preserves Snowflake's persistent estimates and stopped failure records; only Retry estimate clears a stopped failure. It also clears other browser Forecasts snapshots so expanded results use the refreshed data. Original source timestamps and validation rules remain intact. Look for forecasts_cache_hit, forecasts_build, holdings and sql_count in the Server-Timing header. First reads after restart, expiry or holdings changes still build data, and a first AI assessment may still be pending.

To check navigation caching, open Overview, Calendar and Moves once, then switch back with the browser Network panel open: repeat reads should produce no new API request within five minutes. Reload should send a fresh request, and saving holdings should invalidate earlier page results. Visiting Connected brokerages reads saved accounts; Sync accounts and returning from the hosted connection portal import SnapTrade's provider snapshot.

Sponsor tools

Failed provider requests and background tasks are not retried automatically. Successful data schedules continue normally; stopped work requires an explicit action. Docker services also have automatic restarts disabled. Forecasts reuse saved estimates and expose Retry estimate for a single manual attempt after a failure. An unsupported number in AI prose hides the explanation while preserving independently validated estimates. See DEPLOY.md for operational recovery.

Tiger Data: Postgres via pg stores markets, holdings, tags and measured links; TimescaleDB hypertables store five-minute odds and daily prices. Screens read our database through the backend. Docker's local TimescaleDB provides the same schema for transfer and development.

Snowflake Cortex AI: REST calls assign only fixed-list tags and analyze a supplied 10-K risk-factor section once per ticker. Configure SNOWFLAKE_ACCOUNT_URL, SNOWFLAKE_PAT and SNOWFLAKE_CORTEX_MODEL; no additional SDK is needed. New series tags have source = 'snowflake' and remain unreviewed until a person approves them. The migration preserves historical Gemini/manual provenance and approvals. The risk-factors job accepts a symbol, local filing-text path and HTTPS filing URL; automatic SEC filing discovery is not implemented.

Event context: Optional Cortex Search retrieves reporting from your own index with TITLE, URL and TEXT columns. This replaces Google Search grounding; automatic open-web search is not implemented. Summaries cite only retrieved HTTPS sources and may use only numbers in the supplied market data. Missing configuration, sources or supported numbers means no new summary. See DEPLOY.md for setup. Application storage remains in Tiger Data/PostgreSQL, independently of Snowflake.

ElevenLabs: The official SDK converts a database-backed template briefing into MP3, cached per account or guest portfolio and holdings snapshot. Playback appears on the overview when audio is available. Scheduled jobs create it from 8 a.m. New York time, and Reload briefing prepares a missing snapshot on request. Unchanged holdings reuse the saved audio even when the date or Kalshi quotes change. Templates go through the same number guard. Optional AI wording smoothing is omitted to preserve exact template facts.

Status

Docker setup, Kalshi polling, Yahoo price loading, Snowflake tagging and one Cortex Search query have run against live services. Series tags were bulk-approved on October 9, 2026 without individual review; 103 plainly incorrect mappings were withdrawn on October 10 and several debatable groups remain approved (see REVIEW-TAGS.md). The human sector mapping is still empty, so links come only from company tags and the four measured drivers. SEC report dates need SEC_USER_AGENT. See VALIDATION.md for current checks and the historical phase log; production readiness is not certified.

NUMBERS.md maps displayed numbers to sources. SUBMISSION.md is a draft for human review; it avoids unverified completion claims.

Brokerage accounts

Read-only SnapTrade linking is available under Brokerages for signed-in users, with separate sandbox and live modes. Manual entry and CSV imports remain available. Configure commercial test keys and follow SNAPTRADE.md for sandbox setup and the test checklist. Docker passes the connector settings to the backend.

Thanks!