# apo5698/helli-grading architecture

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

- Interactive diagram: https://gitdiagram.com/apo5698/helli-grading
- Repository: https://github.com/apo5698/helli-grading

## Overview

##### Main Components
- Web Frontend: This is built with Rails views (ERB and Slim templates) and enhanced by modern JavaScript components (found in app/javascript). The existence of separate folders for “grading” (both v1 and v2) and other interactive components (forms, templates, etc.) indicates a rich, dynamic UI.
- API Layer: Under app/controllers/api, a dedicated set of controllers (for assignments, grade items, dependencies, etc.) reveals RESTful endpoints. This layer is likely used for communicating with the client-side JavaScript or external services.
- Backend (Rails MVC Core): The standard Rails folders (models, controllers, views, mailers) manage business logic. Models represent entities such as Assignment, Course, Participant, Submission, Rubric, and others that underpin the auto-grading logic.
- Background Tasks & Job Handling: Although not explicitly in a dedicated background jobs directory, files like Procfile and Rakefile along with specific tasks in .rake files and the Rails/config initializers signal that asynchronous job processing might be in play.
- Supporting Infrastructure: Configuration management (config/ directory with multiple initializer files, environment configurations, and webpack files), database migration scripts under db/migrate, and testing frameworks (RSpec, Cucumber) that ensure robustness.

##### Relationships and Interactions
- The browser client (UI) interacts with the Rails controllers via HTTP/HTTPS, submitting forms (e.g., assignment uploads, grading requests) and receiving rendered views or JSON responses.
- The API endpoints provide a layer through which the frontend and external services can interact with core resources (assignments, courses, submissions).
- The controllers interact with models for business logic execution, such as processing an assignment submission, calculating grades based on defined rubrics, or generating file outputs using the “helli” utility libraries.
- There is a clear MVC separation where models encapsulate data (courses, users, submissions), controllers handle incoming requests, and views render the results.
- Additional libraries (e.g., those related to Java (jdk.rb), open3t.rb, and those inside app/lib/helli) perform specialized tasks like code compilation, execution, and output verification which are central to the auto-grading functionality.

##### Architectural Patterns and Design Principles
- The application uses the standard MVC pattern provided by Rails.
- A modular design is evident, as the project splits functionalities between core assignment/course management and grading-specific logic.
- There’s a separation of concerns between UI (client-side components), API endpoints (dedicated controllers under app/controllers/api), and background/utility functions (residing in lib and specialized subdirectories).

##### Technologies and Frameworks
- Ruby on Rails (core framework) handling the MVC pattern.
- Webpacker for managing JavaScript bundles and components.
- RSpec and Cucumber for testing, which implies that tests are part of the overall architecture to ensure components interact correctly.
- Additional libraries for auto-grading tasks such as JDK integrations (app/lib/jdk.rb) and utilities for CSV handling and logging.
- ActionCable (under app/channels) suggests real-time features may be present for live updates or notifications.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        A["Browser/Client (UI)"]:::client
        B["Rails Views"]:::frontend
        C["JavaScript Components"]:::frontend
    end

    %% Rails Application Server
    subgraph "Rails Application Server"
        D["Web Controllers"]:::backend
        E["API Controllers"]:::backend
        F["Models"]:::backend
        G["Grading Models"]:::backend
        H["Utility Libraries (Helli)"]:::utility
        I["JDK Integration"]:::utility
    end

    %% Supporting Infrastructure
    subgraph "Supporting Infrastructure"
        J["Database"]:::db
        K["Background Tasks & Job Handling"]:::tasks
        L["Configuration & Environment"]:::infra
        M["Real-Time Communication"]:::infra
        N["Testing Infrastructure"]:::infra
    end

    %% Background Files
    subgraph "Background Files"
        O["Procfile"]:::tasks
        P["Procfile.dev"]:::tasks
        Q["Procfile.dev-hmr"]:::tasks
        R["Rakefile"]:::tasks
        S["Rake Tasks"]:::tasks
    end

    %% Database Files
    subgraph "Database Files"
        T["Migrations"]:::db
        U["Schema"]:::db
    end

    %% Data Flow Connections
    A -->|"sends_request"| D
    A -->|"API_call"| E

    D -->|"renders"| B
    E -->|"returns_JSON"| A

    D -->|"invokes_grading"| G
    D -->|"calls_utilities"| H
    D -->|"calls_JDK"| I

    G -->|"updates"| F
    H -->|"updates"| F
    I -->|"updates"| F

    F -->|"persists_data"| J
    E -->|"accesses"| F

    L --> D
    L --> E
    L --> F

    D -->|"triggers_jobs"| K
    M --> D

    J --> T
    J --> U

    K --> O
    K --> P
    K --> Q
    K --> R
    K --> S

    %% Class Definitions for Colors
    classDef client fill:#ccf,stroke:#333,stroke-width:2px;
    classDef frontend fill:#f9f,stroke:#333,stroke-width:2px;
    classDef backend fill:#9f9,stroke:#333,stroke-width:2px;
    classDef utility fill:#ff9,stroke:#333,stroke-width:2px;
    classDef tasks fill:#fc9,stroke:#333,stroke-width:2px;
    classDef infra fill:#9cf,stroke:#333,stroke-width:2px;
    classDef db fill:#cfc,stroke:#333,stroke-width:2px;

    %% Click Events
    click B "https://github.com/apo5698/helli-grading/tree/master/app/views"
    click C "https://github.com/apo5698/helli-grading/tree/master/app/javascript"
    click E "https://github.com/apo5698/helli-grading/tree/master/app/controllers/api"
    click D "https://github.com/apo5698/helli-grading/tree/master/app/controllers"
    click F "https://github.com/apo5698/helli-grading/tree/master/app/models"
    click G "https://github.com/apo5698/helli-grading/tree/master/app/models/rubrics"
    click H "https://github.com/apo5698/helli-grading/tree/master/app/lib/helli"
    click I "https://github.com/apo5698/helli-grading/blob/master/app/lib/jdk.rb"
    click O "https://github.com/apo5698/helli-grading/tree/master/Procfile"
    click P "https://github.com/apo5698/helli-grading/blob/master/Procfile.dev"
    click Q "https://github.com/apo5698/helli-grading/blob/master/Procfile.dev-hmr"
    click R "https://github.com/apo5698/helli-grading/tree/master/Rakefile"
    click S "https://github.com/apo5698/helli-grading/tree/master/lib/tasks"
    click L "https://github.com/apo5698/helli-grading/tree/master/config/"
    click T "https://github.com/apo5698/helli-grading/tree/master/db/migrate"
    click U "https://github.com/apo5698/helli-grading/blob/master/db/schema.rb"
```
