Developer Roadmap Question/Quiz System Architecture: A Stream-Based AI Pipeline Explained

The developer roadmap quiz system uses a stream-based AI generation pipeline that combines React components, React-Query hooks, and a custom chat-stream parser to generate, display, and verify quiz questions in real-time.

The quiz system in the kamranahmedse/developer-roadmap repository implements a sophisticated architecture for generating interactive learning assessments. This developer roadmap question/quiz system leverages streaming AI responses to create dynamic quizzes that adapt to user input while maintaining a responsive frontend experience through incremental content delivery.

High-Level Architecture Overview

The system follows a stream-based AI generation pipeline that separates concerns between UI rendering, data fetching, stream parsing, and state management. The architecture connects four primary layers:

• UI Layer: React components in src/components/AIQuiz/ handle user input and display
• Query Layer: Functions in src/queries/ai-quiz.ts manage API communication
• Stream Parser: src/lib/chat.ts processes real-time AI responses
• Verification Layer: src/hooks/use-verify-answer.ts validates user submissions

Frontend UI Layer

The frontend implements a component hierarchy centered around the <AIQuiz /> entry point in src/components/AIQuiz/AIQuiz.tsx.

AIQuiz Component Structure

The main component renders an <AIQuizLayout> containing two primary sub-components:

• <GenerateAIQuiz />: Located in src/components/AIQuiz/GenerateAIQuiz.tsx, this component captures user input including the target term, quiz format selection, and generation triggers.
• <AIQuizContent />: Defined in src/components/AIQuiz/AIQuizContent.tsx, this component receives streaming question data and renders the interactive quiz interface, including the <AIQuizResultStrip> for answer verification feedback.

The UI imports generation logic from src/queries/ai-quiz.ts and verification hooks from src/hooks/use-verify-answer.ts.

State Management Flow

Components communicate through callback props that trigger during the streaming process:

• onLoadingChange: Toggles loading states during initial request
• onStreamingChange: Indicates active stream reception
• onQuestionsChange: Receives parsed QuizQuestion[] arrays as they accumulate
• onDetailsChange: Captures metadata prefixed with d: in the stream

Data Fetching and Stream Processing

The query layer in src/queries/ai-quiz.ts implements the core generation logic that bridges the frontend components and the AI backend.

The generateAIQuiz Function

The generateAIQuiz() function initiates quiz creation by sending a POST request to /v1-generate-ai-quiz (or /v1-regenerate-ai-quiz when forcing regeneration). The request payload includes:

• term: The subject matter for quiz generation
• format: Output format specification
• prompt: Optional custom instructions
• questionAndAnswers: Existing Q&A pairs for context-aware generation

The function receives a readable stream via response.body and delegates parsing to readChatStream() from src/lib/chat.ts.

Parsing the AI Stream

The readChatStream() function in src/lib/chat.ts processes the stream using the CHAT_RESPONSE_PREFIX protocol. It handles two line prefixes:

• 0: – Message content containing JSON-encoded strings that accumulate into the quiz text
• d: – Detail/metadata lines providing auxiliary information

As chunks arrive, the parser invokes callbacks for each line type, allowing the UI to update incrementally rather than waiting for the complete response.

Question Generation and Parsing

Once the stream completes, generateAIQuiz() aggregates the raw text and converts it into structured data through generateAiQuizQuestions(). This parser transforms the accumulated markdown into an array of QuizQuestion objects, each containing the question text, options, and correct answer indicators.

The resulting QuizQuestion[] array passes to the UI through the onQuestionsChange callback, triggering re-renders of <AIQuizContent /> with the new questions.

React-Query Integration and Caching

The system leverages React-Query for server state management, defined in src/queries/ai-quiz.ts and configured through src/stores/query-client.ts.

Fetching Saved Quizzes

The aiQuizOptions(quizSlug) function creates a query configuration that fetches persisted quizzes from /v1-get-ai-quiz. Upon retrieval, it processes the stored content field using the same generateAiQuizQuestions() parser used during generation, exposing data.questions to consuming components.

This ensures consistent data transformation between freshly generated and previously saved quizzes.

User Quiz Listing

The listUserAiQuizzesOptions() function provides a query for retrieving the user's quiz history. This query is gated by isLoggedIn() from src/lib/jwt.ts, ensuring authentication state validates before attempting to fetch user-specific data from the backend.

