# faaiz251/quizora architecture

> Architecture diagram of the GitHub repository faaiz251/quizora, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/faaiz251/quizora
- Repository: https://github.com/faaiz251/quizora

## Overview

##### Project Type and Purpose
- Quizora is a full-stack web application: a React-based single-page frontend (built with Vite) serving as the UI layer, and an Express.js/Node.js backend exposing REST APIs.
- Purpose: Provide AI-generated quizzes of varying difficulty, track user progress and virtual coins, and secure user authentication.

##### File Structure Analysis
- Top-level:
- backend/ – Express server with config, controllers, middleware, models, and route definitions.
- frontend/ – React app scaffolded by Vite, with Tailwind CSS, React Router, and Axios.
- Backend patterns:
- MVC-style separation: controllers (authController, etc.), models (User.js), routes (answerRoutes, questionRoutes, userRoutes), plus auth middleware.
- Configuration (gemini.js) for AI integration, dotenv for environment.
- Frontend patterns:
- Public vs src folders—static assets vs React code.
- Components (Navbar, pages folder), routing (React Router), private route guard.
- Styling with Tailwind (tailwind.config.js), build via Vite (vite.config.js).

##### README Insights
- Tech stack confirms MongoDB for persistence, Gemini API for dynamic question generation, CORS & dotenv for security & config.
- Features highlight authentication, quiz workflow, difficulty levels, coin accounting.

a. Main Components
1. Client (Browser) – React SPA
2. Frontend App – UI + Router + Axios
3. API Layer – Express.js server exposing /auth, /questions, /answers, /users
4. Business Logic
- Authentication service (JWT, password hashing)
- Quiz service (calls Gemini API)
- Coin management service
5. Data Layer – MongoDB (Users collection, QuizHistory, Coins)
6. External Service – Gemini AI API
7. Infrastructure – Hosting (e.g., AWS/GCP), Env & CORS config
b. Relationships & Data Flow
- User → React UI (login/register, quiz pages)
- React UI → Axios calls REST endpoints
- Express routes → corresponding controllers → business logic
- Quiz controller → Gemini API → returns questions → response to UI
- Answer controller → evaluates, updates coin balance in MongoDB
- User controller → CRUD operations on user profile
c. Architectural Patterns
- MVC pattern in backend
- SPA with client-side routing in frontend
- Layered architecture: Presentation → API → Service → Data
- External-service integration for AI
d. Key Technologies
- Frontend: React.js, Vite, Tailwind CSS, React Router, Axios
- Backend: Node.js, Express.js, Mongoose (MongoDB ODM), dotenv, CORS
- External: Gemini AI API

