# apollo1321/marvin architecture

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

- Interactive diagram: https://gitdiagram.com/apollo1321/marvin
- Repository: https://github.com/apollo1321/marvin

## Overview

##### Project type and purpose
- Project type: A language-agnostic, Nix-powered CLI tool for automating build, test, lint, format, and submission workflows in student course repositories.
- Purpose: Provide reproducible environments and seamless integration with C++ and Go build/test tooling, sandbox execution, quality checks, and submission to a grading system.

##### File structure
- Top-level directories:
– cli/: The entire CLI application (source code, modules, configuration).
– courses/: Per-course directories with Nix configs and YAML for course tasks.
– dev_env/: Reusable Nix expressions for language environments.
– doc/: Setup and usage guides.
– scripts/: Helper scripts to install/uninstall/activate Nix environment.
- Configuration/build orchestrators: flake.nix, flake.lock, default.nix files, Nix expressions.
- Language modules: cli/src/modules/cpp.py and go.py.
- Core routing: cli/src/main.py and lib.py.
- Private/staff commands: cli/src/private.py.

##### Key insights from README
- Modular architecture: core utilities, CLI router, per-language modules, private commands.
- Nix-based reproducible environments.
- External integrations: CMake/Ninja, Clang-Tidy/Format for C++, Go toolchain, sandboxing on Linux, external grading/submission endpoint, IDE integrations.

##### Main components and relationships
- User shell (Linux/macOS/WSL)
↓
- Activation scripts (scripts/activate → sets env via Nix)
↓
- CLI Frontend (cli/src/main.py)
↔ Core library (cli/src/lib.py)
↔ Language modules (cpp.py, go.py)
↔ Private commands (private.py)
↓
- Environment manager (Nix flakes, dev_env/*.nix, course default.nix)
- Build/test tools
– C++: CMake, Ninja, Clang-Tidy, Clang-Format
– Go: go build/test, sandbox runtime
- Course config (courses/*/config.yml)
↓
- External grading system (submission API)
- File system (source code, build artifacts)

Data flow examples:
– User runs “cli test” → main.py routes to cpp.py or go.py → invokes CMake/Go tool → test results returned to CLI → exit code.
– User runs “cli submit” → module packages code → HTTP call to grading endpoint.

##### Architectural patterns and principles
- Modular plugin pattern: language support via separate modules (cpp, go).
- Separation of concerns:
– CLI parsing & routing (main.py)
– Shared utilities (lib.py)
– Environment provisioning (Nix files)
- Declarative environment management (Nix flakes).
- Extensibility: add new language by dropping in a new module.
- Single entry point CLI with subcommands.

##### Elements
- Clear labels: e.g., “CLI Router (main.py)”, “C++ Module (cpp.py)”, “Nix Flake (flake.nix)”.
– command invocation path,
– environment provisioning steps,
– data/results flow.
– Python code vs. Nix configs vs. external binaries.
- Notes on key interactions:
– “ENV variables set here”,
– “YAML course config loaded here”.

