Culilingo - English Learning Platform

Culilingo is an interactive English learning platform for Spanish speakers that combines video lessons with gamified learning experiences.

Features

• Interactive Video Lessons: Learn with real video content, subtitles, and speed controls
• Multiple Choice Questions: Immediate feedback with explanations in Spanish
• Gamification: Points, streaks, achievements, and leaderboards
• Progress Tracking: Detailed analytics by category and skill level
• Content Management: Admin panel for managing videos and questions
• Responsive Design: Optimized for mobile and desktop

Tech Stack

• Frontend: Next.js 13+ with App Router, TypeScript, Tailwind CSS
• UI Components: shadcn/ui, Radix UI primitives
• Database: PostgreSQL with Prisma ORM
• Authentication: NextAuth.js
• File Storage: AWS S3 (or compatible)
• AI Services: OpenAI GPT-4, Whisper API
• Deployment: Vercel (frontend) + Render (database)

Getting Started

Prerequisites

• Node.js 18+
• PostgreSQL database
• AWS S3 bucket (for video storage)
• OpenAI API key

Installation

1. Clone the repository:

git clone https://github.com/your-username/culilingo.git
cd culilingo

2. Install dependencies:

npm install

3. Set up environment variables:

cp .env.example .env.local

Fill in your environment variables in .env.local

4. Set up the database:

npx prisma migrate dev
npx prisma db seed

5. Run the development server:

npm run dev

6. Open http://localhost:3000 in your browser.

Database Schema

Core Tables

• users: User accounts and profiles
• categories: Lesson categories (Travel, Work, etc.)
• videos: Video metadata and storage info
• scenes: Individual video segments
• questions: Multiple choice questions
• options: Answer choices for questions
• attempts: User question attempts
• scores: User points and progress
• leaderboards: Ranking data

Key Relationships

• Users have many attempts and scores
• Videos belong to categories and have many scenes
• Scenes have many questions
• Questions have many options and attempts

API Endpoints

Public Routes

• GET /api/lessons - Get paginated lessons with filters
• POST /api/auth/login - User authentication
• GET /api/leaderboard - Public leaderboard

Protected Routes

• POST /api/attempts - Submit question attempts
• GET /api/me/progress - User progress data
• GET /api/me/achievements - User achievements

Admin Routes (CMS)

• POST /api/admin/videos - Upload new videos
• GET /api/admin/questions/draft - Get draft questions
• PUT /api/admin/questions/:id - Edit questions
• POST /api/admin/questions/:id/publish - Publish questions

Content Processing Pipeline

1. Video Upload: Admin uploads video with metadata
2. Transcription: Whisper API generates English transcripts
3. Scene Detection: AI identifies natural break points
4. Question Generation: GPT-4 creates multiple choice questions
5. Review & Edit: Admin reviews and refines AI-generated content
6. Publication: Content goes live for students

Deployment

Vercel (Frontend)

1. Connect your repository to Vercel
2. Set environment variables in Vercel dashboard
3. Deploy automatically on git push

Render (Database)

1. Create PostgreSQL database on Render
2. Note the connection string
3. Run migrations: npx prisma migrate deploy

AWS S3 (Storage)

1. Create S3 bucket for video storage
2. Set up CORS policy for browser uploads
3. Configure IAM user with appropriate permissions

Performance Optimizations

• Video Streaming: Progressive download with adaptive bitrates
• Image Optimization: Next.js Image component with WebP
• Caching: Redis for session data and leaderboards
• CDN: CloudFront for global video delivery
• Database: Connection pooling and query optimization

Security Features

• Authentication: Secure JWT tokens with refresh rotation
• Rate Limiting: API protection against abuse
• Input Validation: Zod schemas for type safety
• CORS: Proper cross-origin resource sharing
• Content Reporting: User-generated content moderation

Analytics & Monitoring

• User Events: Video play, question attempts, completion
• Performance: Response times and error rates
• Business Metrics: User engagement and retention
• Error Tracking: Comprehensive error logging

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and add tests
4. Commit: git commit -am 'Add feature'
5. Push: git push origin feature-name
6. Create a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support, email help@culilingo.com or join our Discord server.