System map
One page. Where things live and which way traffic flows.
Layers (outside in)
| Layer | What it is | In this repo |
|---|---|---|
| Clients | iOS/RN app, web, crawlers, Slack, vendor webhooks | not here (see config.toml redirect URLs) |
| Kong gateway | Routes /functions/v1, /rest/v1, /auth/v1; checks apikey | invisible; behaviour noted in _shared/jwt/default.ts |
| Edge runtime | Deno, one isolate per function, Deno.serve entry | src/supabase/functions/*/index.ts |
| PostgREST | REST over exposed schemas, RLS enforced | [api].schemas in config.toml |
| Postgres | Tables, RLS, functions, pg_cron, pg_net, vault | src/supabase/migrations/ (239 files) |
| External APIs | Massive, Quartr, SnapTrade, Resend, Google, Slack, OpenAI, SEC EDGAR | called from handlers; keys in function env |
Three traffic directions
AInbound user request. Client → Kong → edge function router → handler → supabase-js (anon or user JWT) → Postgres under RLS → JSON back. Gate order inside the function: OPTIONS, CORS origin, then route. stocks/index.ts
BScheduled internal call. pg_cron → SQL job →
private.post_to_edge_function(path, body) → pg_net → Kong → edge function with service_role bearer + Origin: https://api.wallstreetbets.com → handler calls vendor API → writes with service client (RLS bypassed). migrations/*schedule*.sqlCInbound vendor webhook / DB trigger. Quartr, SnapTrade sign payloads with HMAC; handler verifies, writes. DB triggers (waitlist welcome email, Slack alerts) use direction B's transport. quartr-webhook-handling/, notify-slack/
Function inventory
| Function | Auth tier | Role |
|---|---|---|
stocks | public + service routes | market data API and all ingestion/refresh jobs (30 handlers) |
earnings, earnings-cache | public / user | Quartr-derived earnings data |
quartr-webhook-handling, snaptrade-webhook | HMAC | vendor push ingestion |
brokerage, account, feed, submit-feedback | user JWT | per-user features |
news-admin, news-api, news-public | API key / public | news CMS surfaces |
send-email, notify-slack, fx, clickup-sprint-guard, proxy | service / hook | internal utilities |
Shared primitives (_shared/)
| File | Use it for |
|---|---|
cors.ts | OPTIONS handling and the Origin allow-list. Missing Origin is a 403. |
jwt/default.ts | getUserId (user JWT via JWKS) and validateServiceRole (shared-secret check). |
utils.ts | createSuccessResponse / createErrorResponse, the canonical JSON envelope. |
validation.ts, canonicalTicker.ts | Input validation at the trust boundary. |
audit.ts | Writes to the audit schema. |
Tooling
Command (from src/) | Effect |
|---|---|
npx supabase start | Docker stack: Postgres 54322, API 54321, Studio 54323, Mailpit 54324. Applies migrations + seed.sql. |
npx supabase functions serve --no-verify-jwt | Runs every function in one edge runtime with hot reload. The flag skips Kong's JWT check locally. |
npx supabase db reset | Drop and replay all migrations. The local way to apply a new migration. |
npx supabase test db | Run pgTAP files. |
deno test --allow-all supabase/tests/functions/ | Edge function tests. CI runs only the standalone subset. |
never db push / functions deploy | Prod is deployed by the GitHub integration on merge to main. |