Answer Verification System

The verification layer handles answer validation through streaming AI feedback, implemented in src/hooks/use-verify-answer.ts.

The useVerifyAnswer Hook

The useVerifyAnswer hook manages the verification lifecycle. When invoked, it posts the user's answer to /v1-verify-quiz-answer/{slug}. The response streams back using the same protocol as quiz generation, processed through readChatStream().

The hook tracks verification status and aggregates feedback text incrementally as the AI evaluates the answer correctness.

Stream Parsing for Feedback

The parseVerifyAIQuizAnswerResponse() function processes the accumulated stream content to extract structured feedback. It identifies <status> tags indicating correctness and extracts textual explanations provided by the AI evaluator.

This parsed response triggers the onFinish callback with the final verdict and feedback, allowing <AIQuizResultStrip> to display appropriate success or error styling.

Data Models and Backend API

The frontend interacts with a structured data model and external API endpoints, abstracting the AI implementation details.

AIQuizDocument Structure

The server stores quizzes as AIQuizDocument objects (MongoDB-style documents). These contain:

• content: The raw markdown string generated by the AI
• questionAndAnswers: Historical Q&A pairs for context preservation
• View counters and engagement metadata
• Token usage statistics for cost tracking

The frontend never directly manipulates this document; it only consumes the derived QuizQuestion[] array produced by generateAiQuizQuestions().

External API Endpoints

The repository assumes a backend service exposed through PUBLIC_API_URL providing these endpoints:

• POST /v1-generate-ai-quiz: Initiates new quiz generation with streaming response
• POST /v1-regenerate-ai-quiz/:slug: Forces regeneration of existing quiz
• GET /v1-get-ai-quiz/:slug: Retrieves stored quiz document
• POST /v1-verify-quiz-answer/:slug: Validates user answers with streaming feedback

The frontend treats these as opaque streaming endpoints, handling all responses through the readChatStream() abstraction in src/lib/chat.ts.

Summary

The developer roadmap question/quiz system implements a sophisticated streaming architecture that separates concerns across multiple layers:

• Component Layer: React components in src/components/AIQuiz/ handle user interaction and display, with <AIQuiz /> serving as the main entry point
• Stream Processing: The readChatStream() function in src/lib/chat.ts parses AI responses using the CHAT_RESPONSE_PREFIX protocol to handle incremental content delivery
• Data Transformation: generateAiQuizQuestions() in src/queries/ai-quiz.ts converts raw markdown streams into structured QuizQuestion[] arrays
• State Management: React-Query hooks in src/queries/ai-quiz.ts cache quiz data and manage server state for both generation and retrieval operations
• Verification: The useVerifyAnswer hook in src/hooks/use-verify-answer.ts provides real-time AI feedback on user answers through the same streaming protocol

Frequently Asked Questions

How does the developer roadmap quiz system handle real-time AI streaming?

The system uses the readChatStream() function in src/lib/chat.ts to process readable streams from the backend. It parses line prefixes—specifically 0: for message content and d: for details—allowing the UI to incrementally render quiz questions as they generate rather than waiting for the complete response.

What is the difference between generating a new quiz and fetching a saved quiz?

New quiz generation invokes generateAIQuiz() in src/queries/ai-quiz.ts, which POSTs to /v1-generate-ai-quiz and processes a streaming response. Fetching saved quizzes uses aiQuizOptions(), which GETs from /v1-get-ai-quiz and applies the same generateAiQuizQuestions() parser to the stored content field, ensuring consistent data structures between fresh and cached quizzes.

How does the answer verification system work in the developer roadmap quiz architecture?

The useVerifyAnswer hook in src/hooks/use-verify-answer.ts manages verification by posting user answers to /v1-verify-quiz-answer/{slug}. The response streams back through readChatStream() and gets processed by parseVerifyAIQuizAnswerResponse(), which extracts <status> tags and textual feedback to display real-time AI evaluation of user responses.

What authentication mechanisms protect user-specific quiz operations?

User-specific queries like listUserAiQuizzesOptions() are gated by the isLoggedIn() function from src/lib/jwt.ts. This ensures that requests to list a user's quiz history only execute when valid JWT authentication credentials are present, preventing unauthorized access to personal quiz data stored in the AIQuizDocument records.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}