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

> Discover the stream-based AI pipeline architecture powering the developer roadmap quiz system. Learn how React components and a custom parser create real-time quiz experiences.

- Repository: [Kamran Ahmed/developer-roadmap](https://github.com/kamranahmedse/developer-roadmap)
- Tags: architecture
- Published: 2026-02-24

---

**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`](https://github.com/kamranahmedse/developer-roadmap/blob/main/src/queries/ai-quiz.ts) manage API communication
- **Stream Parser**: [`src/lib/chat.ts`](https://github.com/kamranahmedse/developer-roadmap/blob/main/src/lib/chat.ts) processes real-time AI responses
- **Verification Layer**: [`src/hooks/use-verify-answer.ts`](https://github.com/kamranahmedse/developer-roadmap/blob/main/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`](https://github.com/kamranahmedse/developer-roadmap/blob/main/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`](https://github.com/kamranahmedse/developer-roadmap/blob/main/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`](https://github.com/kamranahmedse/developer-roadmap/blob/main/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`](https://github.com/kamranahmedse/developer-roadmap/blob/main/src/queries/ai-quiz.ts) and verification hooks from [`src/hooks/use-verify-answer.ts`](https://github.com/kamranahmedse/developer-roadmap/blob/main/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`](https://github.com/kamranahmedse/developer-roadmap/blob/main/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`](https://github.com/kamranahmedse/developer-roadmap/blob/main/src/lib/chat.ts).

### Parsing the AI Stream

The `readChatStream()` function in [`src/lib/chat.ts`](https://github.com/kamranahmedse/developer-roadmap/blob/main/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`](https://github.com/kamranahmedse/developer-roadmap/blob/main/src/queries/ai-quiz.ts) and configured through [`src/stores/query-client.ts`](https://github.com/kamranahmedse/developer-roadmap/blob/main/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`](https://github.com/kamranahmedse/developer-roadmap/blob/main/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`](https://github.com/kamranahmedse/developer-roadmap/blob/main/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`](https://github.com/kamranahmedse/developer-roadmap/blob/main/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`](https://github.com/kamranahmedse/developer-roadmap/blob/main/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`](https://github.com/kamranahmedse/developer-roadmap/blob/main/src/queries/ai-quiz.ts) converts raw markdown streams into structured `QuizQuestion[]` arrays
- **State Management**: React-Query hooks in [`src/queries/ai-quiz.ts`](https://github.com/kamranahmedse/developer-roadmap/blob/main/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`](https://github.com/kamranahmedse/developer-roadmap/blob/main/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`](https://github.com/kamranahmedse/developer-roadmap/blob/main/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`](https://github.com/kamranahmedse/developer-roadmap/blob/main/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`](https://github.com/kamranahmedse/developer-roadmap/blob/main/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`](https://github.com/kamranahmedse/developer-roadmap/blob/main/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.