Data Flow

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/QuestionForm.js
• backend/database.py
• web/src/context/WebSocketContext.js
• backend/api/answers.py
• web/src/config/api.js
• backend/services/ai_service.py

This document outlines the data flow within the QA-Dashboard application, detailing how information moves between the Next.js frontend, the FastAPI backend, and the PostgreSQL database. The system uses a combination of RESTful APIs for state-changing operations and WebSockets for real-time data synchronization across clients.

The primary data entities are User, Question, and Answer. The flow encompasses user authentication, question and answer creation, status updates, and AI-powered features like duplicate question detection and answer suggestions.

Data Models and Schemas

The application's data structure is defined at two main levels: the database persistence layer (SQLAlchemy) and the API interface layer (Pydantic).

Database Schema

The core entities are defined in backend/database.py using SQLAlchemy. The User, Question, and Answer tables form the relational backbone of the application.

The following diagram illustrates the relationships between these database tables.

API Data Schemas (Pydantic)

Pydantic models in backend/schemas.py are used for data validation, serialization, and documentation in the FastAPI endpoints. These schemas define the shape of data for API requests and responses.

QuestionResponse Schema

This model represents a question object sent from the backend to the frontend.

Field	Type	Description
id	string (UUID)	The unique identifier for the question.
message	string	The content of the question.
status	string	The current status (Pending, Escalated, Answered).
created_at	datetime	Timestamp of when the question was created.
answered_at	datetime (optional)	Timestamp of when the question was marked as answered.
created_by	string	The username of the user who created the question.

Sources: backend/schemas.py:38-49

DuplicateCheckResponse Schema

This model is used for the real-time duplicate question check feature.

Field	Type	Description
is_duplicate	boolean	True if a similar question is found.
similar_question	string (optional)	The text of the similar question found.
answer	string (optional)	The existing answer to the similar question, if available.
similarity_score	float	The calculated similarity score.

Sources: backend/schemas.py:91-96

Core Data Flow: Creating a Question

Creating a question is a primary user action that involves the frontend, backend API, database, a webhook notification, and a WebSocket broadcast to update all connected clients in real-time.

The sequence diagram below illustrates this entire process.

Real-time Data Synchronization via WebSockets

The application uses WebSockets to push real-time updates to all connected clients, ensuring the UI is always synchronized without needing to poll for changes.

Backend: WebSocket Connection and Broadcasting

1. A client connects to the /questions/ws endpoint.
2. The ConnectionManager on the backend accepts and stores the connection.
3. Upon connection, the server immediately sends a questions_list message containing all current questions, sorted by status and creation time.
4. When an event occurs (e.g., a new question is created or a status is updated), the backend API calls manager.broadcast() to send a message of type question_created or question_updated to all connected clients.

Sources: backend/api/questions.py:64-90, backend/api/questions.py:160-167

Frontend: Handling WebSocket Messages

The WebSocketProvider in the frontend manages the WebSocket lifecycle and state updates.

1. The connect function establishes a connection to the backend's WebSocket endpoint.
2. An onmessage event handler parses incoming JSON messages.
3. Based on the message type, it updates the shared questions state, which causes the React UI to re-render.

The following diagram shows how the client-side WebSocketContext handles incoming messages.

AI-Powered Data Flows

The application integrates an AI service for providing smart features, such as checking for duplicate questions and suggesting answers.

Duplicate Question Check

To prevent repeat questions, the QuestionForm component sends the user's input (after a debounce) to the backend to check for similarity against existing questions.

AI Answer Suggestion

Users can request an AI-generated answer for any question. This is handled by the ai_service on the backend, which can use a real LLM or a mock response.

1. A user clicks the "Get AI Suggestion" button in QuestionCard.js.
2. A GET request is sent to /questions/{id}/suggest-answer.
3. The backend suggest_answers endpoint invokes ai_service.generate_suggested_answer().
4. The AI service checks a semantic cache first. If no cached answer is found, it queries the LLM.
5. The generated suggestion is returned to the frontend and displayed.

Sources: web/src/components/QuestionCard.js:63-78, backend/api/questions.py:170-196, backend/services/ai_service.py:46-88