Architecture

• 1: Overview
• 2: Components
• 3: Configuration

1 - Overview

Divekit is a tool that helps instructors to create and distribute repositories to students.

High-Level Overview

graph TB
    INST((Instructors))
    ORIGIN[Origin Repository]
    CLI[Divekit CLI]
    DIST[Distribution]
    REPOSTUDENT[Student Repositories]
    REPOTEST[Test Repositories]
    STUDENTS((Students))
    TPAGE[Test Pages]

    INST -->|Develop| ORIGIN
    INST -->|Use| CLI
    ORIGIN -->|Input| CLI
    CLI -->|Generate| DIST
    DIST --- REPOTEST
    DIST --- REPOSTUDENT
    STUDENTS -->|Work on| REPOSTUDENT
    TPAGE -->|Get feedback| STUDENTS
    REPOSTUDENT --->|Update| REPOTEST
    REPOTEST --->|Update| TPAGE

    style CLI fill:#42b050,stroke:#333
    style ORIGIN fill:#fcf,stroke:#333
    style DIST fill:#a3e87e,stroke:#333
    style INST fill:#ff9,stroke:#333
    style STUDENTS fill:#ff9,stroke:#333
    style REPOSTUDENT fill:#6fc5ff,stroke:#333
    style REPOTEST fill:#6fc5ff,stroke:#333

Component Details

Divekit CLI

The CLI serves as the central interface for instructors. It controls the entire process of task distribution and management. All necessary commands for creating, distributing, and managing repositories are executed through the CLI.

Origin Repository

The Origin Repository contains the initial version of assignments and tests. It serves as a master template from which individualized versions for students are generated. This is where the original assignments, code scaffolds, and test cases are maintained.

Distribution

A Distribution is the result of the distribution process and consists of two main components:

Student Repositories

Individualized repositories for each student or group, containing:

• Personalized assignments
• Adapted code scaffolds
• Specific resources

Test Repositories

Separate repositories containing test cases and evaluation criteria:

• Automated tests
• Assessment metrics
• Feedback mechanisms

Test Page

A page where students can get feedback on their work.

Students

Students are the users who are working on the repositories. They can be individuals or groups.

Instructor

Instructor is the user who is creating the repositories and distributing them to the students.

2 - Components

This document describes the core components of Divekit and how they interact.

Components Overview

graph TB
    subgraph interfaces
        CLI[CLI Interface]
        WebUI[Web Interface]
    end
    style WebUI stroke-dasharray: 5 5

    subgraph core[Modules]
        ModuleEntry((   ))
        style ModuleEntry fill:none,stroke:none
        
        Config[Configuration Manager]
        GitAdapter[GitLab Adapter]
        Indiv[Individualization]
        Pass[Passchecker]
        Plag[Plagiarism Checker]
        User[Usermanagement]
    end
    
    CLI --> ModuleEntry
    WebUI -.-> ModuleEntry
    
    Pass --> GitAdapter
    Plag --> GitAdapter
    User --> GitAdapter
    GitAdapter --> GitLab[GitLab API]

Interfaces

• CLI Interface: Central command-line interface for all user interactions
• Web Interface (planned): Alternative user interface that uses the same modules as the CLI

Modules

• Configuration Manager: Manages all configuration files and user settings
• GitLab Adapter: Central component for all GitLab interactions
• 🚧 Individualization: Handles the individualization of tasks
• 🚧 Passchecker: Checks submissions and communicates with GitLab
• 🚧 Plagiarism Checker: Detects possible plagiarism and interacts with GitLab
• 🚧 Usermanagement: Manages users and their permissions through GitLab

3 - Configuration

Divekit uses a hierarchical configuration system with both global and project-specific settings.

Configuration Levels

Divekit uses a multi-level configuration system based on the frequency of changes:

[0] Installation

Configurations that are set once during DiveKit installation and rarely changed afterwards. These contain global defaults and environment settings.

