Technology Stack

Relevant source files

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

• README.md
• web/package.json
• backend/main.py
• backend/database.py
• web/src/context/WebSocketContext.js
• backend/api/questions.py
• backend/services/ai_service.py
• web/src/config/api.js

The qa-dashboard is a full-stack, real-time Q&A platform. Its architecture is composed of a modern web frontend, a high-performance Python backend, a relational database, and an integrated AI service for providing intelligent features. The technology choices emphasize real-time communication, scalability, and maintainability.

This document provides a detailed breakdown of the technology stack, covering the frontend, backend, database, and AI/ML components. It outlines the key frameworks, libraries, and architectural patterns used throughout the project.

Sources: README.md:3-5

High-Level Architecture

The system is divided into two main services: a web frontend and a backend API. The frontend is a Next.js application that communicates with the backend via REST API calls and a persistent WebSocket connection for real-time updates. The backend is a FastAPI application that handles business logic, interacts with a PostgreSQL database, and integrates with an AI service for generating answer suggestions.

The following diagram illustrates the overall system architecture.

Frontend

The frontend is a single-page application built with Next.js, a React framework. It is responsible for rendering the user interface, managing user authentication state, and communicating with the backend for data and real-time updates.

Sources: README.md:19-23, web/package.json:11

Key Frameworks and Libraries

Library/Framework	Version	Description
next	16.0.8	The React framework for server-rendered applications.
react	19.2.1	The core UI library for building components.
react-dom	19.2.1	Serves as the entry point to the DOM and server renderers for React.
tailwindcss	^4	A utility-first CSS framework for styling.
use-debounce	^10.0.6	A React hook to debounce input, used for checking duplicate questions.

Sources: web/package.json:10-18, web/src/components/QuestionForm.js:5

Real-time Communication

Real-time functionality is achieved using the browser's native WebSocket API. A WebSocketProvider is used to create a global context for managing the WebSocket connection state.

• Connection Management: The connect function in WebSocketContext.js establishes a connection to the backend's /questions/ws endpoint. It includes logic for automatic reconnection on disconnect.
• State Updates: The provider listens for messages like questions_list, question_created, and question_updated from the server and updates the shared questions state accordingly, which causes the UI to re-render in real-time.

The diagram below shows the sequence of establishing a connection and receiving updates.

Backend

The backend is built using FastAPI, a modern, high-performance Python web framework. It provides a RESTful API for standard CRUD operations and a WebSocket endpoint for real-time communication.

Sources: README.md:25-31, backend/main.py:40

Key Frameworks and Libraries

Library/Framework	Description
fastapi	The core web framework for building APIs.
uvicorn	The ASGI server used to run the FastAPI application.
sqlalchemy	The ORM used for all database interactions.
pydantic	Used for data validation and serialization through schemas.
python-jose	Handles JWT creation and validation for authentication.
passlib	Used for securely hashing and verifying passwords.
langchain-google-genai	Integrates with Google's Gemini models for AI features.

Sources: README.md:26-31, backend/services/ai_service.py:5

Application Entrypoint

The main application is defined in backend/main.py. It configures CORS middleware to allow requests from the frontend and includes the API routers for authentication, questions, and answers. It also uses a lifespan manager to initialize the database and create a default "Anonymous" user on startup.

# backend/main.py:40-62
app = FastAPI(
    title="Q&A Dashboard API",
    description="Real-time Q&A dashboard with WebSocket support",
    version="1.0.0",
    lifespan=lifespan,
)


app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000", "http://localhost:3001", "*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)


app.add_middleware(TrustedHostMiddleware, allowed_hosts=["localhost", "127.0.0.1"])

app.include_router(auth.router)
app.include_router(questions.router)
app.include_router(answers.router)

Sources: backend/main.py:40-62

Database

The application uses PostgreSQL as its relational database, managed via AWS RDS. SQLAlchemy serves as the Object-Relational Mapper (ORM) to define the database schema and interact with it from the Python backend.

Sources: README.md:20, 27, backend/database.py:12

Database Schema

The schema consists of three main tables: users, questions, and answers.

• users: Stores user information, including credentials and an is_admin flag.
• questions: Contains the question text, status, timestamps, and a foreign key to the user who asked it.
• answers: Contains the answer text and foreign keys to the parent question and the user who answered it.

The following ER diagram visualizes the relationships between these tables.

The Question model includes an enumeration for its status:

• PENDING
• ESCALATED
• ANSWERED

Sources: backend/database.py:22-26

AI & Machine Learning

The application leverages AI to provide two key features: suggesting answers to questions and checking for duplicate questions before they are posted. This is implemented in the AIService class.

Sources: README.md:15, 49-51, backend/services/ai_service.py

AI Service (ai_service.py)

The AIService singleton class integrates with a large language model (LLM) via the langchain-google-genai library, specifically targeting a Gemini model.

• Mock Mode: If the GOOGLE_API_KEY environment variable is not set, the service operates in a "mock mode," returning placeholder responses. This allows the application to function without a valid AI provider key.
• Answer Suggestion: The generate_suggested_answer method uses a PromptTemplate to ask the LLM for a concise answer to a given question. It also interacts with a semantic cache to avoid re-generating answers for similar questions.
• Duplicate Check: The check_duplicate method uses a vector store to perform a similarity search on new question text. If a sufficiently similar question is found, it returns the existing question and its answer.

The flow for generating a suggested answer is as follows: