Welcome to the QA Dashboard

Relevant source files

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

• README.md
• backend/main.py
• backend/database.py
• backend/api/questions.py
• backend/api/answers.py
• backend/services/ai_service.py
• web/src/app/forum/page.js
• web/src/context/WebSocketContext.js
• web/src/components/QuestionForm.js
• web/src/components/QuestionCard.js
• web/src/config/api.js

The QA Dashboard is a full-stack, real-time Question and Answer platform. It enables users to post questions, provide answers, and receive live updates without needing to refresh the page. The system is built with a modern tech stack, featuring a Next.js frontend and a FastAPI backend, with communication facilitated by WebSockets.

Key functionalities include secure user authentication with JWT, role-based permissions for regular users and administrators, and question status tracking (Pending, Escalated, Answered). The platform also integrates advanced features like AI-powered answer suggestions using Langchain and Google's Gemini model, real-time duplicate question detection, and webhook notifications for important events.

Sources: README.md:3-25

Architecture Overview

The application follows a decoupled client-server architecture, comprising a web frontend and a backend API.

• Frontend: A Next.js application responsible for rendering the user interface, managing user interactions, and handling client-side state. It communicates with the backend via REST API calls and a persistent WebSocket connection.
• Backend: A FastAPI application that serves the REST API, manages WebSocket connections, handles business logic, and interacts with the database.
• Database: A PostgreSQL database, managed via SQLAlchemy ORM, persists all user, question, and answer data.
• Real-time Layer: WebSockets provide a bidirectional communication channel for instant updates, such as new questions or status changes.
• AI Service: An integrated service using Langchain and a vector store for generating answer suggestions and detecting duplicate questions.

Sources: README.md:27-75

This diagram illustrates the high-level interaction between the system's main components.

Backend System

The backend is a Python application built with the FastAPI framework.

*Sources: README.md:37-43, backend/main.py

Application Entry Point

The main entry point is backend/main.py. It initializes the FastAPI application, configures CORS middleware to allow requests from the frontend, and includes the API routers for authentication, questions, and answers. A lifespan context manager handles database initialization (init_db()) on startup and ensures a default "Anonymous" user exists in the database.

Sources: backend/main.py:12-62

Database Schema

The application uses a PostgreSQL database with three primary tables: users, questions, and answers. The schema is defined using SQLAlchemy in backend/database.py.

Sources: backend/database.py:25-83, README.md:154-187

The diagram below shows the relationships between the database entities.

Table Definitions

Table	Column	Type	Constraints	Description
users	id	UUID	Primary Key	Unique identifier for the user.
	username	VARCHAR(255)	Unique, Not Null	User's chosen username.
	email	VARCHAR(255)	Unique, Not Null	User's email for login.
	password	VARCHAR(255)	Not Null	Hashed password.
	is_admin	BOOLEAN	Default: False	Flag for admin privileges.
questions	id	UUID	Primary Key	Unique identifier for the question.
	user_id	UUID	Foreign Key (users.id)	The user who posted the question.
	message	TEXT	Not Null	The content of the question.
	status	ENUM	Default: Pending	Can be 'Pending', 'Escalated', or 'Answered'.
answers	id	UUID	Primary Key	Unique identifier for the answer.
	question_id	UUID	Foreign Key (questions.id)	The question this answer belongs to.
	user_id	UUID	Foreign Key (users.id)	The user who posted the answer.
	message	TEXT	Not Null	The content of the answer.

Sources: backend/database.py:35-83, README.md:154-187

API Endpoints

The backend exposes several RESTful endpoints for managing application data. Endpoints are defined in web/src/config/api.js and implemented in backend/api/.

Method	Path	Description	Auth Required
POST	/auth/register	Register a new user.	No
POST	/auth/login	Log in and receive a JWT.	No
POST	/questions	Create a new question.	Yes
GET	/questions	Get a list of all questions.	No
PATCH	/questions/{id}	Update a question's status.	Yes (Admin)
GET	/questions/{id}/suggest-answer	Get an AI-generated answer suggestion.	Yes
POST	/answers/{question_id}	Post an answer to a question.	Yes
DELETE	/answers/{id}	Delete an answer.	Yes (Admin)
WS	/ws	Establish a WebSocket connection.	N/A

Sources: README.md:104-120, web/src/config/api.js:8-23, backend/api/questions.py, backend/api/answers.py

Frontend System

The frontend is a Next.js application that provides the user interface. It is structured with pages, components, and contexts for state management.

*Sources: README.md:31-35, web/README.md

Component Architecture

The main user-facing view is the ForumPage, which assembles several key components to create the Q&A interface.

This diagram shows the hierarchy of components on the forum page.

State Management

Global state, such as user authentication and WebSocket connections, is managed using React Context. The AuthProvider and WebSocketProvider wrap the entire application in the root layout, making this state available to all components.

Sources: web/src/app/layout.js:23-27, web/src/context/AuthContext.js, web/src/context/WebSocketContext.js

Real-Time Functionality (WebSockets)

The application's real-time capabilities are powered by WebSockets, enabling instant updates across all connected clients.

Connection and Event Flow

1. Connection: The frontend's WebSocketProvider connects to the backend's /questions/ws endpoint upon initialization.
2. Initial State: Upon connection, the backend sends a questions_list event containing all current questions.
3. Broadcasting: When a user performs an action (e.g., creates a question), the backend API endpoint processes the request, saves it to the database, and then uses a ConnectionManager to broadcast an event (question_created or question_updated) to all connected clients.
4. Client-side Update: The frontend's WebSocketProvider listens for these events, updates its internal state (questions), and React re-renders the affected components, such as the QuestionList.

Sources: web/src/context/WebSocketContext.js:18-50, backend/api/questions.py:23-24, 60-91

The following sequence diagram illustrates the flow when a user posts a new question.

Advanced Features

AI-Powered Suggestions

Users can request an AI-generated answer for any question.

• Flow: Clicking "Get AI Suggestion" in the QuestionCard component triggers a fetch request to the GET /questions/{id}/suggest-answer endpoint.
• Backend Logic: The backend's ai_service receives the request. It first checks a semantic cache for a similar, previously answered question. If no suitable match is found, it invokes the Gemini LLM via Langchain to generate a new answer.
• Mock Mode: If the GOOGLE_API_KEY is not configured, the AIService operates in a mock mode and returns a placeholder response.

Sources: web/src/components/QuestionCard.js:56-70, backend/api/questions.py:151-169, backend/services/ai_service.py:18-63

Duplicate Question Check

To prevent repeat questions, the QuestionForm component performs a real-time check as the user types.

• Flow: A useDebounce hook captures the text from the question input field. Once the user pauses typing, a fetch request is sent to the POST /questions/check-duplicate endpoint.
• Backend Logic: The ai_service uses a vector store to perform a similarity search on the input text against existing questions.
• UI Feedback: If the similarity score passes a certain threshold, the backend returns the similar question and its existing answer, which are then displayed as a warning to the user in the UI.

Sources: web/src/components/QuestionForm.js:17-50, 107-129, backend/api/questions.py:172-175, backend/services/ai_service.py:91-136

Conclusion

The QA Dashboard is a robust, full-stack application that effectively demonstrates the integration of a modern web framework (Next.js), a high-performance API (FastAPI), and real-time communication via WebSockets. Its architecture is modular and extensible, incorporating advanced features like AI-driven assistance and semantic caching to enhance the user experience. The clear separation of concerns between the frontend and backend, combined with a well-defined API and database schema, provides a solid foundation for future development and scaling.

Sources: README.md