Earnlytics

AI-driven US tech company earnings analysis platform with Chinese summaries.

Production: https://earnlytics-ebon.vercel.app
Last Updated: 2026-02-27

🎯 Current Progress

Phase	Status	Completion	Key Achievements
Plan 1: MVP	✅ Complete	100%	10 pages, Vercel deployed
Plan 2: AI Automation	✅ Complete	100%	DeepSeek AI, 23 earnings analyzed, GitHub Actions
Plan 3: Scale	✅ Complete	100%	30 companies, 109 earnings, 100% AI coverage, email subscription
RAG AI Assistant	✅ Complete	100%	Vector search, multi-turn dialogue, dynamic suggestions
Portfolio Optimization	✅ Complete	100%	Real-time prices, glassmorphism design, auto-refresh

Database Status

• Companies: 30 (Tier 1/2/3) - scripts support tier2/tier3 insertion
• Earnings: 109 records - scripts for backfilling and seeding
• AI Analyses: 100% coverage - analyze-batch.ts script available
• Document Embeddings: Vector data populated - 1024-dim Cohere embeddings
• Chat Conversations: Ready for AI assistant - multi-turn dialogue support
• Subscribers: Ready (API + UI complete) - send-digests.ts script exists

📂 Project Structure

earnlytics/
├── AGENTS.md                 # AI assistant knowledge base (updated 2026-02-11)
├── README.md                 # This file
├── .gitignore                # Root gitignore (minimal)
├── doc/                      # Chinese documentation
│   ├── 计划/                 # Execution plans (Plan 1-5)
│   ├── 策略/                 # Strategy docs
│   ├── 技术/                 # Technical docs
│   └── 项目状态报告-20260210.md # Current status report
├── earnlytics-web/           # Next.js 16 frontend ⬅️ Main codebase
│   ├── src/
│   │   ├── app/             # App Router pages
│   │   │   ├── earnings/[symbol]/ # Dynamic route for earnings
│   │   │   ├── companies/   # Company list page
│   │   │   ├── calendar/    # Earnings calendar
│   │   │   ├── assistant/   # AI assistant (RAG chat) ✨
│   │   │   ├── portfolio/   # Portfolio management
│   │   │   ├── privacy/     # Privacy policy
│   │   │   ├── terms/       # Terms of service
│   │   │   └── api/         # API routes
│   │   ├── components/
│   │   │   ├── ui/          # shadcn/ui primitives
│   │   │   ├── icons/       # SVG icon library (replaced all emoji)
│   │   │   └── layout/      # Header, Footer
│   │   └── lib/             # Utilities (ai.ts, supabase.ts)
│   ├── scripts/             # 24 data scripts
│   │   ├── fetch-earnings.ts
│   │   ├── analyze-batch.ts
│   │   ├── generate-embeddings.ts  # Vector generation ✨
│   │   ├── backfill-tier2.ts
│   │   └── send-digests.ts
│   └── supabase/migrations/ # Database schema
└── pencil-earnlytics.pen    # Design file (13 pages)

🚀 Quick Start

# Frontend development
cd earnlytics-web && npm run dev          # Start dev server (localhost:3000)

# Data Operations
npm run fetch:earnings                    # Fetch latest earnings from FMP
npm run analyze:batch                     # Generate AI analysis (batch of 5)
npm run generate:embeddings               # Generate vector embeddings for RAG

# Build & Deploy
npm run build                             # Production build
npm run lint                              # Lint check

🛠 Tech Stack

