{"id":28646826,"url":"https://github.com/tsohledev/quiz-webapp","last_synced_at":"2026-01-20T16:35:32.202Z","repository":{"id":293687672,"uuid":"984600364","full_name":"tsohleDev/quiz-webapp","owner":"tsohleDev","description":"A quiz web app for software engineers using vanilla html, css and javascript","archived":false,"fork":false,"pushed_at":"2025-05-19T07:52:18.000Z","size":417,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-13T02:07:32.972Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tsohleDev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-16T07:39:32.000Z","updated_at":"2025-05-19T07:52:23.000Z","dependencies_parsed_at":"2025-05-16T16:41:49.784Z","dependency_job_id":"dd42a462-c9b1-4a82-9d7a-06942b7ec308","html_url":"https://github.com/tsohleDev/quiz-webapp","commit_stats":null,"previous_names":["tsohledev/quiz-webapp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tsohleDev/quiz-webapp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsohleDev%2Fquiz-webapp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsohleDev%2Fquiz-webapp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsohleDev%2Fquiz-webapp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsohleDev%2Fquiz-webapp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tsohleDev","download_url":"https://codeload.github.com/tsohleDev/quiz-webapp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsohleDev%2Fquiz-webapp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265524858,"owners_count":23782049,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-13T02:07:31.558Z","updated_at":"2026-01-20T16:35:32.163Z","avatar_url":"https://github.com/tsohleDev.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# QUIZ WEB APP\n\n## Overview\n\nQuiz Web App is a simple, client-side web application that allows users to take quizzes on various topics. It stores user progress and scores using Firebase Firestore and identifies users (or more accurately, browser instances) using a custom cookie-based UID system. Initial quiz questions are populated from a local JSON file if not already present for a user in the database.\n\n## Tech Stack\n\n* **Frontend:** HTML, CSS, Vanilla JavaScript\n* **Backend (Database):** Firebase Firestore\n* **UID Management:** Custom JavaScript using browser cookies\n\n## Core Features\n\n* Dynamic loading of quiz questions based on categories.\n* Persistent UID for users/browsers via cookies.\n* Storage of initial quiz questions for users in Firestore.\n* Tracking and storage of user scores for different quiz categories.\n* Retrieval of a user's top score for a specific category.\n\n## Project Structure (Key Files)\n\n* `index.html` (or your main HTML file, e.g., `test_quiz_app_html`): The main entry point of the application.\n* `authentication.js`: Handles generation and retrieval of UIDs using browser cookies.\n    * `getCookie(name)`\n    * `setCookie(name, value, days)`\n    * `generateUUID()`\n    * `getUid()`\n* `database-client.js` (referred to as `database.js` in some contexts): Contains all the logic for interacting with Firebase Firestore.\n* `firebase-keys.js`: **(Important: Not in version control)** Stores your Firebase project configuration.\n* `init-data.json`: Contains the initial set of questions for different categories, loaded into Firestore if a user accesses a category for the first time.\n\n## Setup and Installation\n\n1.  **Clone the Repository:**\n    ```bash\n    git clone \u003cyour-repository-url\u003e\n    cd quiz-web-app\n    ```\n\n2.  **Firebase Setup:**\n    * This project uses Firebase Firestore as its backend database.\n    * You will need to create your own Firebase project at [https://console.firebase.google.com/](https://console.firebase.google.com/).\n    * Once your project is created, enable Firestore database.\n    * Go to your Firebase project settings and find your web app's Firebase configuration object.\n\n3.  **Create `firebase-keys.js`:**\n    * In the root of the project, create a file named `firebase-keys.js`.\n    * This file will contain your Firebase project's configuration details. It is **intentionally excluded from version control** (via `.gitignore`) because it contains sensitive information.\n    * Add your Firebase configuration to `firebase-keys.js` like this:\n        ```javascript\n        // firebase-keys.js - DO NOT COMMIT THIS FILE IF IT CONTAINS REAL KEYS\n        const firebaseConfig = {\n            apiKey: \"YOUR_ACTUAL_API_KEY\",\n            authDomain: \"YOUR_ACTUAL_AUTH_DOMAIN\",\n            projectId: \"YOUR_ACTUAL_PROJECT_ID\",\n            storageBucket: \"YOUR_ACTUAL_STORAGE_BUCKET\",\n            messagingSenderId: \"YOUR_ACTUAL_MESSAGING_SENDER_ID\",\n            appId: \"YOUR_ACTUAL_APP_ID\",\n            measurementId: \"YOUR_MEASUREMENT_ID\" // Optional\n        };\n        ```\n    * Replace the placeholder values with your actual Firebase project credentials.\n\n4.  **Firestore Indexes:**\n    * The application might require specific composite indexes in Firestore for certain queries (e.g., fetching top scores).\n    * If you encounter Firestore errors related to missing indexes, the error message in your browser's developer console will usually provide a direct link to create the required index in your Firebase console. Follow that link and create the index. For example, the `getUserTopScore` function requires an index on the `scores` collection for fields `uid` (Ascending), `category` (Ascending), and `score` (Descending).\n\n5.  **Open in Browser:**\n    * Open the main HTML file `index.html` in your web browser to run the application.\n\n## UID Management\n\nThis application uses a simple client-side UID generation and persistence mechanism:\n* When a user first visits, a UUID is generated using functions in `authentication.js`.\n* This UID is then stored in a browser cookie (e.g., `quizAppUserUID`) with a long expiry (e.g., 365 days).\n* On subsequent visits, the UID is retrieved from the cookie.\n* This UID is used to associate Firestore data (like fetched questions and scores) with a specific browser instance.\n\n**Note:** This cookie-based UID system is for simple browser identification and is **not a secure authentication system**. It does not verify user identity.\n\n## Core Database Functionality (`database-client.js`)\n\nThe `database-client.js` file manages all interactions with Firebase Firestore. Key functions include:\n\n* **`updateQuestions(uid, categoryKey, questions)`:**\n    * Updates (creates or overwrites) multiple question documents in Firestore for a specific `uid` and `categoryKey`.\n    * The questions are stored under the path `users/{uid}/{categoryKey}`.\n    * Uses a batch write for efficiency.\n\n* **`getQuestions(uid, categoryKey)`:**\n    * Retrieves questions for a given `uid` and `categoryKey` from Firestore.\n    * If no questions are found in Firestore for that user/category combination, it attempts to:\n        1.  Fetch initial questions for the `categoryKey` from the local `init-data.json` file.\n        2.  Use `updateQuestions()` to save these initial questions to Firestore under the user's path.\n        3.  Return the newly loaded questions.\n    * If questions already exist in Firestore, it returns them directly.\n\n* **`addScore(uid, score, category)`:**\n    * Adds a new score entry to a root `scores` collection in Firestore.\n    * Each score document includes the `uid`, `score`, `category`, and a server `timestamp`.\n\n* **`getUserTopScore(uid, category)`:**\n    * Retrieves the highest score for a given `uid` and `category` from the `scores` collection.\n    * Requires a composite index in Firestore to function correctly.\n\n## Future Improvements\n\n* **Secure Authentication:**  Replacing the custom cookie UID system with Firebase Authentication. This would provide actual user accounts, secure identity verification, and allow for more granular security rules in Firestore based on `request.auth.uid`.\n* **Error Handling \u0026 UI:** Enhance UI feedback for all operations and improve error display.\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsohledev%2Fquiz-webapp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftsohledev%2Fquiz-webapp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsohledev%2Fquiz-webapp/lists"}