Smart Question Ordering

Relevant source files

The following files were used as context for generating this wiki page:

• backend/api/questions.py
• web/src/components/QuestionList.js
• backend/database.py
• web/src/context/WebSocketContext.js
• web/src/components/QuestionCard.js
• README.md

Smart Question Ordering is a core feature of the QA-Dashboard that ensures questions are displayed in a prioritized manner. The primary goal is to surface important and time-sensitive questions, such as those marked "Escalated," to the top of the list for immediate attention from administrators. This logic is handled exclusively on the backend, providing a consistently ordered list to all clients.

The ordering is based on a two-tier system: first by the question's status and then by its creation timestamp. This ensures that questions requiring action are always visible above others, while questions within the same status category are sorted chronologically.

Sources: README.md:14, backend/api/questions.py:113-117

Architecture and Data Flow

The ordering logic is implemented within the FastAPI backend and consumed by the Next.js frontend. The frontend does not perform any sorting itself; it renders the list of questions in the exact order it receives from the server. This ensures a single source of truth for the question order across all user sessions.

The data flow for retrieving the sorted list occurs in two primary scenarios:

1. Initial Load (HTTP): When a user first loads the forum page, a standard HTTP GET request is made to the /questions endpoint, which returns a JSON array of questions already sorted by the backend.
2. Real-time Connection (WebSocket): Upon establishing a WebSocket connection, the server immediately sends a questions_list message containing the complete, sorted list of all current questions. Subsequent updates (new questions, status changes) are broadcast to clients to update their local state.

This diagram illustrates the high-level data flow for fetching and displaying the sorted question list.

Backend Implementation

The sorting logic resides entirely in the backend/api/questions.py file and is applied to both the REST API endpoint and the WebSocket connection handler.

Ordering Logic

The sorting is performed in Python after fetching the questions from the database. It uses a predefined priority map for question statuses.

1. Primary Sort Key: The status of the question. A dictionary status_order maps each status to a numerical priority.
2. Secondary Sort Key: The created_at timestamp of the question, sorted in descending order (newest first).

The defined status priority is as follows:

• Escalated: 0 (Highest priority)
• Pending: 1
• Answered: 2 (Lowest priority)

Sources: backend/api/questions.py:109-112, backend/database.py:27-31

The following code snippet from the get_questions endpoint demonstrates the implementation:

# backend/api/questions.py:113-117
    status_order = {
        QuestionStatus.ESCALATED: 0,
        QuestionStatus.PENDING: 1,
        QuestionStatus.ANSWERED: 2,
    }

    questions = query.order_by(desc(Question.created_at)).all()

    questions.sort(
        key=lambda q: (status_order.get(q.status, 3), -q.created_at.timestamp())
    )

This logic is also mirrored in the websocket_endpoint function to provide the initial sorted list to new WebSocket clients.

Sources: backend/api/questions.py:84-88, backend/api/questions.py:113-119

Key Components

QuestionStatus Enum

This enum defines the possible states a question can be in, which is the basis for the primary sorting criteria.

Sources: backend/database.py:27-31

API Endpoints

The following endpoints are directly involved in the smart ordering feature:

Endpoint	Method	Description
/questions	GET	Fetches all questions, applying the smart ordering logic before returning the list.
/questions/ws	WebSocket	Establishes a real-time connection. On connection, it sends a complete, sorted list of all questions.
/questions/{question_id}	PATCH	Updates a question's status. This triggers a question_updated WebSocket event, but does not re-sort the list on the client side.

Sources: backend/api/questions.py:77, backend/api/questions.py:101, backend/api/questions.py:151

Frontend Display

The frontend is responsible for rendering the pre-sorted list received from the backend. The core components involved are WebSocketContext, QuestionList, and QuestionCard.

Data Consumption and State Management

The WebSocketContext manages the connection and the local state of the questions array.

1. Initial Connection: When the WebSocket connects, it receives a questions_list message. The payload (message.data) is used to set the initial state of the questions array. This list is already sorted by the backend.
2. Real-time Updates:
   • question_created: A new question is prepended to the existing questions array.
   • question_updated: The context finds the updated question in the array by its id and replaces it with the new data.

It is important to note that while the initial list is perfectly sorted, subsequent question_updated events update the question in place. This means if a 'Pending' question at the bottom of the list is updated to 'Escalated', it will not automatically move to the top of the list until the component is reloaded or the connection is re-established.

The diagram below shows the sequence of events when a user loads the forum page.

Rendering Components

• QuestionList.js: This is a simple presentational component. It receives the questions array as a prop and uses map() to render a QuestionCard for each question. It performs no sorting or reordering.
• QuestionCard.js: This component displays individual question details. It visually represents the question's status with a colored badge and a left border, providing an immediate visual cue that corresponds to the smart ordering. For example, 'Escalated' questions have a red border, making them stand out at the top of the list.

Sources: web/src/components/QuestionList.js:8-16, web/src/components/QuestionCard.js:101-104, web/src/components/QuestionCard.js:111-113

Data Model

The Question model in the database contains the fields necessary for the ordering logic.

This ER diagram shows the Question table and its relationship with the User table.

questions Table Schema

Column	Type	Constraints	Description
id	UUID	PRIMARY KEY	Unique identifier for the question.
user_id	UUID	FOREIGN KEY	The ID of the user who posted the question.
message	Text	NOT NULL	The content of the question.
status	Enum	DEFAULT 'Pending'	The current status (Pending, Escalated, Answered). Primary sort key.
created_at	DateTime	DEFAULT now()	The timestamp when the question was created. Secondary sort key.
answered_at	DateTime	NULLABLE	Timestamp for when the question was marked as answered.
created_by	Text	NOT NULL	The username of the creator.

Sources: backend/database.py:48-61