# asi-uniovi/malloovia architecture

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

- Interactive diagram: https://gitdiagram.com/asi-uniovi/malloovia
- Repository: https://github.com/asi-uniovi/malloovia

## Overview

##### Project Type and Purpose
- Malloovia is a Python package designed to solve virtual machine allocation problems in cloud infrastructure using linear programming.
- It provides both a Python API and a CLI interface for defining and solving VM allocation problems in an IaaS context.
- The project is split into two main phases (Phase I for long term reservation decisions, and Phase II for short term VM allocations).

##### Main Components
- Core Library (malloovia package):
– Contains modules like cli.py (command-line interface), lpsolver.py (linear programming solver), model.py (definitions for VMs, problems, performance sets, etc.), phases.py (phase I and II solvers), solution_model.py, and util.py.
– YAML schemas (malloovia.schema.yaml and problem.schema.yaml) that define the problem and solution file formats.
- User Interfaces:
– Python API: Components/classes that users import and integrate directly into Python applications.
– CLI: Accessible via the malloovia/cli.py module, which allows execution via command-line.
- External Configuration/Deployment:
– Build and configuration files (setup.py, setup.cfg, pyproject.toml, Makefile, tox.ini, Travis CI configuration, etc.), which indicate testing, continuous integration (CI), and documentation generation.
- Documentation:
– The docs/ folder holds ReStructuredText files, templates, and a Makefile used to generate documentation via ReadTheDocs.
- Testing:
– The tests/ directory contains unit tests and test data (YAML problem and solution examples, CSV workloads) to ensure the project's reliability.

##### Relationships and Interactions
- User Input Flow:
– Problem definitions and workload data (possibly provided via YAML files or directly in Python) feed into the model components.
– The CLI or Python API orchestrates the execution by calling Phase I (reservation decision) followed by Phase II (on-demand allocation).
- Solver Engine:
– The lpsolver module interfaces with the problem data (constructed in model.py and phases.py) to compute the optimal VM allocation.
- Output Flow:
– After computation, the solutions are output via either a file (YAML) or returned by the API, and these may be further processed or inspected.
- Configuration and Testing:
– CI (such as Travis CI) automatically runs tests defined in the tests/ directory, ensuring the integration and reliability of all components.

##### Architectural Patterns and Design Principles
- Separation of Concerns:
– The package clearly separates problem modeling, CLI interaction, and the underlying solver logic.
- Layered Architecture:
– UI Layer (CLI/Python API) → Business Logic (Phases, Models, and Solver) → Configuration/Utility (schemas, utilities) → Testing & Documentation.
- Extensibility:
– With clear YAML schemas and modular design, adding new problem types, solvers, or additional features can be done with minimal impact on existing modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Malloovia System Architecture"
        %% Input Layer
        subgraph "Input Layer"
            UI["User Inputs (YAML/API)"]:::input
            subgraph "External Configuration"
                setup_py["setup.py"]:::input
                setup_cfg["setup.cfg"]:::input
                pyproject["pyproject.toml"]:::input
                makefile["Makefile"]:::input
                tox_ini["tox.ini"]:::input
                travis[".travis.yml"]:::input
            end
        end

        %% Processing Layer
        subgraph "Processing Layer"
            cli["CLI Interface"]:::core
            api["Python API Interface"]:::core
            %% YAML Schemas used for problem and solution definitions
            yaml1["YAML Schema (malloovia.schema.yaml)"]:::core
            yaml2["YAML Schema (problem.schema.yaml)"]:::core

            subgraph "Core Processing"
                model["Model"]:::core
                lpsolver["LP Solver"]:::core
                phaseI["Phase I Solver"]:::core
                phaseII["Phase II Solver"]:::core
                solModel["Solution Model"]:::core
                util["Utilities"]:::core
            end
        end

        %% Output Layer
        subgraph "Output Layer"
            result["Results (YAML/Printed)"]:::input
        end

        %% Testing & CI
        subgraph "Testing & CI"
            tests["Tests"]:::integration
            docs["Documentation"]:::integration
        end
    end

    %% Data Flow Connections
    UI -->|"provides data"| cli
    UI -->|"provides data"| api
    UI -->|"validates against"| yaml1
    UI -->|"validates against"| yaml2

    cli -->|"initiates"| model
    api -->|"initiates"| model
    yaml1 -->|"defines"| model
    yaml2 -->|"defines"| model

    model -->|"supplies problem"| lpsolver
    lpsolver -->|"computes reservation"| phaseI
    phaseI -->|"outputs allocation"| phaseII
    phaseII -->|"generates solution"| solModel
    solModel -->|"produces"| result

    %% Supporting utility connection (error handling, etc.)
    util --- model

    %% External configuration influence on processing and testing
    setup_py --- model
    setup_cfg --- model
    pyproject --- model
    makefile --- model
    tox_ini --- tests
    travis --- tests
    docs --- tests

    %% Styling Classes
    classDef core fill:#cce5ff,stroke:#0056b3,stroke-width:2px;
    classDef input fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef integration fill:#ffe5b4,stroke:#ff8c00,stroke-width:2px;

    %% Click Events for Core Library Components
    click cli "https://github.com/asi-uniovi/malloovia/blob/master/malloovia/cli.py"
    click api "https://github.com/asi-uniovi/malloovia/blob/master/malloovia/__init__.py"
    click model "https://github.com/asi-uniovi/malloovia/blob/master/malloovia/model.py"
    click lpsolver "https://github.com/asi-uniovi/malloovia/blob/master/malloovia/lpsolver.py"
    click phaseI "https://github.com/asi-uniovi/malloovia/blob/master/malloovia/phases.py"
    click phaseII "https://github.com/asi-uniovi/malloovia/blob/master/malloovia/phases.py"
    click solModel "https://github.com/asi-uniovi/malloovia/blob/master/malloovia/solution_model.py"
    click util "https://github.com/asi-uniovi/malloovia/blob/master/malloovia/util.py"

    %% Click Events for YAML Schemas
    click yaml1 "https://github.com/asi-uniovi/malloovia/blob/master/malloovia/malloovia.schema.yaml"
    click yaml2 "https://github.com/asi-uniovi/malloovia/blob/master/malloovia/problem.schema.yaml"

    %% Click Events for External Configuration/Deployment Files
    click setup_py "https://github.com/asi-uniovi/malloovia/blob/master/setup.py"
    click setup_cfg "https://github.com/asi-uniovi/malloovia/blob/master/setup.cfg"
    click pyproject "https://github.com/asi-uniovi/malloovia/blob/master/pyproject.toml"
    click makefile "https://github.com/asi-uniovi/malloovia/tree/master/Makefile"
    click tox_ini "https://github.com/asi-uniovi/malloovia/blob/master/tox.ini"
    click travis "https://github.com/asi-uniovi/malloovia/blob/master/.travis.yml"

    %% Click Event for Documentation
    click docs "https://github.com/asi-uniovi/malloovia/tree/master/docs/"

    %% Click Event for Testing
    click tests "https://github.com/asi-uniovi/malloovia/tree/master/tests/"
```
