# spongy01/question-paper-generator architecture

> Architecture diagram of the GitHub repository spongy01/question-paper-generator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/spongy01/question-paper-generator
- Repository: https://github.com/spongy01/question-paper-generator

## Overview

##### Project Type & Purpose
- This is a Node.js-based command-line application designed to generate custom question papers. It accepts user input for question paper parameters (via an interactive CLI or a JSON file) and uses a validation and generation pipeline to produce question papers. The project also supports reading questions from multiple JSON files specified in a configuration file.

##### File Structure
- The top-level directories include:
- Generator/ – Contains logic for question paper generation (questionGenerator.js and questionManager.js).
- IO_Module/ – Deals with input and output, handling file reading, requirement fetching, and writing the generated question paper.
- Validator/ – Handles the validation of the input requirements.
- data/ – Stores the question store JSON files.
- tests/ – Contains tests (using Jest) that verify the functionality of question generation and validation.
- docs/ – Contains generated documentation (including JSDoc outputs) and assets (fonts, scripts, styles).
- Configuration files like package.json, jsdoc.config.json, and utils.js centralize settings such as file paths for input data and output papers.
- The starting point is app.js, which drives the execution flow.

##### Architectural Components & Their Relationships
- “User Interface / Input Module”: Represents the input methods –
- Interactive CLI input or JSON file-based requirements (questionRequirements.json).
- “Validation Module” (Validator/validator.js): Receives the input requirements and validates them. It ensures that the required criteria (like marks distribution and difficulty percentages) are met.
- “Data Access Module”: Consists of:
- IO_Module/fileReader.js – Reads the question store from files listed in data_locations.json.
- IO_Module/requirementFetcher.js – Fetches user requirement.
- “Question Generation Module” (Generator/):
- questionGenerator.js takes validated requirements and applies generation logic (related to problems like subset-sum).
- questionManager.js coordinates the process.
- “Output Module”: (IO_Module/paperWriter.js) writes the generated paper into a JSON file in a designated output directory (configured in utils.js).
- “Configuration/Utils Module”: (utils.js) provides centralized configuration including paths and common settings.

##### Important Architectural Patterns & Design Principles
- Separation of Concerns: Each module (IO, Validator, Generator) is responsible for a distinct part of the pipeline.
- Modularity: Components are split into separate directories allowing independent development and possible future extension (e.g., adding more input methods or output formats).
- Configurable Behavior: Through utils.js and data_locations.json, the system’s behavior can be altered without modifying the business logic.
- Testing: The project includes a tests/ directory with Jest tests for critical modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Application Entry (app.js)"]:::entry
    B["User Input (Interactive CLI & JSON)"]:::input
    E["Requirement Fetcher (IO_Module/requirementFetcher.js)"]:::data
    C["Validation Module (Validator/validator.js)"]:::validator
    F["Question Generation Coordinator (Generator/questionManager.js)"]:::generator
    G["Question Generation Logic (Generator/questionGenerator.js)"]:::generator
    D["Data Access (File Reader) (IO_Module/fileReader.js)"]:::data
    H["Paper Writer Module (IO_Module/paperWriter.js)"]:::output
    subgraph "Configuration"
        I1["Utils (utils.js)"]:::config
        I2["Data Locations (data_locations.json)"]:::config
    end
    J["Test Suite (tests/)"]:::test

    A -->|"starts"| B
    B -->|"fetchesReq"| E
    E -->|"sendsReq"| C
    C -->|"validatedReq"| F
    F -->|"invokeLogic"| G
    G -->|"retrieveQuestions"| D
    F -->|"writeOutput"| H
    A -->|"initiateTests"| J

    %% Dashed arrows indicating usage of configuration
    B --- I1
    B --- I2
    C --- I1
    C --- I2
    F --- I1
    F --- I2
    H --- I1
    H --- I2

    click A "https://github.com/spongy01/question-paper-generator/blob/main/app.js"
    click B "https://github.com/spongy01/question-paper-generator/blob/main/questionRequirements.json"
    click C "https://github.com/spongy01/question-paper-generator/blob/main/Validator/validator.js"
    click E "https://github.com/spongy01/question-paper-generator/blob/main/IO_Module/requirementFetcher.js"
    click D "https://github.com/spongy01/question-paper-generator/blob/main/IO_Module/fileReader.js"
    click F "https://github.com/spongy01/question-paper-generator/blob/main/Generator/questionManager.js"
    click G "https://github.com/spongy01/question-paper-generator/blob/main/Generator/questionGenerator.js"
    click H "https://github.com/spongy01/question-paper-generator/blob/main/IO_Module/paperWriter.js"
    click I1 "https://github.com/spongy01/question-paper-generator/blob/main/utils.js"
    click I2 "https://github.com/spongy01/question-paper-generator/blob/main/data_locations.json"
    click J "https://github.com/spongy01/question-paper-generator/tree/main/tests/"

    classDef entry fill:#FFA500,stroke:#333,stroke-width:2px;
    classDef input fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef validator fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef data fill:#FFFF99,stroke:#333,stroke-width:2px;
    classDef generator fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef output fill:#AFEEEE,stroke:#333,stroke-width:2px;
    classDef config fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef test fill:#D3D3D3,stroke:#333,stroke-width:2px;
```
