# pranavtechie/modelith-cli architecture

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

- Interactive diagram: https://gitdiagram.com/pranavtechie/modelith-cli
- Repository: https://github.com/pranavtechie/modelith-cli

## Overview

##### Project Type and Purpose
- Modelith is an open-source, CLI-based tool designed to help professors, TAs, and teachers compare coding assignments – primarily by analyzing ASTs of submission files (currently supporting Jupyter notebooks) to identify similarities and potential plagiarism.
- In addition to its CLI functionality, the project incorporates a web client (frontend) for filtering submissions, visualizing the similarity matrix, and possibly extended features like trend analysis and class management.
- It also includes some automation components (e.g., Kaggle automation) indicating that the tool can interface with external platforms for additional data extraction or login functionalities.

##### File Structure and Key Components
- Top-level directories and files:
- The “src” directory encapsulates the main source code within a “modelith” package.
- “src/modelith/cli” – Contains the command-line interface and its commands (extract, init, kaggle_dump). This is the entry point when using the tool via the command line.
- “src/modelith/core” – Houses the core logic such as AST comparison, database operations (using sqlite), folder hashing, sanity checks, and notebook analysis. This is essentially the “engine” that performs the assignment comparisons.
- “src/modelith/frontend” – Contains the web client part of the project, built with modern web technologies (a React-based single page application using Vite, TypeScript, and a package manager lock file such as bun.lock). This component likely provides additional interactive features like threshold-based filtering and visual reports.
- “src/modelith/kaggle_automation” – Contains scripts aimed at automating aspects of Kaggle interaction, e.g., logging in.
- Other supportive files include configuration files (Makefile, pyproject.toml), test scripts in the “tests” directory, CI/CD configurations under “.github/workflows”, and development tooling under “devtools”.

##### Defining the Main Architectural Components
a. Components:
- CLI Interface: Represented by the “cli” directory with its commands (extract, init, kaggle_dump). This component is the user’s gateway to invoking functionality.
- Core Engine: Located in the “core” directory, it includes AST comparison, database operations, and various helper utilities (e.g., folder hashing and sanity checks).
- Database Module: A part of the core logic that uses SQLite for storing submissions and metadata.
- Frontend Web Client: A modern web application residing in “frontend” that interfaces with the core’s data and provides visualization (similarity matrix, filtering mechanisms, and likely dashboards).
- Kaggle Automation Module: A specialized component that handles external service interactions (Kaggle-specific operations).
- Testing and CI/CD: Represented by “tests” for unit tests and the “.github/workflows” for continuous integration and deployment pipelines.

b. Relationships and Interactions:
- The CLI tool (via its commands) calls into the core engine functions, triggering processes like AST generation, analysis, and database updates.
- The core engine communicates with the SQLite database to store, retrieve, and compare submission data.
- The frontend module reads from (or interfaces with) the database or core APIs (if there is an API layer in place) to display analysis results and similarity matrices.
- The Kaggle automation module might interact with external APIs to pull or dump data that will then flow into the core’s processing pipeline.
- Continuous integration (CI) workflows ensure that changes to any of these components are tested and deployed correctly.

##### Architectural Patterns or Design Principles
- Separation of concerns: The project clearly delineates functionality into CLI, core processing, and web presentation layers.
- Modular design: The use of separate directories for distinct responsibilities (e.g., separate “cli”, “core”, and “frontend” modules) supports maintainability and scalability.
- Extensibility: With dedicated directories for future features (e.g., class management, multi-language support), the architecture shows plans for modular expansion.
- Integration with external package management and deployment tooling (such as uv for Python environments and GitHub Actions) helps keep the tool lightweight and easily installable.

