How apollo1321/marvin works
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.