# duonghuuthanh/cs2301quizapp architecture

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

- Interactive diagram: https://gitdiagram.com/duonghuuthanh/cs2301quizapp
- Repository: https://github.com/duonghuuthanh/cs2301quizapp

## Overview

##### Project type and purpose
- This is a Java desktop application (JavaFX-based) for administering and practicing quizzes.
- It follows a layered MVC-style architecture with controllers for the UI, service classes for business logic, POJOs as data models, utilities for database connectivity, and FXML/CSS for the presentation.

##### File structure
- Top-level modules: QuizAppV1 and QuizAppV2 (two iterations of the same app).
- src/main/java/com/dht/quizappvX: entry point App.java and four controllers (PrimaryController, SecondaryController, QuestionsController, PracticeController).
- src/main/java/com/dht/services: service interfaces and implementations (CategoryServices, LevelServices, QuestionServices, plus decorators in V1).
- src/main/java/com/dht/pojo: data models (Category, Level, Question, Choice).
- src/main/java/com/dht/utils: helpers for alerts, stages, database connector (MyConnector/JdbcConnector), and theme management (Factory pattern).
- src/main/resources/com/dht/quizappvX: FXML views and CSS theme files.
- quizdb.sql at top level defines the relational schema.

##### (sparse) README
- Name: CS2301QuizApp – implies an academic project or sample.
- No further architectural notes—structure must be inferred from file tree.

a. Main components
1. Presentation Layer
– JavaFX FXML files (primary.fxml, secondary.fxml, questions.fxml, practice.fxml)
– Controllers (PrimaryController, SecondaryController, QuestionsController, PracticeController)
2. Business Logic Layer
– Service interfaces and implementations (CategoryServices, LevelServices, QuestionServices, decorators)
3. Data Access Layer
– JdbcConnector/MyConnector
– SQL schema (quizdb.sql)
4. Domain Model
– POJOs: Question, Choice, Category, Level
5. Themes Engine
– ThemeFactory + concrete factories (Dark, Light, Default)
– ThemeManager
6. External Resource
– SQLite/MySQL database (as defined by quizdb.sql)

b. Relationships and interactions
1. App.java initializes JavaFX and injects dependencies (ThemeManager, Services, Connectors).
2. Controllers receive user events from FXML views and call corresponding Services.
3. Services issue SQL queries via the JdbcConnector to the database.
4. Results are mapped into POJOs and returned to Controllers.
5. Controllers update the UI, possibly switching scenes via MyStage.
6. ThemeManager applies CSS themes at startup or on user request using Factory pattern.

c. Architectural patterns/design principles
- MVC separation: FXML + Controllers, Service layer, Domain models
- Factory pattern for theme selection
- Decorator pattern (V1) to extend QuestionServices with filtering (Keyword, Limit)
- Single responsibility: each package handles one concern (pojo, services, utils, themes)

