Architecting Learntail: Building an AI Quiz Generator in Weeks

Prerequisites

To get the most out of this architecture, you should have a solid grasp of Python for backend development and TypeScript for the frontend. Familiarity with Docker for containerization and basic cloud deployment concepts on Google Cloud Platform (GCP) is essential. You also need an understanding of how to interact with RESTful APIs.

Key Libraries & Tools

• FastAPI: A modern, high-performance web framework for building APIs with Python.
• Next.js: The React-based framework used for the frontend to handle server-side rendering and routing.
• MongoDB Atlas: A fully managed NoSQL database-as-a-service.
• OpenAI API: Powering the quiz generation via the GPT-3.5 Turbo model.
• LangChain: The orchestration library used to manage prompts and AI interactions.
• Tailwind CSS: A utility-first CSS framework for rapid UI development.

Code Walkthrough & Repository Structure

We organize everything into a single monorepo. This drastically simplifies dependency management and CI/CD orchestration.

Backend Structure (FastAPI)

The backend is segmented by concern rather than service. The routers/ folder handles API endpoints like /quizzes and /users, while the database/ layer contains the logic for interacting with MongoDB Atlas.

# backend/main.py snippet
from fastapi import FastAPI
from .routers import quizzes, auth

app = FastAPI()
app.include_router(quizzes.router)
app.include_router(auth.router)

Frontend Logic (Next.js)

The frontend uses dynamic routing to fetch quizzes based on a unique slug. This slug is stored in the database and retrieved via the API when a user visits a specific quiz URL.

// src/app/quiz/[slug]/page.tsx
async function QuizPage({ params }: { params: { slug: string } }) {
  const quiz = await getQuizFromAPI(params.slug);
  return <QuizPlayer data={quiz} />;
}

Deployment & CI/CD

We use GitHub Actions to automate the build and deployment to Google Cloud Run. To avoid unnecessary costs, the workflow uses path filtering. If you only change code in the /backend folder, the frontend container does not rebuild. This keeps your CI/CD pipeline lean and efficient.

Tips & Gotchas

Avoid reinventing the wheel. Use existing libraries for everything from rate limiting to email verification. A major mistake developers make is trying to host their own database or AI models too early. Use "ready-to-go" services like SendGrid for magic links and Stripe for payments. This allows you to launch fast and iterate based on real user feedback rather than technical assumptions.