Layer	Technology	Version
Frontend	Next.js	16.1.6
Frontend	React	19.2.3
Frontend	TypeScript	5
Styling	Tailwind CSS	4
UI Components	shadcn/ui	Latest
Icons	Lucide React + Custom SVG	Latest
Path alias	@/* → ./src/*	-

Backend & Infrastructure

• Hosting: Vercel Serverless
• Database: Supabase PostgreSQL + pgvector
• AI Service: DeepSeek API (¥0.002/1K tokens)
• Embedding: Cohere Embedding API (1024-dim, free tier)
• Data Source: Financial Modeling Prep (FMP) API + SEC EDGAR
• Automation: GitHub Actions (every 4 hours)

⚡ Performance Updates (2026-02-27)

• /home now uses server-side prefetch + cache (revalidate=300) to reduce client waterfall.
• Added dynamic imports and viewport-triggered rendering for below-the-fold sections.
• HeroStats counters start only when entering viewport.
• MarketTicker animation pauses when tab hidden/offscreen to reduce CPU usage.
• EarningsCard optimized with memo + memoized sparkline generation.
• /api/market-ticker now supports in-memory short cache + ETag / 304.
• Added Web Vitals collection pipeline:
  • client reporter: src/components/performance/WebVitalsReporter.tsx
  • API endpoint: src/app/api/web-vitals/route.ts (POST ingest + GET summary)
• Added image optimization helper src/lib/image-optimization.ts to avoid unnecessary unoptimized.

🗂 Architecture Docs Note

• Legacy root doc earnlytics-web-architecture.md has been removed.
• Use for_AGENTS/AGENTS.md and for_AGENTS/规范文档/* as the canonical architecture and implementation references.

📋 Development Plans (Based on Actual Code)

Phase	Timeline	Goal	Status	Evidence in Code
Plan 1: MVP	Week 1-2	10 pages, 10 companies	✅ Complete	10+ pages in app/, shadcn/ui components
Plan 2: AI Automation	Week 3-4	AI analysis, automation	✅ Complete	ai.ts, analyze-batch.ts, GitHub Actions
Plan 3: Scale	Month 2	30 companies, 109 earnings	✅ Complete	tier2/tier3 scripts, backfill scripts
RAG AI Assistant	Week 5-6	Vector search, AI chat	✅ Complete	/assistant page, Cohere embeddings, RAG pipeline
Portfolio Optimization	Week 6-7	Real-time prices, UI upgrade	✅ Complete	15-min refresh, glassmorphism design
Plan 4: Growth	Month 3	SEO, traffic growth	📋 Planned	-
Plan 5: Commercialization	Month 4-6	Monetization	📋 Planned	-

💰 Cost Analysis (Based on Actual Implementation)

Phase	Monthly Cost	Main Expense	Actual (Based on Code)
MVP	¥0	Free tier	✅ ¥0 (Vercel, Supabase free)
Automation	¥1-2	DeepSeek API	✅ ¥0.2-1 (batch processing)
Scale	¥10-20	Potential DB upgrade	🚀 ¥0.2-1 (still on free tiers)

Current Monthly Cost: ~¥0.2-1 (extremely low, all free tiers)

🔑 Key Architecture Decisions (Visible in Code)

1. Dynamic Routing for Earnings

Changed from: /earnings?symbol=aapl (query params)
Changed to: /earnings/aapl (dynamic route)
Evidence: src/app/earnings/[symbol]/page.tsx exists
Reason: Next.js 15+ params are Promises, simpler to use dynamic segments

2. SVG Icons Instead of Emoji

All emoji replaced with SVG components
Evidence: src/components/icons/index.tsx exists with custom icons
Benefits: Consistent styling, better performance, no platform differences

3. AI Analysis Batch Processing

Approach: Process 5 earnings at a time
Evidence: scripts/analyze-batch.ts with batch logic
Reason: Control API costs, manageable execution time

📚 Documentation (Chinese)

Path	Content	Status
doc/计划/	Execution plans (Plan 1-5)	✅ Complete
doc/策略/	Strategy documents	✅ Complete
doc/技术/	Technical documentation	✅ Complete
doc/项目状态报告-20260210.md	Current status report	✅ Updated

⚠️ Anti-Patterns (THIS PROJECT)

NEVER Do These

• ❌ Run create-next-app in root directory (creates duplicate config)
• ❌ Add API keys to git (use environment variables)
• ❌ Use as any, @ts-ignore, @ts-expect-error
• ❌ Add .gitignore rules that overlap with earnlytics-web/.gitignore
• ❌ Commit .env.local or files containing secrets

ALWAYS Do These

• ✅ Use SVG icons from src/components/icons/
• ✅ Follow shadcn/ui patterns for components
• ✅ Update progress documents when completing tasks
• ✅ Use dynamic routes for parameterized pages
• ✅ Test build before committing

🐛 Known Issues & Solutions (From Code Analysis)

Issue	Solution	Evidence
useSearchParams returns null	Use dynamic route [symbol] instead	earnings/[symbol]/page.tsx
params is Promise in Next.js 15	Use React.use() to unwrap	earnings/[symbol]/page.tsx
Environment variables in scripts	Use dotenv to load .env.local	scripts/*.ts with config()
API keys leaked to git	1) Delete file, 2) Rotate keys, 3) Add to .gitignore	Already fixed

📝 Notes

• Project uses DOVE VPN proxy (HTTP 7897) for GitHub access
• Doc folder uses Chinese naming conventions (计划, 技术, ���略)
• Root .gitignore is minimal; full rules in earnlytics-web/.gitignore
• Monthly AI cost: ~¥0.2-1 (extremely low cost, batch processing)
• All API keys must be rotated if accidentally committed
• Dynamic routes use [symbol] format, accessed via React.use(params) in Next.js 15
• 23 data scripts available for various operations

🎉 Key Achievements

1. ✅ Complete Frontend: 10+ pages with dynamic routing
2. ✅ AI Integration: DeepSeek API with batch processing
3. ✅ RAG AI Assistant: Vector search with Cohere embeddings, multi-turn dialogue
4. ✅ Data Pipeline: 24 scripts for data fetching, analysis, and embeddings
5. ✅ Database Schema: Supabase migrations with pgvector support
6. ✅ UI System: shadcn/ui + custom SVG icons + glassmorphism design
7. ✅ Automation: GitHub Actions for scheduled tasks
8. ✅ Scalability: Support for 30 companies across 3 tiers
9. ✅ Real-time Portfolio: 15-min price refresh with auto-update

---

Production: https://earnlytics-ebon.vercel.app
GitHub: https://github.com/Timcai06/Earnlytics
Branch: main
Last Updated: 2026-02-27