##### Detail level
- Every folder → file grouping as components only if they play a distinct role.
- Dev_env/*.nix files as one “Dev Env Nix Expressions” block.
- Courses/* as a “Course Config” block, connected to both CLI and Nix environment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Shell
    Shell("User Shell (bash/zsh/PowerShell)"):::external

    %% Scripts
    subgraph "Activation Scripts"
        Activate("Activate Script"):::blue
        Install("Install Nix"):::blue
        Uninstall("Uninstall Nix"):::blue
    end

    %% CLI Layer
    subgraph "CLI Layer"
        Router("CLI Router<br/>(main.py)"):::green
        Lib("Core Library<br/>(lib.py)"):::green
        subgraph "Language Modules"
            CPP("C++ Module<br/>(cpp.py)"):::green
            Go("Go Module<br/>(go.py)"):::green
        end
        Private("Private Commands<br/>(private.py)"):::green
    end

    %% Environment Management
    subgraph "Environment Management" 
        Flake("Nix Flake<br/>(flake.nix)"):::blue
        Lock("Flake Lockfile<br/>(flake.lock)"):::blue
        DevEnv("Dev Env Nix Expressions"):::blue
        CLIConfig("CLI Nix Config<br/>(default.nix)"):::blue
        subgraph "Course Config"
            CourseDS("DS Course Nix<br/>(courses/ds/default.nix)"):::blue
            CoursePCP("PCP Course Nix<br/>(courses/pcp/default.nix)"):::blue
            YAMLDS("DS Task Definitions<br/>(courses/ds/config.yml)"):::blue
            YAMLPCP("PCP Task Definitions<br/>(courses/pcp/config.yml)"):::blue
        end
    end

    %% Build/Test Engines
    subgraph "Build/Test Engines"
        CMake("CMake/Ninja/LLVM"):::orange
        GoTool("Go Build/Test"):::orange
        Sandbox("Sandbox Runtime"):::orange
    end

    %% File System
    FS("File System<br/>(source & artifacts)"):::external

    %% External Services
    Grading("Grading API Endpoint"):::purple

    %% Documentation
    Doc("Documentation<br/>(setup.md)"):::external

    %% Connections
    Shell -->|"runs"| Activate
    Shell -->|"runs"| Install
    Shell -->|"runs"| Uninstall

    Activate -->|sets ENV| Router
    Install -->|installs Nix| Flake
    Uninstall -->|removes Nix| Flake

    Router -->|uses| Lib
    Router -->|routes to| CPP
    Router -->|routes to| Go
    Router -->|routes to| Private

    Router -->|loads| CLIConfig
    Router -->|reads| CourseDS
    Router -->|reads| CoursePCP
    Lib -->|invokes| DevEnv

    CPP -->|calls| CMake
    CPP -->|invokes| Sandbox
    Go -->|calls| GoTool
    Private -->|may use| Lib

    CMake -->|writes/reads| FS
    GoTool -->|writes/reads| FS
    Sandbox -->|isolates| FS

    Router -->|submits| Grading
    Grading -->|returns result| Router

    Doc -->|guides| Shell
    Doc -->|guides| Router

    %% Click Events
    click Router "https://github.com/apollo1321/marvin/blob/main/cli/src/main.py"
    click Lib "https://github.com/apollo1321/marvin/blob/main/cli/src/lib.py"
    click CPP "https://github.com/apollo1321/marvin/blob/main/cli/src/modules/cpp.py"
    click Go "https://github.com/apollo1321/marvin/blob/main/cli/src/modules/go.py"
    click Private "https://github.com/apollo1321/marvin/blob/main/cli/src/private.py"
    click CLIConfig "https://github.com/apollo1321/marvin/blob/main/cli/default.nix"
    click Flake "https://github.com/apollo1321/marvin/blob/main/flake.nix"
    click Lock "https://github.com/apollo1321/marvin/blob/main/flake.lock"
    click DevEnv "https://github.com/apollo1321/marvin/tree/main/dev_env/"
    click CourseDS "https://github.com/apollo1321/marvin/blob/main/courses/ds/default.nix"
    click CoursePCP "https://github.com/apollo1321/marvin/blob/main/courses/pcp/default.nix"
    click YAMLDS "https://github.com/apollo1321/marvin/blob/main/courses/ds/config.yml"
    click YAMLPCP "https://github.com/apollo1321/marvin/blob/main/courses/pcp/config.yml"
    click Activate "https://github.com/apollo1321/marvin/tree/main/scripts/activate"
    click Install "https://github.com/apollo1321/marvin/tree/main/scripts/install_nix"
    click Uninstall "https://github.com/apollo1321/marvin/tree/main/scripts/uninstall_nix"
    click Doc "https://github.com/apollo1321/marvin/blob/main/doc/setup.md"

    %% Styles
    classDef green fill:#e0f8e9,stroke:#2ecc71,stroke-width:2px;
    classDef blue fill:#e8f4fd,stroke:#3498db,stroke-width:2px;
    classDef orange fill:#fff4e5,stroke:#e67e22,stroke-width:2px;
    classDef purple fill:#f3e5ff,stroke:#9b59b6,stroke-width:2px;
    classDef external fill:#f0f0f0,stroke:#7f8c8d,stroke-width:1px,stroke-dasharray: 5 5;
```
