API Endpoints
Relevant source files
The following files were used as context for generating this wiki page:The QA Dashboard's backend is a FastAPI application that exposes a RESTful API for managing users, questions, and answers. It serves as the backbone for the Next.js frontend, handling all data persistence, business logic, and user authentication. The API is designed to be real-time, leveraging WebSockets to push updates to connected clients instantly.
The API is structured into logical modules using FastAPI's APIRouter. The main application in backend/main.py aggregates routers for authentication, questions, and answers. It also configures essential middleware for CORS and trusted hosts, making it ready for integration with a web client. Data validation is handled by Pydantic schemas, ensuring type safety and clear API contracts.
Application Setup and Core Endpoints
The main FastAPI application is instantiated in backend/main.py. This file is responsible for initializing the application, setting up middleware, and including the modular API routers.
Sources: backend/main.py
API Router Structure
The application's endpoints are organized into separate routers, which are then included in the main FastAPI app instance. This modular approach keeps the codebase clean and organized.
This diagram shows the main application including the routers for authentication, questions, and answers.
Sources: backend/main.py:66-68
Core Endpoints
The application defines two root-level endpoints for health checks and basic API information.
| Endpoint | Method | Description |
|---|---|---|
/health | GET | A health check endpoint that returns the application's status. |
/ | GET | The root endpoint providing basic API information and a link to the documentation. |
| Sources: backend/main.py:71-84 |
Authentication Endpoints (/auth)
Authentication is managed through JWT (JSON Web Tokens). These endpoints handle user registration and login.
Sources: backend/api/auth.py, backend/schemas.py:5-15, web/src/config/api.js:9-11
Endpoint Summary
| Endpoint | Method | Description | Authentication |
|---|---|---|---|
/auth/register | POST | Registers a new user. | None |
/auth/login | POST | Authenticates a user and returns a JWT access token. | None |
/auth/me | GET | Retrieves the profile of the currently authenticated user. | JWT Required |
User Login Flow
When a user logs in, they provide their credentials, and the server validates them. Upon success, a JWT is generated and returned to the client, along with user details. This token must be included in the Authorization header for subsequent requests to protected endpoints.
This diagram illustrates the sequence of events during a successful user login.
Sources: backend/api/auth.py:23-45
Question Endpoints (/questions)
These endpoints are the core of the Q&A platform, managing the lifecycle of questions, including creation, retrieval, status updates, and AI-powered interactions.
Sources: backend/api/questions.py, web/src/config/api.js:14-20
Endpoint Summary
| Endpoint | Method | Description | Authentication |
|---|---|---|---|
/questions | POST | Creates a new question. Broadcasts question_created via WebSocket. | JWT Required |
/questions | GET | Retrieves a list of all questions, sorted by status and timestamp. | None |
/questions/{id} | GET | Retrieves a specific question along with its answers. | None |
/questions/{id} | PATCH | Updates a question's status (e.g., 'Pending', 'Answered'). Admin only. | JWT Required (Admin) |
/questions/{id}/suggest-answer | GET | Generates an AI-powered answer suggestion for the question. | None |
/questions/check-duplicate | POST | Checks if a new question is a duplicate of an existing one. | None |
Question Creation Flow
Creating a question is an interactive process that involves database insertion, a webhook notification for admins, and a real-time broadcast to all connected clients via WebSockets.
This diagram shows the steps involved when a user posts a new question.
Sources: backend/api/questions.py:32-63, backend/utils/webhooks.py:31-34
Question Status Update
Admins can change the status of a question. If a question is marked as "Answered", a webhook notification is sent. In all cases, the status change is broadcast to all clients.
This flow chart details the logic for updating a question's status.
Sources: backend/api/questions.py:151-185
Question Sorting Logic
When fetching all questions, the API applies a specific sorting order to prioritize more urgent items. The order is:
- Status:
Escalated>Pending>Answered - Timestamp: Newest first (descending
created_at)
Sources: backend/api/questions.py:117-122
Answer Endpoints (/answers)
These endpoints handle the creation, retrieval, and deletion of answers associated with questions.
Sources: backend/api/answers.py, web/src/config/api.js:23-26
Endpoint Summary
| Endpoint | Method | Description | Authentication |
|---|---|---|---|
/answers/{question_id} | POST | Creates a new answer for a specific question. | JWT Required |
/answers/{question_id} | GET | Retrieves all answers for a specific question. | None |
/answers/{answer_id} | DELETE | Deletes a specific answer. | JWT Required (Admin) |
Answer Deletion
Only users with admin privileges can delete answers. The API checks the is_admin flag on the authenticated user's record before proceeding with the deletion.
Sources: backend/api/answers.py:65-69
WebSocket Endpoint (/ws)
The API provides a WebSocket endpoint for real-time communication between the server and clients, ensuring the UI is always up-to-date.
Sources: backend/api/questions.py:66-93, web/src/context/WebSocketContext.js
Connection and Event Flow
- A client connects to
WS /questions/ws. - Upon successful connection, the server immediately sends a
questions_listevent containing all current questions, sorted by priority. - The client then listens for subsequent events like
question_createdandquestion_updatedto incrementally update its state without needing to poll the API.
This diagram shows the WebSocket connection handshake and how real-time updates are pushed to clients.
Sources: backend/api/questions.py:66-93, web/src/context/WebSocketContext.js:25-46