# queens-qmulus/qmulus architecture

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

- Interactive diagram: https://gitdiagram.com/queens-qmulus/qmulus
- Repository: https://github.com/queens-qmulus/qmulus

## Overview

##### Project Type and Purpose
- Qmulus is a public, open API that allows consumers to retrieve university data via HTTP GET requests. It is not a full-stack UI application but rather a backend API with documentation and testing suites.
- The README emphasizes its role as a public data API and points to online documentation (docs.qmulus.io) for further details.

##### Analyzing the File Structure
- The top-level directories and files indicate:
- API source code is contained in the “src” folder.
- Several datasets (buildings, courses, departments, news, sections, textbooks) are each implemented as separate modules under “src/api”.
- The “src/db” directory suggests a dedicated component for handling database interactions and ingestion records.
- Utility modules under “src/utils” extend functionality (e.g., token management, logging, validation).
- “docs” houses the static documentation assets including HTML, CSS, JavaScript, and locale files.
- The “bin” folder contains scripts for starting the application in development and production modes.
- GitHub workflows, testing under “test”, and additional tools indicate a structured CI/CD and testing approach.
- This structure hints at a modular, perhaps loosely coupled design with clear separation of concerns (routing, models, database, utilities).

a. Main Components:
- API Gateway / Entry Point: The central entry (src/index.js) receiving incoming HTTP requests.
- API Modules: Each dataset (buildings, courses, etc.) as separate components with their own routing, logic (model, routes).
- Database Layer: A separate module handling data persistence and ingestion (src/db and src/db/ingestRecord).
- Ingestion Module: A dedicated API (src/api/ingest) and associated DB ingestion logic that processes incoming records.
- Utility Components: Modules such as apiTokenManager, logger, requestSecretValidator, which support authentication, logging, and request validation.
- Documentation Service: The static “docs” folder that serves the API documentation website.
- DevOps/Deployment: Scripts in “bin” for starting the application, GitHub workflows for CI/CD, and ecosystem configuration files.
- Testing Suite: The structured “test” folder for unit and integration tests of API endpoints.
b. Relationships and Interactions:
- All external HTTP GET requests hit the API Gateway, which then routes requests to the appropriate API Module (e.g., courses, buildings).
- Each API Module uses its associated model and routes to process the request. Utility modules such as the token manager ensure that authentication or secret validation is properly conducted.
- Upon data requests, each API module interacts with the Database Layer which abstracts data retrieval and ingestion operations.
- The Ingestion Module facilitates data updates; it could be triggered separately from standard API calls.
- The Documentation Service is static but serves as an entry point for developers to understand the API endpoints.
- The entire system is supported by CI/CD automation (via GitHub workflows) and unit/integration tests ensuring reliability.
c. Architectural Patterns and Design Principles:
- Separation of Concerns: Modular division between API endpoints, database handling, utility functions, and external documentation.
- RESTful API Design: Endpoints follow a standard GET-request mechanism with clear URI patterns.
- Layered Architecture: Distinct layers for request handling, business logic, and data persistence.
d. Relevant Technologies:
- Node.js as the runtime.
- Possibly Express (or a similar framework) for API routing, although not explicitly named, the modular routing in “src/api” is consistent with frameworks like this.
- Standard JSON-based communication as indicated in the README examples.
- Tools for testing and deployment (e.g., GitHub workflows, npm scripts in “package.json”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["HTTP Client Request"]:::external
    Gateway["API Gateway (src/index.js)"]:::api

    subgraph "API Modules"
        Buildings["Buildings Module"]:::module
        Courses["Courses Module"]:::module
        Departments["Departments Module"]:::module
        News["News Module"]:::module
        Sections["Sections Module"]:::module
        Textbooks["Textbooks Module"]:::module
        IngestAPI["Ingestion API (src/api/ingest)"]:::module
    end

    subgraph "Database Layer"
        DB["Database (src/db)"]:::database
        DBIngest["DB Ingestion Logic (src/db/ingestRecord)"]:::database
    end

    Utilities["Utilities (src/utils)"]:::utility

    Documentation["Documentation Service (docs)"]:::external

    subgraph "DevOps & Testing"
        Deployment["Deployment Scripts (bin)"]:::devops
        CICD["CI/CD Workflows (.github/workflows)"]:::devops
        Testing["Testing Suite (test)"]:::testing
    end

    Client -->|"HTTP_GET"| Gateway
    Gateway -->|"RoutesTo"| Buildings
    Gateway -->|"RoutesTo"| Courses
    Gateway -->|"RoutesTo"| Departments
    Gateway -->|"RoutesTo"| News
    Gateway -->|"RoutesTo"| Sections
    Gateway -->|"RoutesTo"| Textbooks
    Gateway -->|"RoutesTo"| IngestAPI

    Buildings -->|"DataQuery"| DB
    Courses -->|"DataQuery"| DB
    Departments -->|"DataQuery"| DB
    News -->|"DataQuery"| DB
    Sections -->|"DataQuery"| DB
    Textbooks -->|"DataQuery"| DB

    IngestAPI -->|"IngestRequest"| DBIngest
    DBIngest -->|"Updates"| DB

    Buildings -->|"Uses"| Utilities
    Courses -->|"Uses"| Utilities
    Departments -->|"Uses"| Utilities
    News -->|"Uses"| Utilities
    Sections -->|"Uses"| Utilities
    Textbooks -->|"Uses"| Utilities
    IngestAPI -->|"Uses"| Utilities

    %% Click Events
    click Gateway "https://github.com/queens-qmulus/qmulus/blob/develop/src/index.js"
    click Buildings "https://github.com/queens-qmulus/qmulus/tree/develop/src/api/buildings"
    click Courses "https://github.com/queens-qmulus/qmulus/tree/develop/src/api/courses"
    click Departments "https://github.com/queens-qmulus/qmulus/tree/develop/src/api/departments"
    click News "https://github.com/queens-qmulus/qmulus/tree/develop/src/api/news"
    click Sections "https://github.com/queens-qmulus/qmulus/tree/develop/src/api/sections"
    click Textbooks "https://github.com/queens-qmulus/qmulus/tree/develop/src/api/textbooks"
    click IngestAPI "https://github.com/queens-qmulus/qmulus/tree/develop/src/api/ingest"
    click DB "https://github.com/queens-qmulus/qmulus/tree/develop/src/db"
    click DBIngest "https://github.com/queens-qmulus/qmulus/tree/develop/src/db/ingestRecord"
    click Utilities "https://github.com/queens-qmulus/qmulus/tree/develop/src/utils"
    click Documentation "https://github.com/queens-qmulus/qmulus/tree/develop/docs"
    click Deployment "https://github.com/queens-qmulus/qmulus/tree/develop/bin"
    click CICD "https://github.com/queens-qmulus/qmulus/tree/develop/.github/workflows"
    click Testing "https://github.com/queens-qmulus/qmulus/tree/develop/test"

    %% Styles
    classDef api fill:#bbdefb,stroke:#1e88e5,stroke-width:2px;
    classDef module fill:#c5e1a5,stroke:#7cb342,stroke-width:2px;
    classDef database fill:#ffe082,stroke:#fb8c00,stroke-width:2px;
    classDef utility fill:#f8bbd0,stroke:#c2185b,stroke-width:2px;
    classDef external fill:#fff9c4,stroke:#fbc02d,stroke-width:2px;
    classDef devops fill:#d1c4e9,stroke:#673ab7,stroke-width:2px;
    classDef testing fill:#b2dfdb,stroke:#00796b,stroke-width:2px;
```
