First Principles

The definitive Elon Musk encyclopedia. Every company, every milestone, every tweet, every prediction — graded against reality.

A fan-built encyclopedia covering Elon Musk's lifetime, his ten ventures (Tesla, SpaceX, Neuralink, xAI, X, The Boring Company, OpenAI history, Zip2, X.com/PayPal, SolarCity), and the public record of his predictions and tweets. Powered by xAI's Grok for grounded "Ask Elon" answers cited to real public statements.

Not endorsed by Elon Musk or any of his companies.

Stack

• Framework: Next.js 16 (App Router, Turbopack) + React 19
• Language: TypeScript (strict)
• Styling: Tailwind v4 + Newsreader serif + Geist Sans
• AI: xAI Grok (chat completions + embeddings) via plain fetch (no SDK dependency)
• Database: Supabase (Postgres + Auth + RLS + pgvector)
• Payments: Stripe (Pro tier — $9/mo)
• Analytics: PostHog + Vercel Analytics + Speed Insights

Project structure

src/
├── app/                          # Next.js App Router
│   ├── page.tsx                  # Landing — hero, status strip, encyclopedia tiles
│   ├── companies/                # /companies + /companies/[id]
│   ├── vehicles/                 # /vehicles + /vehicles/[id]
│   ├── timeline/                 # /timeline (filterable lifetime stream)
│   ├── tweets/                   # /tweets (search) + /tweets/[id] (annotation)
│   ├── quotes/                   # /quotes (sourced quote library)
│   ├── predictions/              # /predictions (graded scoreboard)
│   ├── ask/                      # /ask (Grok-grounded chat)
│   ├── on-this-day/              # /on-this-day (calendar-matched events)
│   ├── scrubber/                 # /scrubber (tweet ↔ TSLA stock split-pane)
│   ├── pricing/                  # /pricing (Free + Pro tiers)
│   └── api/
│       ├── ask/                  # POST /api/ask — SSE-streamed Grok responses
│       └── ...                   # checkout, webhook, billing, etc.
├── components/
│   ├── ai/                       # legacy Claude panel (kept for layout context)
│   ├── ask/AskElonChat.tsx       # NEW — Grok chat UI
│   ├── countdown/                # LaunchCountdown live ticker
│   ├── entity/                   # CompanyCard, VehicleCard, QuoteCard, PredictionRow, MilestoneList
│   ├── onthisday/                # OnThisDayCard
│   └── tweets/                   # TweetSearchBar
├── data/                         # TypeScript-as-CMS — version-controlled facts
│   ├── companies.ts              # 10 companies, full milestones
│   ├── timeline.ts               # 50+ life events (Phase 7 fills to 300+)
│   ├── vehicles.ts               # 14 vehicles/rockets/robots
│   ├── quotes.ts                 # Curated quotes with sources
│   ├── predictions.ts            # Public predictions with reality grades
│   └── tweets-curated.ts         # Hand-annotated tweet "greatest hits"
├── lib/
│   ├── site-config.ts            # SITE — palette, brand, SEO
│   ├── xai/                      # NEW — Grok client, models, streaming, RAG
│   │   ├── client.ts
│   │   ├── models.ts
│   │   ├── stream.ts
│   │   ├── elon-prompts.ts       # SYSTEM_GROUNDED, SYSTEM_NEUTRAL, SYSTEM_DEEP_RESEARCH
│   │   └── grounded-rag.ts       # In-memory retriever over quotes + tweets + milestones
│   ├── launches.ts               # Static launch + delivery counts (live API in Phase 7)
│   └── supabase/                 # Supabase client + fp-tweets DB wrapper
├── types/
│   └── fp.ts                     # Company, LifeEvent, Vehicle, Quote, Prediction, CuratedTweet
├── scripts/
│   └── ingest-tweets.ts          # Kaggle CSV → Supabase fp_tweets
└── supabase/
    └── migrations/
        └── 20260501000000_fp_tweets.sql   # fp_tweets + fp_tweet_curated + hybrid-search RPC

Local development

Requires bun (brew install oven-sh/bun/bun).

bun install
cp .env.example .env.local        # then fill in keys
bun dev                           # http://localhost:3000

The site renders fully without any env vars set — Ask Elon falls back to a graceful demo mode that streams the retrieved citations themselves. The countdown widgets, on-this-day, scrubber, and all encyclopedia routes work entirely from the local TypeScript dataset.

Going live (in priority order)

1. xAI Grok (the headline feature)

Set XAI_API_KEY=xai-... in .env.local. The /ask endpoint switches automatically from demo mode to live streaming Grok responses on the next request. Buy credits at console.x.ai.

2. Bulk tweet archive (Phase 7)

# In the Supabase SQL editor, run:
#   supabase/migrations/20260501000000_fp_tweets.sql

# Download the Kaggle CSV (free):
#   https://www.kaggle.com/datasets/dadalyndell/elon-musk-tweets-2010-to-2025-march

# Bulk-load (with embeddings):
SUPABASE_URL=... SUPABASE_SERVICE_ROLE_KEY=... XAI_API_KEY=... \
  bun scripts/ingest-tweets.ts --csv ./tmp/elon.csv --embeddings --batch 200

After ingestion, /tweets fully searches the 100K+ corpus via Postgres FTS + pgvector hybrid scoring (fp_tweets_hybrid_search RPC).

3. Stripe Pro

1. Create First Principles Pro — Monthly ($9/mo) in your Stripe dashboard.
2. Copy the price id to STRIPE_PRICE_MONTHLY.
3. The existing /api/checkout route already wires it.

4. Live launch + stock data (Phase 7)

• src/lib/launches.ts — replace static array with a SpaceX schedule API or scraped feed
• src/app/scrubber/page.tsx — replace mocked TSLA series with Yahoo Finance API

House style

• Cream + navy editorial: never glassmorphism, never neon. Britannica × tech magazine.
• Typography: Newsreader serif for headlines, Geist Sans for UI, mono for dates.
• Colors: only via SITE.* palette tokens — no hardcoded hex outside site-config.ts.
• Container: max-w-5xl mx-auto px-6 py-16 (or max-w-3xl for chat).
• No documentation comments: code self-documents through naming. Comments only where the why is non-obvious.
• Fan-project framing: every major page mentions the disclaimer; nothing implies endorsement.

Phases shipped

Legal posture

• "First Principles is a fan-built encyclopedia. Not endorsed by Elon Musk, Tesla, SpaceX, X, xAI, Neuralink, The Boring Company, or any related entity."
• Ask Elon answers are grounded in publicly-available quotes and tweets; no voice synthesis, no AI-generated photorealistic Elon imagery.
• Tweet archive is treated as public-record curation; full attribution to X.
• Stripe Pro gates features (unlimited messages, deep research, exports), not the persona itself.