Glossary
Terms as this codebase uses them. Lessons stick to these definitions.
| Term | Meaning here |
|---|---|
| Edge function | One Deno program under src/supabase/functions/<name>/index.ts, deployed to Supabase's edge runtime and reachable at /functions/v1/<name>/…. One function hosts many endpoints via its own router. |
| Endpoint | The last path segment a function's router switches on, e.g. details in /functions/v1/stocks/details. |
| Handler | A file in handlers/ exporting handle…Request(req); owns one endpoint's validation, DB access and response. |
| Kong | Supabase's API gateway in front of every service. Checks the apikey header, forwards to the edge runtime, PostgREST or GoTrue. Locally it strips non-JWT bearer tokens. |
| PostgREST | Auto-generated REST API over the exposed schemas ([api].schemas in config.toml). The mobile app uses it directly for simple reads; edge functions exist for anything needing logic or secrets. |
| GoTrue | Supabase Auth. Issues the JWTs; publishes the JWKS at /auth/v1/.well-known/jwks.json. |
| anon key | Public key shipped in clients. Requests with it run as role anon; RLS decides what they see. |
| service_role key | Secret key. Bypasses RLS. Only cron, triggers and edge functions hold it. validateServiceRole checks a caller presented it. |
| RLS | Row Level Security: Postgres policies that filter rows per role. The reason the anon key is safe to ship. |
| Vault | vault.decrypted_secrets: encrypted key/value store inside Postgres. Holds supabase_url and supabase_service_role_key so SQL can call edge functions. |
| pg_cron | Postgres extension that runs SQL on a schedule. Every scheduled job in this repo is a migration calling cron.schedule(name, crontab, sql). |
| pg_net | Postgres extension for async HTTP. net.http_post queues a request and returns an id; the response lands in net._http_response later. |
private.post_to_edge_function | The one sanctioned way for SQL to call an edge function. Adds the vault URL, service key and the mandatory Origin header. |
| Migration | Timestamped SQL file in src/supabase/migrations/. Applied in order by db reset locally and by the GitHub integration in prod. |
| pgTAP | SQL test framework. Files in src/supabase/tests/database/*.test.sql, run with npx supabase test db. |
| Import map | The imports block of a deno.json that maps bare names to URLs. The functions-level deno.json here only sets JSX options; imports use full specifiers. |
jsr: / npm: / https: | Deno import specifier schemes: JSR registry, npm registry, raw URL (e.g. esm.sh). All three appear in this repo. |
| Massive | Market-data vendor (formerly Polygon.io). Sole price ingestion source, REST polling only. |
| Tier | Either retention tier of price bars (intraday/hourly/daily partitions) or market-cap tier (mega/large/mid/small) driving refresh cadence. Context tells which. |
| Publishable / secret key | The modern sb_publishable_* and sb_secret_* keys. The stocks public endpoints accept only the publishable key; the legacy anon JWT is rejected there. Locally, validateServiceRole still matches the legacy service_role JWT, not sb_secret_*. |
| Hermetic test | A Deno test that imports a core function with injected dependencies and needs no running stack. Selected for CI by not mentioning localhost:54321 or _testUtils. |
| Accession number | EDGAR's unique id for one filing. The upsert key for Stock_SEC_Filings; the live poller and the Massive sweep meet on it. |
| CIK | SEC Central Index Key, one per filer. SEC_CIK_Tickers maps it to our tickers; one CIK can own several share classes. |
| Data source (provenance) | data_source column on price bars: massive or derived. Decides which writer may overwrite which in the hourly tier. |
| HMAC webhook | Inbound vendor call signed with a shared secret over the raw body plus id and timestamp headers. Verified constant-time before anything is parsed (Quartr, SnapTrade). |
| Ledger (backfill) | A table recording per-item outcome of a one-time history load, e.g. SEC_Filings_Backfill, Stock_Financials_Backfill. The cron asks it what is still pending. |
| Reconcile (date sweep) | Nightly re-fetch of the last few days from a second source, inserted with on conflict do nothing, so a missed live event self-heals. |
| TTM | Trailing twelve months. Computed, never filed: flows sum four quarters, instants take the latest value. Guarded by quarters_in_window and window_span_days. |
| Watermark | The point a poller reached last run (SEC_Feed_Poll_State). Advanced only after a successful write, so a failed run re-reads. |
| Snapshot | Massive's whole-US-market quote endpoint, one call. Feeds refresh and ingest-minute-bars; the diff source for retry-blocked and prune-stale. |
| Grouped daily | Massive's one-call-per-date, all-tickers daily bar endpoint. Daily only; the reason the daily tier is cheap and hourly is not. |
| Universe | The set of tracked tickers: Companies from Quartr, narrowed to rows present in Stock_Current_Quotes. Massive data outside it is discarded. |
| Blocked company | Companies.blocked = true after ten consecutive refresh failures. Excluded from every job until retry-blocked finds it in a snapshot again. |
| HMAC webhook verification | Vendor signs the request body with a shared secret; we recompute and compare in constant time. Used by snaptrade-webhook and quartr-webhook-handling. Replay protection is separate (dedup on the vendor's event id). |
| Keyset pagination | Paging by "rows after (event_time, id)" instead of OFFSET, so pages stay stable while new rows land at the head. Used by get_feed. |
SECURITY DEFINER / security_invoker | Whether a SQL function or view runs with its owner's privileges (bypassing RLS) or the caller's. Definer functions here are always service-role only and revoked from anon/authenticated. |
EdgeRuntime.waitUntil | Edge-runtime API that lets a handler return a response while a promise keeps running. Used by the SnapTrade webhook to ack in time and refresh asynchronously. |