d. Key technologies/frameworks
- Java 11+ (module-info.java present)
- JavaFX (FXML, CSS)
- JDBC (via custom connector)
- Maven build (pom.xml)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        App["App.java"]:::entry
        subgraph "FXML Views"
            direction TB
            PrimaryFXML["primary.fxml"]:::ui
            SecondaryFXML["secondary.fxml"]:::ui
            QuestionsFXML["questions.fxml"]:::ui
            PracticeFXML["practice.fxml"]:::ui
        end
        subgraph "Controllers"
            direction TB
            PrimaryCtrl["PrimaryController"]:::ui
            SecondaryCtrl["SecondaryController"]:::ui
            QuestionsCtrl["QuestionsController"]:::ui
            PracticeCtrl["PracticeController"]:::ui
        end
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        direction TB
        CategorySvc["CategoryServices"]:::service
        LevelSvc["LevelServices"]:::service
        QuestionSvc["QuestionServices"]:::service
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        direction TB
        JdbcConn["JdbcConnector"]:::data
        Configs["Configs"]:::data
    end

    %% Domain Model
    subgraph "Domain Model"
        direction TB
        CategoryModel["Category"]:::model
        LevelModel["Level"]:::model
        QuestionModel["Question"]:::model
        ChoiceModel["Choice"]:::model
    end

    %% Utility Layer
    subgraph "Utility Layer"
        direction TB
        MyAlert["MyAlert"]:::util
        MyStage["MyStage"]:::util
    end

    %% Theme Engine
    subgraph "Theme Engine"
        direction TB
        ThemeFactory["ThemeFactory"]:::util
        Theme["Theme"]:::util
        DarkFactory["DarkThemeFactory"]:::util
        LightFactory["LightThemeFactory"]:::util
        DefaultFactory["DefaultThemeFactory"]:::util
        ThemeManager["ThemeManager"]:::util
    end

    %% External Resource
    DB["Database (quizdb.sql)"]:::database

    %% Connections
    App --> PrimaryCtrl
    App --> SecondaryCtrl
    App --> QuestionsCtrl
    App --> PracticeCtrl
    App --> ThemeManager

    PrimaryFXML --> PrimaryCtrl
    SecondaryFXML --> SecondaryCtrl
    QuestionsFXML --> QuestionsCtrl
    PracticeFXML --> PracticeCtrl

    PrimaryCtrl --> CategorySvc
    PrimaryCtrl --> LevelSvc
    SecondaryCtrl --> QuestionSvc
    QuestionsCtrl --> QuestionSvc
    PracticeCtrl --> QuestionSvc

    PrimaryCtrl --> MyStage
    SecondaryCtrl --> MyStage
    QuestionsCtrl --> MyStage
    PracticeCtrl --> MyStage

    PrimaryCtrl --> MyAlert
    SecondaryCtrl --> MyAlert
    QuestionsCtrl --> MyAlert
    PracticeCtrl --> MyAlert

    PrimaryCtrl --> ThemeManager
    SecondaryCtrl --> ThemeManager
    QuestionsCtrl --> ThemeManager
    PracticeCtrl --> ThemeManager

    CategorySvc --> JdbcConn
    LevelSvc --> JdbcConn
    QuestionSvc --> JdbcConn

    JdbcConn --> DB
    Configs --> JdbcConn

    CategorySvc --> CategoryModel
    LevelSvc --> LevelModel
    QuestionSvc --> QuestionModel
    QuestionSvc --> ChoiceModel

    ThemeManager --> ThemeFactory
    ThemeFactory --> DarkFactory
    ThemeFactory --> LightFactory
    ThemeFactory --> DefaultFactory
    ThemeManager --> Theme

    %% Click Events
    click App "https://github.com/duonghuuthanh/cs2301quizapp/blob/main/QuizAppV2/src/main/java/com/dht/quizappv2/App.java"
    click PrimaryFXML "https://github.com/duonghuuthanh/cs2301quizapp/blob/main/QuizAppV2/src/main/resources/com/dht/quizappv2/primary.fxml"
    click SecondaryFXML "https://github.com/duonghuuthanh/cs2301quizapp/blob/main/QuizAppV2/src/main/resources/com/dht/quizappv2/secondary.fxml"
    click QuestionsFXML "https://github.com/duonghuuthanh/cs2301quizapp/blob/main/QuizAppV2/src/main/resources/com/dht/quizappv2/questions.fxml"
    click PracticeFXML "https://github.com/duonghuuthanh/cs2301quizapp/blob/main/QuizAppV2/src/main/resources/com/dht/quizappv2/practice.fxml"
    click PrimaryCtrl "https://github.com/duonghuuthanh/cs2301quizapp/blob/main/QuizAppV2/src/main/java/com/dht/quizappv2/PrimaryController.java"
    click SecondaryCtrl "https://github.com/duonghuuthanh/cs2301quizapp/blob/main/QuizAppV2/src/main/java/com/dht/quizappv2/SecondaryController.java"
    click QuestionsCtrl "https://github.com/duonghuuthanh/cs2301quizapp/blob/main/QuizAppV2/src/main/java/com/dht/quizappv2/QuestionsController.java"
    click PracticeCtrl "https://github.com/duonghuuthanh/cs2301quizapp/blob/main/QuizAppV2/src/main/java/com/dht/quizappv2/PracticeController.java"
    click CategorySvc "https://github.com/duonghuuthanh/cs2301quizapp/blob/main/QuizAppV2/src/main/java/com/dht/services/CategoryServices.java"
    click LevelSvc "https://github.com/duonghuuthanh/cs2301quizapp/blob/main/QuizAppV2/src/main/java/com/dht/services/LevelServices.java"
    click QuestionSvc "https://github.com/duonghuuthanh/cs2301quizapp/blob/main/QuizAppV2/src/main/java/com/dht/services/QuestionServices.java"
    click JdbcConn "https://github.com/duonghuuthanh/cs2301quizapp/blob/main/QuizAppV2/src/main/java/com/dht/utils/JdbcConnector.java"
    click Configs "https://github.com/duonghuuthanh/cs2301quizapp/blob/main/QuizAppV2/src/main/java/com/dht/utils/Configs.java"
    click CategoryModel "https://github.com/duonghuuthanh/cs2301quizapp/blob/main/QuizAppV2/src/main/java/com/dht/pojo/Category.java"
    click LevelModel "https://github.com/duonghuuthanh/cs2301quizapp/blob/main/QuizAppV2/src/main/java/com/dht/pojo/Level.java"
    click QuestionModel "https://github.com/duonghuuthanh/cs2301quizapp/blob/main/QuizAppV2/src/main/java/com/dht/pojo/Question.java"
    click ChoiceModel "https://github.com/duonghuuthanh/cs2301quizapp/blob/main/QuizAppV2/src/main/java/com/dht/pojo/Choice.java"
    click MyAlert "https://github.com/duonghuuthanh/cs2301quizapp/blob/main/QuizAppV2/src/main/java/com/dht/utils/MyAlert.java"
    click MyStage "https://github.com/duonghuuthanh/cs2301quizapp/blob/main/QuizAppV2/src/main/java/com/dht/utils/MyStage.java"
    click ThemeFactory "https://github.com/duonghuuthanh/cs2301quizapp/blob/main/QuizAppV2/src/main/java/com/dht/utils/themes/ThemeFactory.java"
    click Theme "https://github.com/duonghuuthanh/cs2301quizapp/blob/main/QuizAppV2/src/main/java/com/dht/utils/themes/Theme.java"
    click DarkFactory "https://github.com/duonghuuthanh/cs2301quizapp/blob/main/QuizAppV2/src/main/java/com/dht/utils/themes/DarkThemeFactory.java"
    click LightFactory "https://github.com/duonghuuthanh/cs2301quizapp/blob/main/QuizAppV2/src/main/java/com/dht/utils/themes/LightThemeFactory.java"
    click DefaultFactory "https://github.com/duonghuuthanh/cs2301quizapp/blob/main/QuizAppV2/src/main/java/com/dht/utils/themes/DefaultThemeFactory.java"
    click ThemeManager "https://github.com/duonghuuthanh/cs2301quizapp/blob/main/QuizAppV2/src/main/java/com/dht/utils/themes/ThemeManager.java"
    click DB "https://github.com/duonghuuthanh/cs2301quizapp/blob/main/quizdb.sql"

    %% Styles
    classDef ui fill:#bbdefb,stroke:#0d47a1,color:#0d47a1,stroke-width:1px
    classDef service fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20,stroke-width:1px
    classDef data fill:#ffe0b2,stroke:#e65100,color:#e65100,stroke-width:1px
    classDef model fill:#fff9c4,stroke:#f57f17,color:#f57f17,stroke-width:1px
    classDef util fill:#e1bee7,stroke:#4a148c,color:#4a148c,stroke-width:1px
    classDef database fill:#d7ccc8,stroke:#3e2723,color:#3e2723,stroke-width:1px
    classDef entry fill:#b3e5fc,stroke:#01579b,color:#01579b,stroke-width:1px
```
