Project Structure
Relevant source files
The following files were used as context for generating this wiki page:This document provides a detailed overview of the architectural and directory structure of the QA-Dashboard project. The project is a monorepo containing two primary applications: a FastAPI backend and a Next.js frontend, designed to function as a real-time question and answer platform.
The architecture emphasizes a clear separation of concerns between the frontend client (web) and the backend server (backend). They communicate via a REST API for standard data operations and a WebSocket connection for real-time updates. This decoupled structure allows for independent development, deployment, and scaling of the two services.
High-Level Directory Structure
The repository is organized into two main directories, backend and web, each containing a self-contained application.
This diagram shows the top-level directories and some key files within them.
Sources: README.md:29-57
Key Directories
| Directory | Description |
|---|---|
backend/ | Contains the Python FastAPI application, which handles business logic, API endpoints, database interactions, and WebSocket communication. |
web/ | Contains the JavaScript Next.js application, which serves as the user interface for the platform. |
Sources: README.md:30, README.md:43
Backend (FastAPI)
The backend is a Python application built with the FastAPI framework. It exposes a REST API for CRUD operations and a WebSocket endpoint for real-time features.
Sources: README.md:19, backend/main.py:41-43
Backend File Structure
| File / Directory | Purpose |
|---|---|
main.py | The main entry point for the FastAPI application. It initializes the app, sets up middleware (CORS), and includes the API routers. It also creates a default "Anonymous" user on startup. |
database.py | Defines the SQLAlchemy database models (User, Question, Answer), the database engine, and the session management logic (get_db). |
api/ | A directory containing API routers, which group related endpoints. |
api/questions.py | Defines endpoints for creating, retrieving, and updating questions. It also contains the primary WebSocket endpoint (/ws). |
api/answers.py | Defines endpoints for creating, retrieving, and deleting answers. |
api/auth.py | Defines endpoints for user registration and login (/auth/register, /auth/login). |
schemas.py | Contains Pydantic models used for data validation, serialization, and defining API request/response bodies. |
settings.py | Manages application configuration and environment variables. (Note: File not provided, but referenced in database.py). |
Sources: README.md:31-42, backend/main.py:12-39, backend/database.py, backend/api/questions.py
Backend Request Flow
The following diagram illustrates how an incoming API request to create a question is handled by the backend.
This flow shows the request entering through main.py, being directed to the appropriate router, processed by the endpoint function, interacting with the database, broadcasting a WebSocket message, and finally returning a response.
Sources: backend/main.py:54, backend/api/questions.py:25-54
Frontend (Next.js)
The frontend is a React application built with the Next.js framework, using the App Router. It provides the user interface for interacting with the Q&A platform.
Sources: README.md:17, web/README.md:1
Frontend File Structure
| File / Directory | Purpose |
|---|---|
src/app/ | The core of the Next.js application, using file-system based routing. Each folder represents a URL segment. |
src/app/layout.js | The root layout for the entire application. It wraps all pages with global context providers like AuthProvider and WebSocketProvider. |
src/app/forum/page.js | The main page for the Q&A forum, responsible for displaying the question form and the list of questions. |
src/components/ | Contains reusable React components like QuestionCard, QuestionForm, and Header. |
src/context/ | Manages global state using React Context. AuthContext handles user authentication, and WebSocketContext manages the real-time connection. |
src/config/api.js | Centralizes API and WebSocket configuration, including base URLs and a list of all API endpoints. |
package.json | Defines project metadata and lists dependencies like next, react, and tailwindcss. |
Sources: README.md:44-57, web/src/app/layout.js:4, web/package.json:9-13
Frontend Component and Context Interaction
The forum page demonstrates how components and contexts work together to create a real-time experience.
The RootLayout wraps the application in the AuthProvider and WebSocketProvider. The ForumPage then uses the useAuth and useWebSocket hooks to access user data and the list of questions, which it passes down to child components like QuestionList.
Sources: web/src/app/layout.js:23-27, web/src/app/forum/page.js:8-9
Database Schema
The application uses a PostgreSQL database with three main tables: users, questions, and answers. The schema is defined using SQLAlchemy ORM classes.
Sources: README.md:21, backend/database.py:30-80
This ER diagram shows that a user can have multiple questions and answers. Each question can have multiple answers.
Sources: backend/database.py:30-80, README.md:118-148
Real-time Communication (WebSockets)
Real-time updates are managed through a WebSocket connection established between the frontend and backend.
WebSocket Connection and Data Flow
The following sequence diagram illustrates the process of connecting to the WebSocket and receiving real-time updates.
When the client connects, the server immediately sends the current list of all questions. When a new question is created via a standard REST API call, the server broadcasts a question_created event to all connected clients, which then update their state.
Sources: web/src/context/WebSocketContext.js:15-43, backend/api/questions.py:46-54, backend/api/questions.py:60-80
The WebSocketProvider on the frontend handles the connection lifecycle, including reconnection attempts, and updates a shared questions state that is consumed by the UI.
Sources: web/src/context/WebSocketContext.js:7-100