Architecture Overview

This document provides a comprehensive overview of the YouTube Analyzer application architecture, data flow, and core design patterns.

System Architecture

The YouTube Analyzer follows a modern serverless architecture built on Next.js 14 with the App Router pattern. The system is designed for scalability, maintainability, and optimal user experience.

High-Level Architecture Diagram

┌─────────────┐    ┌──────────────┐    ┌─────────────┐
│   Client    │───▶│   Next.js    │───▶│ PostgreSQL  │
│  (Browser)  │    │    Server    │    │  Database   │
└─────────────┘    └──────────────┘    └─────────────┘
                           │
                           ▼
                   ┌──────────────┐
                   │ External APIs│
                   │ • YouTube    │
                   │ • OpenAI     │
                   │ • Stripe     │
                   │ • Resend     │
                   └──────────────┘

Data Access Patterns

The application uses two primary data access patterns:

1. API Routes: For client-side data access and actions
2. Direct Database Access: For server components to efficiently retrieve data

The direct database access pattern is used in server components to bypass the API layer when appropriate, improving performance and reliability. This is particularly useful for data fetching operations in server-rendered pages.

Example: Analysis results are fetched directly from the database in the results page server component using fetchAnalysis, which uses Prisma ORM directly instead of making an internal API call.

Core Design Patterns

1. Credit-Based Analysis System

The application implements a sophisticated credit system to prevent overselling and ensure fair usage:

• Credit Validation: Credits are checked before analysis starts
• Optimistic UI: User interface updates immediately for better UX
• Deferred Deduction: Credits are only deducted after successful completion
• Real-time Tracking: Credit usage is tracked and displayed in real-time

2. Streaming Analysis Results

Analysis results are delivered through a streaming approach:

• Progressive Updates: Results are delivered as they become available
• Real-time Feedback: Users receive live updates on analysis progress
• Error Handling: Graceful failure handling with partial results recovery

3. Multi-Tenant Architecture

The system supports multiple users with isolated data:

• User Isolation: Each user's data is completely isolated
• Role-Based Access: Different user roles with varying permissions
• Subscription Management: Individual subscription and billing per user

Data Flow Architecture

1. Manual Analysis Flow

User Input → Credit Check → YouTube API → OpenAI Processing → Database Storage → Email Notification

Detailed Steps:

1. User Submission (/dashboard/analysis)

   • User enters YouTube channel URL and analysis parameters
   • Client-side validation and optimistic UI updates
   • Credit reservation to prevent double-spending

2. API Processing (/api/youtube/process)

   • Channel URL parsing and validation
   • YouTube Data API calls for video/channel information
   • Transcript fetching for video content analysis

3. AI Analysis (OpenAI Integration)

   • Content analysis using GPT models
   • Sentiment analysis of comments (for premium tiers)
   • Structured report generation in HTML format

4. Data Persistence (Prisma/PostgreSQL)

   • Analysis results stored with relationships
   • Video metadata and performance metrics
   • User activity and credit tracking

5. Notification System (Resend/React Email)

   • Email notification upon completion
   • Shareable analysis results
   • Integration with dashboard updates

2. Auto-Analysis Flow

Cron Job → Channel Monitoring → New Video Detection → Trigger Analysis → User Notification

Detailed Steps:

1. Scheduled Monitoring (/api/cron/auto-analysis)

   • Vercel cron job runs periodically
   • Checks all active auto-analysis configurations
   • Identifies channels with new videos

2. Trigger Conditions (Business Logic)

   • Per-video triggers (immediate analysis)
   • Batch triggers (3 or 5 video thresholds)
   • Credit validation for automated analyses

3. Background Processing

   • Same analysis pipeline as manual triggers
   • Automatic credit deduction
   • Error handling and retry logic

4. Result Delivery

   • Email notifications with analysis results
   • Dashboard updates with new analysis cards
   • Integration with subscription management

Component Architecture

Frontend Architecture

The frontend follows a component-based architecture with clear separation of concerns:

1. Layout Components (components/layout/)

• Navigation: Top-level navigation and user menus
• Sidebars: Dashboard navigation and filters
• Footers: Site-wide footer with links and information

2. Feature Components (components/analysis/, components/dashboard/)

• Analysis Forms: User input forms for starting analyses
• Result Display: Charts, tables, and formatted analysis results
• History Management: Past analysis tracking and management

3. Shared Components (components/ui/, components/shared/)

• UI Primitives: Buttons, inputs, modals (shadcn/ui)
• Charts: Data visualization components (Recharts)
• Utility Components: Loading states, error boundaries

