High-Level Architecture

Relevant source files

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

• README.md
• backend/main.py
• backend/api/questions.py
• backend/database.py
• web/src/app/layout.js
• web/src/context/WebSocketContext.js
• web/src/config/api.js
• web/src/app/forum/page.js
• backend/schemas.py

The qa-dashboard is a real-time Question and Answer platform featuring a decoupled frontend and backend. The architecture is designed around a modern web stack, prioritizing real-time communication via WebSockets, a clear separation of concerns between the client and server, and an extensible structure for features like AI-powered suggestions.

The system is composed of a Next.js single-page application for the user interface and a Python-based FastAPI server that handles business logic, data persistence, and real-time event broadcasting. Communication between the two occurs over a RESTful API for standard operations and a WebSocket connection for live updates.

Sources: README.md

System Components

The application is logically divided into two primary services: a Frontend Web Application and a Backend API Server. They interact with a PostgreSQL database for data persistence.

This diagram shows the high-level interaction between the user's browser, the Next.js frontend, the FastAPI backend, and the PostgreSQL database.

Sources: README.md, backend/main.py, web/src/app/forum/page.js

Frontend Architecture

The frontend is a Next.js application responsible for rendering the user interface and managing client-side state. It is built with React and styled with Tailwind CSS.

Sources: web/README.md, web/package.json

Core Structure

The frontend code is organized into several key directories within web/src/:

• app/: Contains the page routes (e.g., /, /login, /forum) using the Next.js App Router. The root layout in app/layout.js wraps the entire application with context providers.
• components/: Holds reusable React components like QuestionCard, QuestionForm, and Header.
• context/: Manages global state. AuthContext handles user authentication and JWT tokens, while WebSocketContext manages the real-time connection.
• config/: Stores application configuration, such as API endpoint definitions in api.js.

Sources: README.md: Project Structure, web/src/app/layout.js, web/src/config/api.js

State and Data Management

Global state, particularly for authentication and real-time data, is handled via React's Context API.

• AuthProvider: Wraps the application to provide user and token information to all child components.
• WebSocketProvider: Establishes and maintains the WebSocket connection to the backend. It holds the questions array, which is updated in real-time based on messages received from the server.

// web/src/app/layout.js:19-25
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body className={`${geistSans.variable} ${geistMono.variable} antialiased`}>
        <AuthProvider>
          <WebSocketProvider>{children}</WebSocketProvider>
        </AuthProvider>
      </body>
    </html>
  );
}

Sources: web/src/app/layout.js:19-25

Real-Time Communication

The WebSocketContext is central to the real-time functionality. It connects to the backend's /questions/ws endpoint and listens for messages.

This sequence shows how the frontend connects to the WebSocket and receives both the initial list of questions and subsequent real-time updates.

The context handles specific message types like questions_list, question_created, and question_updated to manipulate the local questions state, which causes the UI to re-render automatically.

Sources: web/src/context/WebSocketContext.js:23-45, web/src/app/forum/page.js:14-23

Backend Architecture

The backend is a FastAPI application that serves a REST API and manages WebSocket connections. It uses SQLAlchemy as an ORM to interact with the PostgreSQL database.

Sources: README.md: Backend, backend/main.py

Core Structure

The backend application is initialized in backend/main.py. This file sets up the FastAPI app, configures CORS middleware, and includes API routers.

• main.py: The application entry point. It defines a lifespan manager to initialize the database and create a default user on startup. It also includes the API routers.
• api/: Contains the API endpoint definitions, separated by resource: auth.py, questions.py, and answers.py.
• database.py: Defines the SQLAlchemy database models (User, Question, Answer) and the database session management.
• schemas.py: Contains Pydantic models for data validation and serialization in API requests and responses.
• services/: Holds business logic decoupled from the API layer, such as the ai_service for generating suggestions.

Sources: backend/main.py:12-73, backend/api/questions.py, backend/database.py

API Endpoints

The backend exposes RESTful endpoints for managing users, questions, and answers, along with a WebSocket endpoint for real-time updates.

Method	Endpoint	Description
POST	/auth/register	Register a new user.
POST	/auth/login	Login and receive a JWT token.
POST	/questions	Create a new question.
GET	/questions	Get a list of all questions.
PATCH	/questions/{id}	Update a question's status (admin only).
GET	/questions/{id}/suggest-answer	Get an AI-generated answer suggestion.
POST	/answers/{question_id}	Post an answer to a specific question.
WS	/ws or /questions/ws	Establish a WebSocket connection.

Sources: README.md: API Endpoints, web/src/config/api.js:8-25, backend/api/questions.py, backend/api/answers.py

Real-Time Broadcasting

The backend uses a ConnectionManager utility to manage active WebSocket clients. When a significant event occurs (like creating or updating a question), the manager broadcasts a message to all connected clients.

# backend/api/questions.py
manager = ConnectionManager()

@router.post("", response_model=QuestionResponse)
async def create_question(...):
    # ... database logic to create question ...
    await manager.broadcast(
        {
            "type": "question_created",
            "data": jsonable_encoder(db_question),
        }
    )
    return db_question

@router.patch("/{question_id}", response_model=QuestionResponse)
async def update_question_status(...):
    # ... database logic to update question ...
    await manager.broadcast(
        {
            "type": "question_updated",
            "trigger": "question_status_updated",
            "data": jsonable_encoder(question),
        }
    )
    return question

This demonstrates how API endpoints trigger WebSocket broadcasts, ensuring all clients have a synchronized state.

Sources: backend/api/questions.py:23-24, 52-58, 143-151

Database Schema

The application uses a PostgreSQL database, managed via AWS RDS. The schema is defined using SQLAlchemy models and consists of three main tables: users, questions, and answers.

This Entity-Relationship diagram illustrates the relationships between the tables. A user can have multiple questions and answers. A question belongs to one user and can have multiple answers.

Sources: backend/database.py:29-81, README.md: Database Schema

Core Data Flow: Creating a Question

The following diagram illustrates the end-to-end flow when a user posts a new question.

This flow highlights the combination of a standard REST API call to create the resource, followed by a WebSocket broadcast to notify all clients (including the one that submitted the question) of the new data in real-time.

Sources: web/src/components/QuestionForm.js:63-85, backend/api/questions.py:27-58, web/src/context/WebSocketContext.js:35-39