~
└── .divekit/
    ├── .env                  # Environment variables
    ├── hosts.json            # Hosts configuration
    ├── members               # Members configuration
    │   ├── 2025-01-21_12-28-15_pear_members.json
    │   ├── 2025-01-27_12-29-00_raspberry_members.json
    │   └── 2025-01-27_12-40-02_sandwich_members.json
    ├── origin.json           # Origin configuration
    └── variation             # Variation configuration (not finalized)
        ├── relations.json    # Relations configuration
        ├── variableExtensions.json # Variable extensions configuration
        └── variations.json     # Variations configuration

Environment Configuration

~/.divekit/.env:

API_TOKEN=YOUR_ACCESS_TOKEN
DEFAULT_BRANCH=main

Remotes

Default: ~/.divekit/hosts.json:

{
    "version": "1.0",
    "hosts": {
        "default": {
            "host": "https://gitlab.git.nrw/",
            "token": "DIVEKIT_API_TOKEN"
        }
    }
}

Example: ~/.divekit/hosts.json:

{
    "version": "1.0",
    "hosts": {
        "default": {
            "host": "https://gitlab.git.nrw/",
            "tokenAt": "DIVEKIT_API_TOKEN"
        },
        "archilab": {
            "host": "https://gitlab.archi-lab.io/",
            "tokenAt": "DIVEKIT_API_TOKEN_ARCHILAB"
        },
        "gitlab": {
            "host": "https://gitlab.com/",
            "tokenAt": "DIVEKIT_API_TOKEN_GITLABCOM"
        }
    }
}

[1] Semester

Configurations that are typically set at the beginning of each semester. These define course-wide settings and distribution templates.

{ORIGIN_DIR}
└── .divekit/                 # Project configuration
    └── distributions/        
        ├── ST1-M1/           # Sandbox environment config
        │   └── config.json   # Distribution settings
        └── ST1-M2/           # Student environment config
            └── config.json   # Distribution settings

Distribution Configuration (Example)

{ORIGIN}/.divekit/distributions/<distribution>/config.json:

{
  "version": "2.0",
  "targets": {
    "default": {
      "remote": "default", // optional
      "groupId": 12345,    // optional (if set in global config)
      "name": "ST1-M1-{{uuid}}",
      "members": {
        "path": "$DIVEKIT_MEMBERS/2025-01-25_13-37_ST1-M1_members.json",
        "rights": "reporter"
      }
    },
    "test": {
      "remote": "gitlab",  
      "groupId": 67890,    // optional (if set in global config)
      "name": "ST1-M1-{{uuid}}_test",
      "members": {
        "path": "$DIVEKIT_MEMBERS/2025-01-25_13-37_ST1-M1_members.json",
        "rights": null
      }
    }
  }
}

[2] Milestone

Configurations that change with each milestone or assignment. These include specific repository settings and member assignments.

{ORIGIN_DIR}
└── .divekit/
    └── distributions/
        └── <distribution>/   # e.g. ST1-M1
            └── config.json   # Milestone-specific settings

Members Configuration

members.csv:

username
tbuck
ada
charles
jobs
woz

generates:

~/.divekit/members/2025-01-25_13-37_ST1-M1_members.json:

{
  "version": "2.0",
  "groups": [                       // ? rename to "members"?
    {
      "uuid": "4a28af44-f2cd-4a9e-a93f-2f4c29d6dfc0",
      "members": [                  // ? rename to "group"?
        "torben.buck"
      ]
    },
    {
      "uuid": "3dc6bbc1-a4eb-44fd-80fc-230bea317bc1",
      "members": [
        "ada"
      ]
    },
    {
      "uuid": "1fe6aa82-e04b-435f-8023-10104341825d",
      "members": [
        "charles"
      ]
    },
    {
      "uuid": "eb64c6af-67da-4f55-ae3a-d4b2a02baae6",
      "members": [
        "jobs"
      ]
    },
    {
      "uuid": "ade17515-bdb9-4398-90c1-cfc078f5ec36",
      "members": [
        "woz"
      ]
    }
  ]
}

[3] 🚧 Call

Configurations that can be overridden during command execution. Any configuration value from the previous levels can be overridden using command-line arguments.

Examples:

# Specify individual files for patching
divekit patch --distribution="sandbox" src/main/java/Exercise.java src/test/java/ExerciseTest.java

# set debug loglevel
divekit patch --loglevel=debug