YouTube Analytics Dashboard with AI-Powered Insights
A comprehensive YouTube analytics platform that helps creators understand their channel performance, track video metrics, and gain AI-powered insights to improve their content strategy.
- � Channel Analytics - Track views, watch time, subscribers, and engagement
- 🎬 Video Performance - Per-video metrics with goal-based scoring
- 🤖 AI Insights - Content analysis powered by Google Gemini
- 🎯 Goal Profiles - Custom scoring based on your content goals
- � Trend Analysis - Track performance changes over time
- 🔍 Segment Analysis - Group videos by playlists or custom criteria
- 📧 Email Reports - Automated weekly/monthly digests
- Node.js 20+
- pnpm 10.x (
npm install -g pnpm) - Supabase account (free tier works)
- Google Cloud project with YouTube APIs enabled
git clone https://github.com/your-username/ytmetrix.git
cd ytmetrix
pnpm install-
Create a new project at supabase.com
-
Go to Project Settings → API and copy:
- Project URL
- Anon/Public key
- Service Role key (keep this secret!)
-
Run the database migrations:
# Apply all migrations to your Supabase project
# You can use the Supabase CLI or run migrations manually in the SQL editor
cd supabase/migrations
# Apply each migration file in order- Go to Google Cloud Console
- Create a new project (or use existing)
- Enable these APIs:
- YouTube Data API v3
- YouTube Analytics API
- Create OAuth 2.0 credentials:
- Go to APIs & Services → Credentials
- Click Create Credentials → OAuth client ID
- Application type: Web application
- Authorized redirect URIs:
http://localhost:3000/api/auth/google/callback(development)https://your-domain.com/api/auth/google/callback(production)
- Create an API Key:
- Click Create Credentials → API Key
- Restrict to YouTube Data API v3 (recommended)
cp .env.example .envEdit .env with your credentials:
# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
# Google OAuth
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
YOUTUBE_API_KEY=your-api-key
# App
NEXT_PUBLIC_APP_URL=http://localhost:3000
NODE_ENV=developmentpnpm dev:allytmetrix/
├── apps/
│ └── web/ # Next.js 16 application
│ └── src/
│ ├── app/ # App Router pages & API routes
│ ├── components/ # React components
│ └── lib/ # Utilities & API clients
├── supabase/
│ └── migrations/ # Database migrations (SQL)
├── scripts/ # Utility scripts
├── tests/ # Test suites
├── docs/ # Documentation
└── render.yaml # Render deployment config
| Layer | Technology |
|---|---|
| Frontend | Next.js 16, React 19, TypeScript, TailwindCSS 4 |
| UI | shadcn/ui, Radix UI, Lucide Icons, Recharts |
| Backend | Next.js API Routes |
| Database | Supabase PostgreSQL with Row Level Security |
| AI | Google Gemini, OpenAI (embeddings) |
| Auth | Supabase Auth + Google OAuth |
The database uses a multi-schema architecture:
public- User-facing tables with RLSb(bronze) - Raw data from YouTube APIss(silver) - Processed/aggregated datag(gold) - AI-generated insights
Key tables:
channels- Connected YouTube channelsvideos- Video metadatachannel_access- User-channel permissionsgoal_taxonomy- Goal profiles and scoring weights
Pull and run the pre-built image from GitHub Container Registry:
# Pull the latest image
docker pull ghcr.io/your-username/ytmetrix:latest
# Run with environment variables
docker run -p 3000:3000 \
-e NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co \
-e NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key \
-e SUPABASE_SERVICE_ROLE_KEY=your-service-role-key \
-e GOOGLE_CLIENT_ID=your-client-id \
-e GOOGLE_CLIENT_SECRET=your-client-secret \
-e YOUTUBE_API_KEY=your-api-key \
ghcr.io/your-username/ytmetrix:latestOr use Docker Compose:
# Copy environment file
cp .env.example .env
# Edit .env with your values
# Run with docker-compose
docker compose up -ddocker build \
--build-arg NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co \
--build-arg NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key \
-t ytmetrix:local .
docker run -p 3000:3000 ytmetrix:local- Fork this repository
- Connect to Render
- Create a new Blueprint from
render.yaml - Set environment variables in Render dashboard
- Deploy!
Works with any Next.js-compatible platform. Set the environment variables and deploy.
# Required
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
YOUTUBE_API_KEY=your-api-key
NEXT_PUBLIC_APP_URL=https://your-domain.com
# Optional - AI Features
GOOGLE_GEMINI_API_KEY=your-gemini-key
OPENAI_API_KEY=your-openai-key
# Optional - Email
RESEND_API_KEY=your-resend-key
# Optional - Cron Security
CRON_SECRET=random-secret-stringThe app includes scheduled jobs for data synchronization:
| Job | Schedule | Purpose |
|---|---|---|
| Channel Sync | Daily 1 AM UTC | Sync channel metrics |
| Video Sync | Daily 1:30 AM UTC | Sync video metrics |
| Watchlist Sync | Daily 2 AM UTC | Sync watched channels |
| Alert Processing | Daily 4 AM UTC | Process alert rules |
Configure CRON_SECRET to secure cron endpoints.
# Run all tests
pnpm test
# Run specific category
node tests/run-all-tests.mjs --category=apiSee tests/README.md for details.
| Document | Purpose |
|---|---|
| docs/DEPLOYMENT.md | Deployment guide |
| docs/PRODUCT_CONTEXT.md | Product overview |
| docs/architecture/ | System architecture |
| docs/EPICS.md | Feature development history |
- OAuth 2.0 for YouTube authentication
- Row Level Security (RLS) on all database tables
- Encrypted tokens stored in Supabase
- HTTPS only in production
- No write access to YouTube - read-only analytics
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit changes:
git commit -m 'Add amazing feature' - Push to branch:
git push origin feature/amazing-feature - Open a Pull Request
MIT License - see LICENSE for details.