wichat_es6a

A web application accessible from any browser.

User registration and authentication.

Automatic question generation based on Wikidata.

The ability to obtain hints generated by a language model (LLM) via an API.

Validation and mitigation of incorrect responses from the language model.

Time control for answering each question.

A documented API for accessing questions and user data.

Automatic generation of correct and incorrect answers (distractors).

Web Technology: The application must be developed using modern web technologies (React.js for the frontend and Node.js/Python for the backend).

Database: PostgreSQL or MongoDB will be used for data storage.

Language Model: A language model (LLM) will be integrated through an external API.

Question Source: Questions must be automatically generated based on Wikidata data.

Response Time: Answers to questions must be recorded within a set time limit.

Delivery Deadlines: The application must be operational before the project closure as agreed.

Documentation: The architecture and development must be documented following the arc42 standard.

Open Source: The source code must be hosted in an accessible repository for review and tracking.

Data Management: User data must be protected in compliance with data protection regulations.

Response Validation: Potential errors or "hallucinations" from the language model must be mitigated to prevent incorrect information in hints.

Adopting a Kanban-style project management: The team employs a Kanban approach to organize and visualize the software development process. Tasks are represented on a Kanban board, facilitating prioritization and fostering team-wide transparency. This methodology enhances focus by limiting work in progress (WIP), promoting continuous delivery and helping the team identify process bottlenecks early.

Using GitHub Flow as the development workflow: GitHub Flow is adopted to ensure a clear and collaborative development process. It encourages the use of short-lived feature branches and enforces Pull Request-based code reviews. This ensures that every change is peer-reviewed before integration, increasing stability and maintaining consistent code quality.

Continuous Integration with GitHub Actions and SonarQube: A CI pipeline is implemented using GitHub Actions to automatically run tests and code quality checks on every push. SonarQube is integrated to analyze code for bugs, vulnerabilities, code smells, and duplications. These tools provide immediate feedback, ensuring issues are addressed before deployment and reinforcing best practices.

Starting the project from scratch with custom configuration: While a reference project exists, the development team opted to build the system from the ground up. This decision fosters a deeper understanding of the architecture, eliminates dependencies on legacy code, and enables customization aligned with current needs. The prior implementation serves strictly as a conceptual guide.

Using MongoDB as the database: MongoDB, a document-oriented NoSQL database, was selected for its flexibility, scalability, and alignment with the application’s data model. Its familiarity within the team and prior successful usage further reinforce this choice.

Using Gemini LLM for response generation: After testing several large language models, Gemini was selected due to its superior performance in generating relevant and context-aware responses to user prompts. Its integration facilitates intelligent, adaptive behavior in the application’s core logic.

Using JavaScript as the primary programming language: JavaScript is chosen for its ubiquity in web development, extensive ecosystem, and strong support for full-stack development via Node.js. The team’s familiarity with the language ensures faster development cycles and reduces onboarding time.

Using Node.js as the backend environment: Node.js is used to build the server-side logic due to its asynchronous event-driven architecture and seamless integration with JavaScript. It is well-suited for handling concurrent requests in real-time applications such as quizzes.

Using Material UI as the UI framework: Material UI accelerates front-end development by offering a comprehensive set of customizable, accessible components. It ensures visual consistency while reducing the amount of custom styling and layout logic needed.

Using Docker for service deployment: Docker is employed to containerize application components, enabling environment consistency, isolated testing, easier scaling, and streamlined deployment pipelines.

Using Azure as the cloud platform: Microsoft Azure is selected for its robust cloud services, seamless DevOps integration, enterprise-level security, and global infrastructure. Azure’s CI/CD support and monitoring tools align well with the project’s operational requirements.

Using a Linux-based server environment: Linux is chosen for hosting the application due to its reliability, performance efficiency, and compatibility with modern development and automation tools.

Separation of game logic and UI components: To ensure maintainability and testability, core game functionality (e.g., score tracking, validation logic, question selection) is decoupled from presentation components. This separation enforces single responsibility and supports future extensibility.

Using setInterval to manage game timers: Timed gameplay requires precise countdown control. The use of setInterval with timestamp drift correction enables consistent and reliable timer behavior, even under varying load conditions.

