Question Status Tracking

Relevant source files

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

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

The Question Status Tracking feature is a core component of the Q&A Dashboard, designed for moderation and organization. It allows administrators to manage the lifecycle of a question by assigning it a specific status. Each question can be marked as Pending, Escalated, or Answered, which affects its visibility, ordering, and presentation in the user interface.

This system is implemented across the full stack, from the database schema that stores the status, to the backend API that handles status updates, and finally to the frontend UI that displays the status and provides controls for administrators. Real-time updates are handled via WebSockets, ensuring all connected clients see status changes instantly.

Sources: README.md, backend/database.py, backend/api/questions.py, web/src/components/QuestionCard.js

Data Model and Statuses

The state of a question is persisted in the questions table in the database. The status column uses a string-based enumeration to constrain its possible values.

Sources: backend/database.py:28-31, backend/database.py:51

Question Status Enum

The QuestionStatus enum defines the three possible states for any question.

Status	Description
Pending	The default status for a newly created question. It is awaiting an answer or review.
Escalated	Marked by an admin to indicate high priority. These questions are sorted to the top of the list.
Answered	Marked by an admin when the question has been satisfactorily resolved. An answered_at timestamp is set.

Sources: backend/database.py:28-31, backend/api/questions.py:165-169

Database Schema

The Question model in the database includes the status field, which defaults to Pending upon creation.

This diagram shows the questions table with its status field and its relationship to the users table.

Sources: backend/database.py:44-60

Backend API for Status Updates

Administrators can change a question's status via a dedicated API endpoint. This action is restricted to admin users.

Sources: backend/api/questions.py:152-185

PATCH /questions/{question_id}

This endpoint is used to update the status of a specific question.

Parameter	Type	In	Description
question_id	string	Path	The UUID of the question to update.
update_data	object	Body	A JSON object containing the new status.

The request body is defined by the QuestionUpdate Pydantic schema.

# From backend/schemas.py
class QuestionUpdate(BaseModel):
    status: Optional[str] = None

Sources: backend/schemas.py:31-33, backend/api/questions.py:153-155

Status Update Flow

When an admin updates a question's status, the backend performs several actions:

1. Finds the question in the database.
2. Updates the status field.
3. If the new status is Answered, it sets the answered_at timestamp and triggers a webhook notification.
4. Broadcasts a question_updated event via WebSocket to all connected clients.
5. Returns the updated question object in the API response.

Sources: backend/api/questions.py:152-185

The following sequence diagram illustrates the process of an admin marking a question as "Answered".

Real-time Updates via WebSocket

Status changes are propagated to all clients in real-time using WebSockets. When a question's status is updated, the backend broadcasts a message that the frontend uses to update its state.

WebSocket Event: question_updated

When a status change occurs, the backend sends a JSON message with the type question_updated.

{
  "type": "question_updated",
  "trigger": "question_status_updated",
  "data": {
    "id": "...",
    "message": "...",
    "status": "Escalated",
    "created_at": "...",
    "answered_at": null,
    "created_by": "..."
  }
}

Sources: backend/api/questions.py:180-184

Frontend State Management

The WebSocketContext on the frontend listens for incoming WebSocket messages. When it receives a question_updated event, it finds the corresponding question in its local state array and updates it with the new data. This change automatically re-renders any components displaying that question, such as the QuestionCard.

// from web/src/context/WebSocketContext.js
} else if (message.type === 'question_updated') {
  setQuestions((prev) =>
    prev.map(q => q.id === message.data.id ? { ...q, ...message.data } : q)
  );
}

Sources: web/src/context/WebSocketContext.js:46-50

Frontend Implementation

The QuestionCard component is responsible for displaying a question's status and providing controls for admins to change it.

*Sources: web/src/components/QuestionCard.js

Status Display

The status is displayed as a colored badge and a left border on the card. The colors are determined by the status value.

• Pending: Yellow badge, blue border
• Escalated: Red badge, red border
• Answered: Green badge, green border

// from web/src/components/QuestionCard.js
const statusColors = {
  'Pending': 'bg-yellow-100 text-yellow-800',
  'Escalated': 'bg-red-100 text-red-800',
  'Answered': 'bg-green-100 text-green-800'
};

Sources: web/src/components/QuestionCard.js:12-16, web/src/components/QuestionCard.js:94-98, web/src/components/QuestionCard.js:102-104

Admin Controls

If the logged-in user is an admin (user.is_admin is true), a dropdown <select> element is rendered, allowing them to change the question's status. Selecting a new status triggers the handleStatusChange function.

// from web/src/components/QuestionCard.js
const handleStatusChange = async (newStatus) => {
  try {
    const response = await fetch(`${API_BASE_URL}${API_ENDPOINTS.UPDATE_QUESTION(question.id)}`, {
      method: 'PATCH',
      headers: getAuthHeaders(token),
      body: JSON.stringify({ status: newStatus })
    });
    // ...
  } catch (err) {
    // ...
  }
};

Sources: web/src/components/QuestionCard.js:77-88, web/src/components/QuestionCard.js:105-116

The following diagram shows the flow of an admin changing a question's status from the UI.

Question List Ordering

The question status directly influences the order in which questions are displayed. The backend API and WebSocket connection both provide an initial list of questions sorted with a specific priority: Escalated questions appear first, followed by Pending, and then Answered. Within these status groups, questions are sorted by their creation timestamp in descending order.

This logic is defined in the get_questions endpoint and the websocket_endpoint handler.

# from backend/api/questions.py
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())
)

Sources: backend/api/questions.py:81-87, backend/api/questions.py:129-139

Summary

The Question Status Tracking system is a vital feature for managing content on the platform. It provides clear visual cues about a question's state, empowers administrators with moderation tools, and uses a smart sorting algorithm to prioritize important content. The integration with WebSockets ensures a responsive and modern user experience where all participants have a synchronized view of the Q&A forum.