🎓 منصة براعة (Exam Platform)

A comprehensive Next.js 15 exam preparation and management platform with Arabic (RTL) support, role-based access control, and subscription management.

✨ Features

🔐 Authentication & Authorization

• better-auth integration with email OTP and Google OAuth
• Role-based access control (ADMIN, STUDENT, EDITOR)
• Custom session management with subscription sync
• Secure API endpoints with Arcjet protection

📚 Exam Management

• Create and manage exams with time limits
• Multiple question types: MULTIPLE_CHOICE, TRUE_FALSE, CHART_AND_MULTIPLE_CHOICE, TABLE_AND_MULTIPLE_CHOICE
• CSV question import functionality
• Question randomization system
• Real-time progress tracking with automatic submission

👥 User Management

• Comprehensive user profiles with exam history
• Data privacy controls and export capabilities
• Subscription management (FREE/PRO plans)
• Usage tracking and limits

🎨 Admin Dashboard

• Analytics and metrics dashboard
• User management interface
• Content creation and management

💳 Subscription System

• Polar.sh integration for payments
• Webhook handling with signature verification
• Usage-based billing and limits
• Customer portal integration

🌐 Public Features

• Publicly accessible exam catalog
• Pricing and subscription pages
• SEO-optimized with sitemap generation

🛠 Tech Stack

Frontend

• Next.js 15 - React framework with App Router
• React 19 - UI library
• TypeScript - Type safety
• Tailwind CSS - Utility-first styling
• shadcn/ui - Reusable component library
• Framer Motion - Animations
• Recharts - Data visualization

Backend

• Next.js Server Actions - Server-side logic
• Prisma ORM - Database management
• PostgreSQL - Primary database
• better-auth - Authentication system
• Zod - Schema validation

Infrastructure & Services

• Arcjet - Rate limiting and security
• Polar.sh - Subscription management
• Nodemailer - Email delivery
• Pino - Structured logging
• CSV Parser - Bulk data import

Development Tools

• Bun - Fast JavaScript runtime and package manager
• Biome - Fast linter and formatter
• Husky - Git hooks
• tsx - TypeScript execution
• Prisma Studio - Database GUI

🚀 Quick Start

Prerequisites

• Bun 1.0+ (or Node.js 18+)
• PostgreSQL database

Installation

1. Clone the repository

   git clone https://github.com/tinyfroggy/exam-app
   cd exam-app

2. Install dependencies

   bun install

3. Setup environment variables

   cp .env.example .env

   Fill in your environment variables (see Environment Variables section)

4. Setup database

   bun run prisma

5. Start development server

   bun dev

Visit http://localhost:3000 to see the application.

📋 Available Scripts

Development

bun dev         # Start development server
bun run build   # Build for production  
bun run start   # Start production server

Database

bun run prisma    # Generate Prisma client and push schema
bun run seed      # Seed database with test data
bun run db:reset  # Reset database and seed (⚠️ deletes all data)
bun run studio    # Open Prisma Studio

Code Quality

bun run check   # Run Biome linter and formatter
bun run showE   # TypeScript type checking

🔧 Environment Variables

Copy .env.example to .env and configure the following sections:

Database

DATABASE_URL=postgresql://user:password@localhost:5432/exam_db

Authentication

BETTER_AUTH_SECRET=your-secret-key
BETTER_AUTH_URL=http://localhost:3000
NEXT_PUBLIC_BETTER_AUTH_URL=http://localhost:3000

OAuth (Google)

GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

Email Configuration

APP_EMAIL_ADDRESS=your-email@gmail.com
APP_EMAIL_PASSWORD=your-app-password

Security & Performance

ARCJET_KEY=your-arcjet-key

Subscription Management

POLAR_ACCESS_TOKEN=your-polar-access-token
POLAR_PRODUCT_ID_PRO=your-product-id
POLAR_SUCCESS_URL=http://localhost:3000/success
POLAR_WEBHOOK_SECRET=your-webhook-secret

Usage Limits

FREE_PLAN_MONTHLY_LIMIT=10
PRO_PLAN_MONTHLY_LIMIT=1000

🏗 Project Architecture

Route Structure

app/
├── (admin)/          # Admin-only routes
├── (auth)/           # Authentication pages  
├── (private)/        # Protected user routes
├── (public)/         # Public pages
└── api/              # API endpoints (minimal)

Database Schema

• Users - Authentication and profile data
• Exams - Exam definitions and metadata
• Questions - Question bank with multiple types
• UserExamAttempts - Exam sessions and results

Service Architecture

• BaseService - Common database operations
• AdminActions - Admin-specific operations
• AuthActions - Authentication services
• UserActions - User profile management
• SubscriptionActions - Payment and billing

🔒 Security Features

• Rate limiting with Arcjet
• Email validation and protection
• Webhook signature verification
• SQL injection prevention with Prisma
• XSS protection with sanitization
• RBAC (Role-Based Access Control)

🌍 Internationalization

• Full Arabic (RTL) support
• Arabic UI text and messages
• RTL-optimized layouts
• Arabic date and time formatting

📊 Analytics & Monitoring

• Structured logging with Pino
• Error tracking and handling
• Performance monitoring
• Usage analytics for subscriptions

🚀 Deployment

Railway (Recommended)

Deploy to Railway with one click or via CLI:

1. Create a new project on Railway
2. Connect your GitHub repository
3. Add a PostgreSQL database from the Railway dashboard
4. Set your environment variables from .env.example
5. Railway will auto-deploy on every push to main

Database Setup

Ensure your PostgreSQL database is accessible and run:

npx prisma migrate deploy

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License.

🔗 Links

• API Reference: Available in development mode
• Support: Create an Issue

---

Built with ❤️ using Next.js 15 and modern web technologies