##### Technologies and Frameworks
- Python for the CLI and core logic.
- SQLite as the lightweight database solution.
- uv (the new package manager for Python) is used to manage the Python environment and dependencies.
- React/TypeScript and Vite for the web frontend development.
- Build/configuration tools including Makefile, pyproject.toml, and bun (for frontend package locking).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI Interface"]:::cli
        Extract["Command: extract"]:::cli
        Init["Command: init"]:::cli
        KaggleDump["Command: kaggle_dump"]:::cli
        CLI -->|"triggers"| Extract
        CLI -->|"triggers"| Init
        CLI -->|"triggers"| KaggleDump
    end

    %% Core Processing Layer
    subgraph "Core Processing Layer"
        CoreEngine["Core Engine"]:::core
        AST["AST Comparison"]:::core
        Folder["Folder Hashing"]:::core
        Notebook["Notebook Analyzer"]:::core
        Sanitize["Sanitize Filenames"]:::core
        Sanity["Sanity Check"]:::core
        CoreEngine -->|"executes"| AST
        CoreEngine -->|"executes"| Folder
        CoreEngine -->|"executes"| Notebook
        CoreEngine -->|"executes"| Sanitize
        CoreEngine -->|"executes"| Sanity
    end

    %% Database Module
    subgraph "Database"
        Database["Database Module"]:::db
    end

    %% Frontend Layer
    subgraph "Frontend Layer"
        Frontend["Frontend Web Client"]:::frontend
        ReactApp["React App"]:::frontend
        Frontend -->|"hosts"| ReactApp
    end

    %% External Integration: Kaggle Automation
    subgraph "External Integration"
        Kaggle["Kaggle Automation Module"]:::automation
    end

    %% CI/CD & Testing
    subgraph "CI/CD & Testing"
        Testing["Testing & CI/CD"]:::testing
    end

    %% Relationships between layers
    CLI ---|"calls"| CoreEngine
    CoreEngine ---|"stores data in"| Database
    Database ---|"serves data to"| Frontend
    Kaggle ---|"feeds data to"| CoreEngine

    %% CI/CD & Testing monitors all components
    Testing ---|"validates"| CLI
    Testing ---|"validates"| CoreEngine
    Testing ---|"validates"| Frontend
    Testing ---|"validates"| Kaggle

    %% Click Events for CLI Interface
    click CLI "https://github.com/pranavtechie/modelith-cli/tree/main/src/modelith/cli/"
    click Extract "https://github.com/pranavtechie/modelith-cli/blob/main/src/modelith/cli/commands/extract.py"
    click Init "https://github.com/pranavtechie/modelith-cli/blob/main/src/modelith/cli/commands/init.py"
    click KaggleDump "https://github.com/pranavtechie/modelith-cli/blob/main/src/modelith/cli/commands/kaggle_dump.py"

    %% Click Events for Core Engine and its modules
    click CoreEngine "https://github.com/pranavtechie/modelith-cli/tree/main/src/modelith/core/"
    click AST "https://github.com/pranavtechie/modelith-cli/blob/main/src/modelith/core/ast_comparison.py"
    click Folder "https://github.com/pranavtechie/modelith-cli/blob/main/src/modelith/core/folder_hash.py"
    click Notebook "https://github.com/pranavtechie/modelith-cli/blob/main/src/modelith/core/notebook_analyzer.py"
    click Sanitize "https://github.com/pranavtechie/modelith-cli/blob/main/src/modelith/core/sanitize_filenames.py"
    click Sanity "https://github.com/pranavtechie/modelith-cli/blob/main/src/modelith/core/sanity_check.py"

    %% Click Event for Database Module
    click Database "https://github.com/pranavtechie/modelith-cli/blob/main/src/modelith/core/db_operations.py"

    %% Click Events for Frontend Web Client
    click Frontend "https://github.com/pranavtechie/modelith-cli/tree/main/src/modelith/frontend/"
    click ReactApp "https://github.com/pranavtechie/modelith-cli/blob/main/src/modelith/frontend/src/main.tsx"

    %% Click Event for Kaggle Automation Module
    click Kaggle "https://github.com/pranavtechie/modelith-cli/blob/main/src/modelith/kaggle_automation/kaggle_login.py"

    %% Click Event for Testing & CI/CD
    click Testing "https://github.com/pranavtechie/modelith-cli/tree/main/tests/"

    %% Styles
    classDef cli fill:#AED6F1,stroke:#5DADE2,stroke-width:2px;
    classDef core fill:#A9DFBF,stroke:#28B463,stroke-width:2px;
    classDef db fill:#F9E79F,stroke:#F4D03F,stroke-width:2px;
    classDef frontend fill:#D7BDE2,stroke:#AF7AC5,stroke-width:2px;
    classDef automation fill:#F5B7B1,stroke:#EC7063,stroke-width:2px;
    classDef testing fill:#D2B4DE,stroke:#BB8FCE,stroke-width:2px;
```
