Flashquizes - AI-Powered Language Learning Platform

A production-ready Japanese vocabulary learning application built with Next.js 15, featuring AI-generated flashcards, spaced repetition quizzes, and sentence practice with automated evaluation.

Description

Flashquizes combines flashcard-based learning with interactive quizzes and AI-powered sentence practice. The platform supports multiple learning modes, tracks mastery progression through spaced repetition algorithms, and integrates payment processing for premium subscriptions via Vietnamese banking infrastructure.

The application handles authentication through Google OAuth, generates vocabulary content using large language models (Gemini/GPT-4), and processes payments through bank transfer webhooks. Built on Next.js 15 with the App Router architecture, it uses MongoDB for persistent storage and Redis for session management and rate limiting.

Technical Highlights

Core Techniques

• Server-side rendering with Next.js 15 App Router for improved performance and SEO
• JWT-based authentication via NextAuth.js with MongoDB session storage
• Spaced repetition algorithm for adaptive learning based on mastery levels (not-started, not-learned, somewhat, mastered)
• Rate limiting implementation using Redis counters to prevent API abuse
• Webhook verification with cryptographic signatures for secure payment processing
• IndexedDB optimization via MongoDB compound indexes for query performance
• CSRF protection on mutation endpoints
• Edge middleware for route protection and authentication checks
• Idempotency keys to prevent duplicate payment processing
• Progressive Web App capabilities for mobile-like experience

AI Integration

The application uses OpenRouter as an API gateway to access multiple language models (Google Gemini 2.0 Flash, GPT-4o-mini). AI handles vocabulary extraction from text, field mapping (Kanji/Hiragana/Meaning), and sentence evaluation with contextual feedback.

Payment Processing

Integrates SePay for Vietnamese bank transfers using VietQR standard. Payments are verified through webhook callbacks with signature validation, triggering automated subscription activation and invoice generation.

Technologies & Libraries

Framework & Runtime

• Next.js 15 - React framework with App Router
• React 19 - UI library
• TypeScript 5 - Type safety

Database & Caching

• MongoDB 5.0+ - Document database
• Mongoose 8 - ODM with schema validation
• Redis 6.0+ - In-memory cache and rate limiting

Authentication & Security

• NextAuth.js 4 - Authentication framework
• @next-auth/mongodb-adapter - Session persistence
• Zod 3 - Runtime schema validation
• csrf - CSRF token generation

UI & Styling

• Tailwind CSS 4 - Utility-first CSS
• Shadcn UI - Accessible component library built on Radix UI
• Radix UI - Unstyled, accessible components
• Lucide React - Icon library
• Recharts - Chart library for analytics

AI & External Services

• OpenRouter API - Multi-model AI gateway
• SePay - Vietnamese payment gateway
• Nodemailer - Email sending

Data Fetching & State

• SWR 2 - Data fetching and caching
• Axios - HTTP client

Development & Deployment

• Docker - Containerization
• pnpm - Fast, disk-efficient package manager

Additional Tools

• PDFKit - Invoice generation
• BCrypt.js - Password hashing
• node-cron - Scheduled tasks

Project Structure

flashquizes/
├── src/
│   ├── app/              # Next.js App Router pages
│   │   ├── admin/        # Admin dashboard pages
│   │   ├── api/          # API route handlers
│   │   ├── auth/         # Authentication pages
│   │   ├── collections/  # Collection CRUD pages
│   │   ├── quiz/         # Quiz interface pages
│   │   └── ...
│   ├── components/       # React components
│   ├── lib/              # Business logic & utilities
│   ├── models/           # Mongoose models
│   ├── schemas/          # Zod & Mongoose schemas
│   ├── types/            # TypeScript definitions
│   ├── hooks/            # Custom React hooks
│   └── middleware.ts     # Edge middleware
├── docs/                 # Documentation
│   ├── brd.md           # Business requirements
│   ├── prd.md           # Product requirements
│   └── architecture.md  # System architecture
├── docker/               # Docker configurations
├── inits/                # Database initialization scripts
├── public/               # Static assets
└── [config files]

Noteworthy directories:

• src/lib/ contains the core business logic including AI integration (openrouter.ts), payment processing (sepay.ts), and usage limit enforcement (usage-limits.ts)
• src/models/ defines database schemas with performance-optimized indexes
• src/app/api/ implements RESTful endpoints and webhook handlers
• docs/ provides business, product, and architecture documentation

Configuration

Environment variables are managed through .env files. Key configurations include MongoDB connection strings, Redis URLs, OAuth credentials (Google), AI API keys (OpenRouter), and payment gateway credentials (SePay).

The docker-compose.yml orchestrates the application container, MongoDB, and Redis services with proper networking and volume mounting.

Documentation

• Business Requirements - Business objectives and strategy
• Product Requirements - Functional and technical requirements
• System Architecture - Technical architecture overview