Anonymous play support (no login required): Users can access and play quizzes without authentication. However, to preserve data integrity, only authenticated users have access to statistics, history, and profile management. This improves accessibility without compromising personalization for logged-in users.

User profile editing and password update: Authenticated users are allowed to manage personal details and change their passwords through secure interfaces. Proper validation and feedback mechanisms are integrated to ensure usability and security.

Using bcrypt to protect user passwords: All stored passwords are hashed using bcrypt, which provides built-in salting and adaptive hashing to resist brute-force and rainbow table attacks. This aligns with industry best practices for secure authentication.

Game modes based on thematic categories: To enhance user engagement, the application supports multiple quiz modes including Countries, Music, Cinema, and Mixed Mode. This allows users to tailor their experience based on personal interests.

Daily question generation via cron + Wikidata: An automated cron job fetches and generates new quiz questions daily from Wikidata. This ensures the application remains dynamic, up-to-date, and free from manual content entry requirements.

Using Swagger for API documentation: Swagger (OpenAPI) is integrated to document all API endpoints interactively. Developers can view, test, and understand the API via a visual interface, which streamlines both internal development and third-party integration efforts.

Using GitHub Flow and Pull Requests for code review: Pull Requests are enforced across all feature and bug-fix branches. Each submission is subject to peer review, ensuring that standards are met, potential defects are caught early, and collaboration remains transparent.

Using Jest for unit testing: Jest is used to test application logic at the unit level. It offers fast test execution, easy mocking, and snapshot testing, making it well-suited for JavaScript-based projects.

Using jest-cucumber for BDD-style testing: Test scenarios are written in Gherkin syntax using jest-cucumber, improving test readability and enabling non-developers to participate in test definition. This supports behavior-driven development (BDD) and improves communication across technical and business stakeholders.

Using pepeter for React component testing: Pepeter is used to create expressive, readable tests for React components. It simplifies interaction simulation and state validation, allowing for deeper and more maintainable component-level testing.

Using Cypress for end-to-end testing: Cypress is adopted for testing complete user flows, such as answering questions, submitting results, and navigating through different parts of the application. This ensures high confidence in the stability of the application post-deployment.

Using Ruby for documentation deployment: Ruby is selected as the documentation deployment environment based on tooling compatibility. Existing scripts and setup guides are designed for Ruby, minimizing setup overhead and ensuring smooth integration with the documentation pipeline.

Modular and testable code structure: The codebase is designed following modular principles, where each component or module fulfills a single, well-defined responsibility. This approach promotes testability, simplifies debugging, and improves long-term maintainability.

Usable Interface:

Immediate Feedback: The user will instantly see whether their answer was correct or not. Additionally, the game history, rankings, and generated questions will always be up to date.

Secure Access Control: User authentication security will be enforced by verifying the correctness of the entered credentials and denying access otherwise.

Persistence: Both user data and game records will be stored to ensure their integrity and availability.

Maintainability: The code is written clearly and legibly, following a modular approach to facilitate maintenance when fixing bugs or adding improvements.

Extensibility: The application is built in a way that allows new functionalities to be added easily in the future without significantly affecting existing components.

Implementation: The application will be developed using JavaScript. The front-end will be built with React, while Node.js and microservices architecture will be used for the back-end. MongoDB will be used for managing the NoSQL database.

Testing: Various tests will be conducted to ensure a high-quality product.

Layers: A three-layer architecture will be implemented to ensure better organization and modularity:

AuthService: Handles user authentication and token management.

UserService: Manages user profiles, roles, and preferences.

QuestionService: Stores and retrieves generated quiz questions.

LLMService: Coordinates AI-based content generation (e.g., questions and hints).

WikidataService: Provides trivia data retrieved from structured knowledge sources.

Routing requests to the appropriate internal services.

Centralizing authentication, authorization, and input validation.

Abstracting internal service structure from external consumers.

When a new game starts, the system first attempts to load questions from the database.

If no suitable cached questions are found, it generates a batch of questions on the fly using the LLM and Wikidata services.

These questions are then saved to the database for reuse in future games.

JavaScript

Node.js

React

MongoDB

Docker

Grafana and Prometheus

Gemini

Wikidata

GitHub Actions

SonarQube