Architecture

How CreatorIQ fits together, from scrape to screen.

Big picture

ScrapeCreators API ──► Pipeline (src/lib/pipeline.ts)
                            │  fetch → normalize → dedupe → score
                            ▼
                     Supabase Postgres ──► Landing (public, ISR 1h)
                            │              Platform (per-user, RLS)
                            ▼
                    Credits engine ◄── user actions (analyze, generate)

Route groups

• (landing) — public marketing pages: /, /pricing. Statically prerendered with 1-hour ISR, fed by getLandingData() via the service role client.
• (auth) — /login and /signup, plus server actions for email/password and Google OAuth.
• (platform) — the app shell behind src/proxy.ts: dashboard, discover, analyze, generate, track, folders, settings. Reads use the session client (RLS scoped to the user).
• (docs) — this documentation site.

Clients, by purpose

• src/lib/supabase/client.ts — browser client.
• src/lib/supabase/server.ts — session client for server components/actions. Respects RLS as the signed-in user.
• src/lib/supabase/admin.ts — service role client. Used only server-side for writes that bypass RLS (pipeline upserts, credit mutations, landing reads).

Session & protection

Next.js 16 renamed middleware to proxy.ts. It refreshes the Supabase session cookie on every request, redirects unauthenticated /platform traffic to /login, and bounces signed-in users away from the auth pages.

Data freshness

• GET /api/cron/scrape runs daily at 06:00 via Vercel Cron, guarded by CRON_SECRET. It re-scrapes trending + every niche found in the DB.
• Landing pages revalidate hourly (ISR) so public data stays fresh.
• Platform pages are dynamic and always read live.