##### Essential Details to Capture
- User authentication lifecycle and middleware protection.
- API endpoints by functional area (auth, questions, answers, users).
- Flow of coin transactions tied to quiz outcomes.
- Dynamic vs static question data (AI-generated vs stored).
- Deployment concerns (environment variables, CORS policy).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Client Side" 
        direction TB
        Browser["User Browser"]:::user
        SPA["React SPA"]:::frontend
        Browser --> SPA
    end

    %% Frontend Application Structure
    subgraph "Frontend Application (Vite + React)" 
        direction TB
        Entry["main.jsx"]:::frontend
        App["App.jsx"]:::frontend
        Components["Navbar.jsx"]:::frontend
        Pages["Pages & Route Guards"]:::frontend
        ConfigFE["Vite & Tailwind Configs"]:::infra
        SPA --> Entry
        SPA --> App
        SPA --> Components
        SPA --> Pages
        SPA --> ConfigFE
    end

    %% Backend API
    subgraph "Backend API (Express.js)" 
        direction TB
        Server["Express Server"]:::backend
        Routes["REST API Routes"]:::api
        Controllers["Controllers"]:::service
        Middleware["Auth Middleware"]:::service
        ConfigBE["Gemini & Env Config"]:::infra
        Models["MongoDB Models"]:::database
        Server --> Routes
        Server --> Controllers
        Controllers --> Models
        Controllers --> Middleware
        Controllers --> ConfigBE
    end

    %% API Endpoints
    subgraph "API Endpoints" 
        direction TB
        AuthRoute["POST /auth/*"]:::api
        QRoute["GET /questions"]:::api
        ARoute["POST /answers"]:::api
        URoute["GET/PUT /users"]:::api
        Routes --> AuthRoute
        Routes --> QRoute
        Routes --> ARoute
        Routes --> URoute
    end

    %% External Services & Database
    subgraph "External & Data" 
        direction TB
        Gemini["Gemini AI API"]:::external
        MongoDB["MongoDB Cluster"]:::database
        QRoute --> Gemini
        Controllers --> MongoDB
    end

    %% Client to API Calls
    SPA -->|POST /auth/login| AuthRoute
    SPA -->|GET /questions?level=| QRoute
    SPA -->|POST /answers| ARoute
    SPA -->|GET /users/:id| URoute

    %% Click Events
    click SPA "https://github.com/faaiz251/quizora/tree/main/frontend/src"
    click Entry "https://github.com/faaiz251/quizora/blob/main/frontend/src/main.jsx"
    click App "https://github.com/faaiz251/quizora/blob/main/frontend/src/App.jsx"
    click Components "https://github.com/faaiz251/quizora/blob/main/frontend/src/components/Navbar.jsx"
    click Pages "https://github.com/faaiz251/quizora/blob/main/frontend/src/pages/Home.jsx"
    click Pages "https://github.com/faaiz251/quizora/blob/main/frontend/src/pages/Login.jsx"
    click Pages "https://github.com/faaiz251/quizora/blob/main/frontend/src/pages/Register.jsx"
    click Pages "https://github.com/faaiz251/quizora/blob/main/frontend/src/pages/Dashboard.jsx"
    click Pages "https://github.com/faaiz251/quizora/blob/main/frontend/src/pages/Quiz.jsx"
    click Pages "https://github.com/faaiz251/quizora/blob/main/frontend/src/pages/Learnmore.jsx"
    click Pages "https://github.com/faaiz251/quizora/blob/main/frontend/src/pages/PrivateRoute.jsx"
    click ConfigFE "https://github.com/faaiz251/quizora/blob/main/frontend/vite.config.js"
    click ConfigFE "https://github.com/faaiz251/quizora/blob/main/frontend/tailwind.config.js"
    click ConfigFE "https://github.com/faaiz251/quizora/blob/main/frontend/postcss.config.js"
    click Server "https://github.com/faaiz251/quizora/blob/main/backend/server.js"
    click AuthRoute "https://github.com/faaiz251/quizora/blob/main/backend/routes/auth.js"
    click QRoute "https://github.com/faaiz251/quizora/blob/main/backend/routes/questionRoutes.js"
    click ARoute "https://github.com/faaiz251/quizora/blob/main/backend/routes/answerRoutes.js"
    click URoute "https://github.com/faaiz251/quizora/blob/main/backend/routes/userRoutes.js"
    click Controllers "https://github.com/faaiz251/quizora/blob/main/backend/controllers/authController.js"
    click Middleware "https://github.com/faaiz251/quizora/blob/main/backend/middleware/authMiddleware.js"
    click ConfigBE "https://github.com/faaiz251/quizora/blob/main/backend/config/gemini.js"
    click Models "https://github.com/faaiz251/quizora/blob/main/backend/models/User.js"
    click ConfigBE "https://github.com/faaiz251/quizora/blob/main/backend/package.json"
    click ConfigBE "https://github.com/faaiz251/quizora/blob/main/backend/.gitignore"
    click ConfigFE "https://github.com/faaiz251/quizora/blob/main/frontend/package.json"
    click ConfigFE "https://github.com/faaiz251/quizora/blob/main/frontend/.gitignore"

    %% Styles
    classDef user fill:#D0E8FF,stroke:#357ABD,color:#000
    classDef frontend fill:#E8F4FF,stroke:#4A90E2,color:#000
    classDef api fill:#E8F1E1,stroke:#6DA34D,color:#000
    classDef backend fill:#E1F1E8,stroke:#3BA76D,color:#000
    classDef service fill:#F0F8FF,stroke:#5A9BD4,color:#000
    classDef database fill:#FFF1E0,stroke:#D97F00,color:#000
    classDef external fill:#F3E6FF,stroke:#8E44AD,color:#000
    classDef infra fill:#F5F5F5,stroke:#888888,color:#000
```
