🚀 Secure AI App With Auth - Project Overview

📋 Project Description

A full-stack web application that generates AI-powered coding challenges with secure user authentication. Users can create personalized coding questions at different difficulty levels, track their challenge history, and manage daily quotas - all powered by OpenAI's GPT models and secured with Clerk authentication.

🏗️ Architecture Overview

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   React Frontend │◄──►│  FastAPI Backend │◄──►│   OpenAI API    │
│   (Port 3000)    │    │   (Port 8000)    │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       
         │                       │                       
         ▼                       ▼                       
┌─────────────────┐    ┌─────────────────┐              
│  Clerk Auth      │    │   SQLite DB     │              
│  (Authentication)│    │   (Local Data)  │              
└─────────────────┘    └─────────────────┘              
         │                                               
         ▼                                               
┌─────────────────┐                                     
│     Ngrok       │                                     
│  (Webhooks)     │                                     
└─────────────────┘                                     

🛠️ Tech Stack

Frontend

• Framework: React 19.1.0 with TypeScript
• Build Tool: Vite 6.3.5 (with SWC for fast compilation)
• Authentication: Clerk React SDK 5.31.9
• State Management: TanStack React Query 5.80.6
• Routing: React Router 7.6.2
• Validation: Zod 3.25.60
• Styling: CSS with modern features

Backend

• Framework: FastAPI (Python 3.13)
• Package Manager: UV (ultra-fast Python package manager)
• Authentication: Clerk Backend API 3.0.3
• Database: SQLite with SQLAlchemy 2.0.41 ORM
• AI Integration: OpenAI API 1.85.0 (GPT-4.1-mini)
• Webhooks: Svix 1.67.0 for secure webhook handling
• Server: Uvicorn 0.34.3 ASGI server

DevOps & Infrastructure

• Tunneling: Ngrok for webhook development
• Environment: Python virtual environments with UV

✨ Key Features

🔐 Authentication & Security

• Clerk Integration: Secure user authentication with JWT tokens
• Webhook Security: Svix-powered webhook verification
• CORS Protection: Configured for secure cross-origin requests
• Environment Variables: Secure credential management

🤖 AI-Powered Challenge Generation

• OpenAI Integration: GPT-4.1-mini for intelligent question generation
• Difficulty Levels: Easy, Medium, Hard challenges
• Structured Output: JSON-formatted responses with validation
• Fallback System: Graceful degradation if AI service fails

📊 User Management

• Daily Quotas: Rate limiting for challenge generation
• Challenge History: Personal challenge tracking
• User Profiles: Clerk-managed user data
• Auto-Reset: Daily quota refresh system

🎯 Challenge System

• Multiple Choice: 4-option questions with single correct answer
• Explanations: Detailed explanations for learning
• Validation: Pydantic models for data integrity
• Storage: SQLite database for persistence

🚀 Development Workflow

Local Development

# Frontend: http://localhost:3000
# Backend: http://localhost:8000
# Ngrok Dashboard: http://localhost:4040

Environment Configuration

# Required Environment Variables
OPENAI_API_KEY=your_openai_key
CLERK_SECRET_KEY=your_clerk_secret
NGROK_AUTHTOKEN=your_ngrok_token
NGROK_DOMAIN=your-domain.ngrok-free.app

📁 Project Structure

├── frontend/                 # React TypeScript application
│   ├── src/
│   │   ├── auth/            # Authentication components
│   │   ├── challenge/       # Challenge generation UI
│   │   ├── history/         # Challenge history views
│   │   ├── layout/          # Layout components
│   │   └── types/           # TypeScript definitions
│   ├── package.json         # Node.js dependencies
│   └── vite.config.ts       # Vite configuration
│
├── backend/                  # FastAPI Python application
│   ├── src/
│   │   ├── routes/          # API endpoints
│   │   ├── database/        # SQLAlchemy models & operations
│   │   ├── ai_generator.py  # OpenAI integration
│   │   └── utils.py         # Helper functions
│   ├── pyproject.toml       # Python dependencies (UV)
│   
│
└── .env                     # Environment variables

🔄 API Endpoints

Challenge Management

• POST /api/generate-challenge - Generate new AI challenge
• GET /api/my-history - Retrieve user's challenge history
• GET /api/quota - Check remaining daily quota

Webhooks

• POST /webhooks/clerk - Handle Clerk authentication events

🔧 Development Optimizations

• Hot reload for both frontend and backend
• Fast dependency installation with UV
• Ngrok integration for webhook testing
• Environment variable injection

🎯 Use Cases

• Coding Interview Prep: Generate practice questions
• Educational Tools: Learning platform for developers
• Skill Assessment: Evaluate programming knowledge
• Daily Practice: Quota-based learning routine

🔮 Future Enhancements

• Multiple programming languages support
• Advanced difficulty customization
• Team challenges and leaderboards
• Integration with coding platforms
• Mobile application development

---

Built with ❤️ using modern web technologies for secure, scalable, and intelligent coding challenge generation.