Skip to content

PROJECT_STRUCTURE.md

Latest commit

 

History

History
423 lines (346 loc) · 10.9 KB

PROJECT_STRUCTURE.md

File metadata and controls

423 lines (346 loc) · 10.9 KB

Project Structure

Comprehensive overview of the VideoGen Messenger codebase organization.

Root Directory

VideoGenMessenger/
├── ios/                    # iOS application and iMessage extension
├── backend/                # Node.js backend API and services
├── infrastructure/         # Infrastructure as Code (Terraform/CDK)
├── docs/                   # Documentation
├── assets/                 # Static assets (logos, images)
└── README.md               # Project overview

iOS Directory (ios/)

Structure

ios/
├── VideoGenMessenger/              # Main iOS app
│   ├── App/
│   │   ├── AppDelegate.swift
│   │   ├── SceneDelegate.swift
│   │   └── Info.plist
│   ├── Views/
│   ├── ViewModels/
│   └── Resources/
│
└── VideoGenMessengerExtension/     # iMessage extension
    ├── MessagesViewController.swift          # Main VC (UIKit + SwiftUI bridge)
    ├── VideoGeneratorRootView.swift         # SwiftUI root view
    ├── VideoGenerationViewModel.swift       # View model
    │
    ├── Models/
    │   └── VideoMetadata.swift             # Data models
    │
    ├── Services/
    │   ├── VideoGenerationAPIService.swift  # API communication
    │   ├── MediaCacheManager.swift          # Two-tier caching
    │   └── VideoStorageService.swift        # Storage operations
    │
    ├── Utilities/
    │   ├── SharedStorage.swift             # App Group utilities
    │   └── Configuration.swift             # App configuration
    │
    └── Info.plist

Key Files

MessagesViewController.swift

  • Main entry point for iMessage extension
  • Manages lifecycle (willBecomeActive, didResignActive, etc.)
  • Bridges UIKit and SwiftUI
  • Handles message sending

VideoGeneratorRootView.swift

  • SwiftUI-based UI
  • Adapts between compact and expanded views
  • Contains Browse, Search, Create tabs
  • Manages user interactions

VideoGenerationViewModel.swift

  • ObservableObject managing state
  • Handles API communication
  • Manages video generation flow
  • Cache and storage coordination

VideoGenerationAPIService.swift

  • REST API client
  • Endpoints: search, trending, generate, status
  • Request/response handling
  • Error management

MediaCacheManager.swift

  • Two-tier caching: NSCache (memory) + Disk
  • LRU eviction policy
  • 100MB disk cache limit
  • 50MB memory cache limit

Backend Directory (backend/)

Structure

backend/
├── api/
│   ├── server.js                   # Express server entry point
│   ├── routes/
│   │   ├── index.js               # Route aggregator
│   │   ├── generation.js          # POST /generate, GET /status/:id
│   │   ├── search.js              # GET /search
│   │   ├── trending.js            # GET /trending
│   │   ├── videos.js              # GET /videos/:id
│   │   └── auth.js                # POST /auth/register
│   │
│   ├── controllers/
│   │   ├── generationController.js
│   │   ├── searchController.js
│   │   ├── trendingController.js
│   │   ├── videoController.js
│   │   └── authController.js
│   │
│   ├── middleware/
│   │   ├── auth.js                # API key validation
│   │   ├── rateLimit.js           # Token bucket rate limiting
│   │   ├── validation.js          # Request validation (Joi)
│   │   └── errorHandler.js        # Global error handler
│   │
│   └── utils/
│       └── logger.js              # Winston logger
│
├── services/
│   ├── generation/
│   │   └── GenerationService.js   # AI video generation logic
│   │
│   ├── search/
│   │   └── SearchService.js       # Elasticsearch search
│   │
│   ├── queue/
│   │   └── QueueService.js        # BullMQ job queue
│   │
│   ├── trending/
│   │   └── TrendingService.js     # Trending algorithm
│   │
│   ├── video/
│   │   └── VideoService.js        # Video metadata
│   │
│   ├── moderation/
│   │   └── ModerationService.js   # Content moderation (TODO)
│   │
│   └── analytics/
│       └── AnalyticsService.js    # Analytics tracking (TODO)
│
├── config/
│   └── database.js                # Database configuration (TODO)
│
├── package.json                   # Dependencies and scripts
└── .env.example                   # Environment variables template

API Routes

Endpoint Method Description
/health GET Health check
/api/v1/generate POST Request video generation
/api/v1/generate/status/:jobId GET Check generation status
/api/v1/search GET Search videos
/api/v1/trending GET Get trending videos
/api/v1/videos/:id GET Get video details
/api/v1/auth/register POST Register API key

Services Layer

GenerationService.js

  • Interfaces with AI providers (Google Veo 3, Runway, Minimax)
  • Manages generation jobs
  • Polls for completion
  • Stores results

SearchService.js

  • Elasticsearch client
  • Multi-match queries across title, description, tags, prompt
  • Autocomplete suggestions
  • Filters by quality, duration, etc.

QueueService.js

  • BullMQ queue management
  • Worker pool for async processing
  • Retry logic with exponential backoff
  • Job status tracking

