Python Daily Challenge - Backend API

> Frontend repository <

A FastAPI backend service that generates AI-powered Python coding challenges using OpenAI's GPT models. Features user authentication via Clerk, intelligent quota management, and comprehensive challenge history tracking across multiple difficulty levels.

---

Key Features

• AI-Powered Challenge Generation using OpenAI API with structured outputs
• User Authentication with Clerk Auth and webhook integration
• RESTful API Endpoints for challenges, user history, and quota management
• Intelligent Quota System with automatic 24-hour reset
• PostgreSQL Database with SQLAlchemy ORM and Alembic migrations
• Challenge History Tracking for all user-generated challenges
• Fallback Challenge System for reliability when AI generation fails
• Structured Logging with Loguru for monitoring and debugging

---

Tech Stack

• Python 3.12+
• FastAPI
• PostgreSQL
• SQLAlchemy
• Alembic
• OpenAI API
• Clerk
• Uvicorn
• Loguru
• Pydantic
• uv for package management

---

Getting Started

Prerequisites

• Python 3.12 or higher
• uv package manager
• PostgreSQL installed and running
• OpenAI API key
• Clerk account with API keys

Local Setup

1. Clone the repository:

   git clone https://github.com/rafaelanobre/python-daily-challenge-backend.git
   cd python-daily-challenge-backend

2. Create and activate a virtual environment:

   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies:

   uv sync

4. Set up your environment variables:

   • Copy .env.example to .env
   • Fill in your DATABASE_URL, OPEN_AI_KEY, CLERK_SECRET_KEY, CLERK_JWT_KEY, CLERK_AUTHORIZED_PARTIES, and CLERK_WEBHOOK_SECRET

   DATABASE_URL=postgresql://username:password@localhost:5432/python_challenge
   ALLOWED_ORIGINS=http://localhost:5173
   ENVIRONMENT=development
   OPEN_AI_KEY=your_openai_api_key
   CLERK_SECRET_KEY=your_clerk_secret_key
   CLERK_JWT_KEY="your_clerk_jwt_key"
   CLERK_AUTHORIZED_PARTIES=your_authorized_parties
   CLERK_WEBHOOK_SECRET=your_webhook_secret

5. Run database migrations:

   alembic upgrade head

6. Start the server:

   python server.py

   The API will be available at http://localhost:8000

7. View API documentation:

   • Swagger UI: http://localhost:8000/docs
   • ReDoc: http://localhost:8000/redoc

---

API Documentation

Main Endpoints

Method	Endpoint	Description	Auth Required
POST	/api/generate-challenge	Generate a new AI-powered challenge	Yes
GET	/api/my-history	Returns the logged-in user's challenge history	Yes
GET	/api/quota	Returns the user's current quota status	Yes
POST	/webhooks/clerk	Clerk webhook for user creation	Webhook Signature

Example Request

Generate Challenge:

POST /api/generate-challenge
Authorization: Bearer <clerk-jwt-token>
Content-Type: application/json

{
  "difficulty": "easy"
}

Response:

{
  "id": 1,
  "difficulty": "easy",
  "title": "Sum of Two Numbers",
  "options": ["option1", "option2", "option3", "option4"],
  "correct_answer_id": "1",
  "explanation": "The correct answer is option1 because...",
  "timestamp": "2025-10-15T10:30:00Z"
}

---

Project Structure

backend/
├── migrations/             # Alembic database migrations
├── src/
│   ├── database/           # Database models and connection
│   ├── dependencies/       # Dependency injection
│   ├── middleware/         # Custom middleware
│   ├── models/             # Pydantic models
│   ├── routes/             # API endpoints
│   ├── services/           # Business logic
│   ├── ai_generator.py     # OpenAI integration
│   ├── app.py              # FastAPI application
│   └── logger.py           # Logging configuration
├── server.py               # Application entry point
├── pyproject.toml          # Dependencies
└── .env.example            # Environment template

---

Roadmap

Planned improvements and features currently in development:

• Implement pagination for challenge history endpoint
• Dockerize application with multi-stage builds
• Create CI/CD pipeline with GitHub Actions
• Add health check and monitoring endpoints

---

License

MIT License

Copyright (c) 2025 Rafaela Nobre

Acknowledgments

This project uses:

• FastAPI, licensed under the MIT License.
• OpenAI Python SDK, licensed under the Apache 2.0 License.
• Clerk Backend API, licensed under the MIT License.
• PostgreSQL and SQLAlchemy, licensed under the MIT License.