Backend Architecture

1. API Layer (app/api/)

├── analysis/          # Manual analysis endpoints
├── auto-analysis/     # Automated analysis management
├── cron/             # Scheduled task endpoints
├── dashboard/        # Dashboard data endpoints
├── user/             # User management
└── webhooks/         # External service webhooks

2. Service Layer (lib/)

├── db.ts             # Database connection and utilities
├── youtube.ts        # YouTube API integration
├── openai-streaming.ts # OpenAI API with streaming
├── email.ts          # Email service integration
├── stripe.ts         # Payment processing
└── subscription.ts   # Subscription management

3. Data Access Layer (prisma/)

• Schema Definition: Database models and relationships
• Migrations: Version-controlled database changes
• Query Optimization: Efficient data retrieval patterns

Security Architecture

1. Authentication & Authorization

• Session-Based Auth: Auth.js v5 with secure session management
• Role-Based Access: USER and ADMIN roles with different permissions
• API Protection: All sensitive endpoints require authentication

2. Data Protection

• Input Validation: Server-side validation for all user inputs
• SQL Injection Prevention: Prisma ORM with parameterized queries
• XSS Protection: React's built-in XSS protection and content sanitization

3. External API Security

• API Key Management: Secure environment variable handling
• Rate Limiting: Respect external API rate limits
• Error Handling: Graceful failure without exposing sensitive information

Performance Architecture

1. Database Optimization

• Indexing Strategy: Strategic database indexes for common queries
• Query Optimization: Efficient Prisma queries with proper includes
• Connection Pooling: PostgreSQL connection pooling for scalability

2. Caching Strategy

• Next.js Caching: Built-in caching for static and dynamic content
• Database Caching: Query result caching for frequently accessed data
• API Response Caching: Caching of YouTube API responses where appropriate

3. Streaming and Real-time Updates

• Streaming Responses: Real-time analysis result delivery
• Optimistic Updates: Immediate UI feedback for better UX
• Progressive Enhancement: Graceful degradation for slower connections

Scalability Considerations

1. Horizontal Scaling

• Stateless Design: All components are stateless for easy scaling
• Database Scaling: PostgreSQL with read replicas support
• CDN Integration: Static asset delivery through Vercel's CDN

2. Resource Management

• Credit System: Prevents resource abuse through usage-based billing
• Queue Management: Future integration with job queues for heavy processing
• Auto-scaling: Vercel's automatic scaling based on demand

3. Monitoring and Observability

• Error Tracking: Comprehensive error logging and tracking
• Performance Monitoring: Response time and resource usage monitoring
• Analytics: User behavior and application usage analytics

Integration Architecture

1. External Service Integrations

YouTube Data API v3

• Channel Information: Public channel data and metadata
• Video Data: Video details, performance metrics, and transcripts
• Rate Limiting: Respect for API quotas and rate limits

OpenAI API

• Content Analysis: AI-powered content analysis and insights
• Streaming Responses: Real-time result delivery
• Cost Management: Efficient token usage and cost optimization

Stripe Integration

• Subscription Management: Recurring billing and plan management
• Webhook Handling: Real-time subscription status updates
• Payment Processing: Secure credit card processing

Resend Email Service

• Transactional Emails: Analysis completion notifications
• Template Management: HTML email templates with React Email
• Delivery Tracking: Email delivery status and analytics

2. Database Integration

• Prisma ORM: Type-safe database access with automatic migrations
• PostgreSQL: Relational database with ACID compliance
• Connection Management: Efficient connection pooling and management

Error Handling and Recovery

1. Graceful Degradation

• Partial Failures: System continues to function with reduced capabilities
• User Feedback: Clear error messages and recovery instructions
• Data Consistency: Ensures data integrity even during failures

2. Retry Logic

• API Failures: Automatic retry for transient API failures
• Database Timeouts: Connection retry with exponential backoff
• External Service Failures: Graceful handling of third-party service outages

3. Monitoring and Alerting

• Error Tracking: Comprehensive error logging with stack traces
• Health Checks: Regular system health monitoring
• Alert System: Notifications for critical system failures

This architecture overview provides the foundation for understanding the YouTube Analyzer system. For detailed implementation information, refer to the specific sections of this developer documentation.

Prompt Management System Architecture (2025-06-22)

The prompt management system enables admins to manage, version, and test LLM prompt templates for each analysis type. It is fully integrated with the analysis workflow and supports safe, versioned editing.

Overview