TrendingService.js

  • Calculates trending scores
  • Caches results (5-15 min TTL)
  • Considers recency + engagement

Infrastructure Directory (infrastructure/)

infrastructure/
├── terraform/              # Terraform IaC
│   ├── main.tf
│   ├── variables.tf
│   ├── outputs.tf
│   ├── vpc.tf
│   ├── ecs.tf
│   ├── rds.tf
│   ├── elasticache.tf
│   ├── s3.tf
│   └── cloudfront.tf
│
└── cdk/                   # AWS CDK (TypeScript)
    ├── bin/
    ├── lib/
    └── package.json

Documentation Directory (docs/)

docs/
├── API.md                  # API documentation
├── GETTING_STARTED.md      # Setup guide
├── PROJECT_STRUCTURE.md    # This file
├── ARCHITECTURE.md         # Architecture overview
├── DEPLOYMENT.md           # Deployment guide
└── TROUBLESHOOTING.md      # Common issues

Data Flow

Video Generation Flow

1. User Input (iOS)
   └─> VideoGeneratorRootView
       └─> VideoGenerationViewModel
           └─> VideoGenerationAPIService
               └─> POST /api/v1/generate

2. Backend Processing
   └─> generationController.requestGeneration()
       └─> QueueService.addGenerationJob()
           └─> BullMQ Queue

3. Worker Processing
   └─> QueueService Worker
       └─> GenerationService.generate()
           └─> Google Veo 3 API
               └─> Download video
                   └─> Upload to S3
                       └─> Generate thumbnail
                           └─> Update status

4. Status Polling (iOS)
   └─> GET /api/v1/generate/status/:jobId
       └─> GenerationService.getStatus()
           └─> Return video_url when complete

5. Video Display
   └─> VideoGenerationViewModel receives URL
       └─> Download and cache locally
           └─> Display in iMessage

Search Flow

1. User Search (iOS)
   └─> SearchView
       └─> VideoGenerationViewModel.searchVideos()
           └─> GET /api/v1/search?q=...

2. Backend Search
   └─> searchController.search()
       └─> SearchService.search()
           └─> Elasticsearch query
               └─> Return results

3. Display Results
   └─> VideoGeneratorRootView updates
       └─> Grid of thumbnails
           └─> Tap to select and send

Configuration Files

Environment Variables (.env)

# Server
NODE_ENV=development
PORT=3000

# Database
DATABASE_URL=postgresql://...
REDIS_URL=redis://localhost:6379

# AI Providers
GOOGLE_VEO_API_KEY=...
RUNWAY_API_KEY=...

# AWS
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_S3_BUCKET=...
AWS_CLOUDFRONT_DOMAIN=...

# Security
JWT_SECRET=...
API_KEY_SALT=...

# Features
ENABLE_AI_GENERATION=true
ENABLE_CONTENT_MODERATION=true

iOS Configuration (Configuration.swift)

- apiKey: API key for backend
- apiBaseURL: Base URL (dev/prod)
- enableAIGeneration: Feature flag
- maxCacheSize: Cache size limit
- videoQuality: Default quality

Testing Structure

backend/
└── __tests__/
    ├── unit/
    │   ├── services/
    │   └── utils/
    ├── integration/
    │   └── api/
    └── e2e/

ios/
└── VideoGenMessengerTests/
    ├── ViewModelTests/
    ├── ServiceTests/
    └── UITests/

Build Outputs

iOS

DerivedData/
└── VideoGenMessenger/
    └── Build/Products/
        └── Debug-iphonesimulator/
            └── VideoGenMessenger.app

Backend

backend/
├── node_modules/
├── logs/
│   ├── error.log
│   └── combined.log
└── dist/           # If using TypeScript

Key Design Patterns

iOS

  • MVVM: ViewModel separates business logic from views
  • Dependency Injection: Services injected into ViewModel
  • Observer Pattern: @Published properties with ObservableObject
  • Repository Pattern: Services abstract data sources

Backend

  • MVC: Models-Views-Controllers (Express pattern)
  • Service Layer: Business logic separated from controllers
  • Middleware Chain: Auth → Rate Limit → Validation → Controller
  • Queue Pattern: Async job processing with BullMQ

Next Steps for Implementation

Immediate (Week 1)

  • Implement actual AI provider integration in GenerationService.js
  • Set up PostgreSQL schema and database connection
  • Implement Elasticsearch indexing
  • Add S3 upload functionality

Short-term (Month 1)

  • Content moderation implementation
  • User authentication and API key management
  • Analytics tracking
  • Comprehensive error handling

Medium-term (Months 2-3)

  • Multi-region deployment
  • Advanced caching strategies
  • Machine learning for search ranking
  • Real-time status updates (WebSockets)

Development Guidelines

  • Code Style: Follow Airbnb style guide (JS), Swift style guide
  • Commit Messages: Conventional Commits format
  • Branch Strategy: Git Flow (main, develop, feature/, hotfix/)
  • Testing: Minimum 80% code coverage
  • Documentation: JSDoc for JS, Swift DocC for Swift

For questions about the project structure, see CONTRIBUTING.md or contact the development team.