• Admin UI: Located at /app/(protected)/dashboard/admin/prompts/PromptsAdmin/ (tab-based, versioned prompt editing)
• API: All prompt CRUD/versioning handled by /app/api/prompts/
• Backend Logic: Shared prompt logic in lib/prompts.ts
• Prompt Templates: Each analysis type has its own editable, versioned prompt template
• Variables & Testing: UI supports prompt variables, test rendering, and sample transcript injection

Workflow

1. Admin selects analysis type in the tab-based UI
2. Prompt template is loaded (latest version)
3. Admin edits or tests the prompt, using sample variables/transcripts
4. Saving creates a new version (all versions are tracked and can be restored)
5. Analysis workflow always uses the latest active prompt version for the selected type

Versioning & Rollback

• All prompt edits are versioned
• Admins can view, compare, and restore previous versions
• Rollback is instant and safe

API Endpoints

• GET /api/prompts — List all prompt templates
• GET /api/prompts/:id — Get prompt with all versions
• POST /api/prompts — Create new prompt template
• PATCH /api/prompts/:id — Edit prompt or add new version
• POST /api/prompts/:id/test — Render prompt with test data

Security & Access

• Only users with ADMIN role can access the prompt management UI and API
• All changes are logged and versioned for auditability

Maintenance & Cleanup

• All legacy/duplicate prompt admin code has been removed (2025-06-22)
• Only the new tab-based UI and /app/api/prompts/ are active
• See code comments and this documentation for update workflow

Admin Tools & Prompt Management

The architecture includes a dedicated admin system for managing prompt templates and other administrative features:

• Admin UI in the dashboard for prompt management (tabbed, versioned editing)
• API endpoints under /app/api/prompts/ for CRUD/versioning operations
• Shared backend logic in lib/prompts.ts for fetching and versioning prompt templates
• All admin tools are accessible only to users with the ADMIN role

See the Admin Tools documentation for a full technical breakdown of how prompt management and other admin features are architected and integrated into the system.

Subscription System Architecture

The subscription system has been completely refactored (June 2025) to provide a cleaner, more maintainable approach to feature access and billing.

1. Configuration-Driven Design

Analysis Types (config/analysis-types.ts):

• Each analysis type includes feature flags (allowsAutomation, allowsEmailNotifications)
• Credit costs and requirements are centrally defined
• Easy to add new analysis types or modify existing ones

Subscription Plans (config/subscriptions.ts):

• Three simple tiers: Free, Starter, Pro
• Clear feature matrices without complex limitations
• Easy to modify plan benefits in a single location

2. Centralized Feature Access

Feature Checking (lib/subscription-features.ts):

• Single source of truth for all feature access decisions
• Admin bypass system for all restrictions
• Consistent API across frontend and backend
• Type-safe feature checking with TypeScript

Key Functions:

canUseAutomation(userPlan, isAdmin)        // Check automation access
canUseEmailNotifications(userPlan, isAdmin) // Check email access  
canUseAnalysisType(type, userPlan, isAdmin) // Check analysis type access
hasEnoughCredits(type, userPlan, isAdmin)   // Check credit availability

3. Admin Bypass System

Administrators can bypass all subscription restrictions:

• Development: Easier testing of premium features
• Support: Help users troubleshoot without subscription barriers
• Demos: Show full functionality during sales processes
• Implementation: All feature checks accept an isAdmin parameter

4. Simplified Credit System

Credit Management:

• No rollover complexity or automation limits
• Credits reserved at analysis start, deducted on completion
• Clear, predictable credit costs per analysis type
• Admin users have unlimited credits

Credit Flow:

Available Credits = Total Credits - Reserved Credits
Reserve → Process → Deduct (success) OR Release (failure)

5. Integration Points

Frontend Components:

• Pricing cards and comparison tables use config data
• Feature access UI reflects subscription capabilities
• Admin users see all features regardless of subscription

Backend APIs:

• All feature-gated endpoints check subscription access
• Consistent error handling for feature restrictions
• Admin bypass respected in all API routes

Email System:

• Email notifications respect subscription permissions
• Admin users can receive all email types
• Centralized permission checking before sending

6. Migration Strategy

The refactor maintains backward compatibility while simplifying:

• Legacy Support: Existing subscriptions continue to work
• Gradual Transition: Features can be migrated incrementally
• Database Compatibility: No breaking schema changes required
• Admin Controls: Full administrative override capabilities

This architecture enables rapid feature development while maintaining clear subscription boundaries and providing excellent administrative control for support and testing scenarios.