# magalucloud/magalu architecture

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

- Interactive diagram: https://gitdiagram.com/magalucloud/magalu
- Repository: https://github.com/magalucloud/magalu

## Overview

This project is a monorepo for Magalu Cloud (MGC) that focuses on a CLI/SDK tool built in Golang. Its core purpose is to provide a command line interface (CLI) and an SDK layer that implements concrete data types (from the “core”) for client commands, and also to process OpenAPI specifications (both dynamic “OpenAPI” and static APIs) to interact with cloud resources. The monorepo is well modularized into several Go modules as follows:

##### Main Components
- Core Module (mgc/core): Contains the basic data types and intermediate representations, HTTP utilities, configuration, logger, and schema definitions.
- SDK Module (mgc/sdk): Implements the concrete commands and exposes them using the definitions in core. It exports functionality for both the CLI and external consumers (e.g., Terraform provider) and includes OpenAPI helpers for dynamically generated commands.
- CLI Module (mgc/cli): Builds a CLI application using Cobra. This leverages both SDK and static API definitions to expose commands to end-users.
- Spec Manipulator (mgc/spec_manipulator): A dedicated tool for handling, transforming, or merging OpenAPI specifications. This tool processes API specs from the “specs” folder.
- OpenAPI customizations and Scripts: Separate directories (openapi-customizations, scripts, and utility Python scripts) provide extra tooling for customizing and validating API definitions and other aspects (e.g., pre-commit hooks for linting and formatting).

##### Interactions and Relationships
- The CLI (mgc/cli) acts as the user interface and uses the SDK (mgc/sdk) commands and functionalities.
- The SDK internally leverages the core module (mgc/core) to build its internal data representation and processing pipelines.
- The Spec Manipulator serves as an auxiliary tool to process OpenAPI specifications which are integrated into SDK and CLI modules.
- External scripts (written in Python) and standard tooling (such as goreleaser, pre-commit, and build scripts) support building, testing, and releasing the application.

##### Architectural Patterns and Design Principles
- Modularization: Each functionality (low level types, command construction, CLI presentation, and API spec manipulation) is segmented into distinct Go modules (core, sdk, cli, spec_manipulator), promoting separation of concerns.
- Layered Approach: Data flows from the CLI layer through the SDK to the core and then to external APIs or resources.
- Extensibility: The project is designed to support adding new APIs, either via dynamic OpenAPI spec loading or static code (see the “ADD_NEW_API.md” for guidelines), which encourages plug-and-play extensibility.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Architecture Note
    ArchNote["Modular Architecture\nSeparation of Concerns\nDynamic_vs_Static_API_integration"]:::note

    %% User Interface Layer
    subgraph "User Interface Layer"
        CLI["mgc/cli (CLI)"]:::cli
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        SDK["mgc/sdk (SDK)"]:::sdk
        Core["mgc/core (Core)"]:::core
    end

    %% API Specification Tools
    subgraph "API Spec Tools"
        SpecManipulator["mgc/spec_manipulator (Spec Manipulator)"]:::spec
        OpenAPICustom["OpenAPI Customizations"]:::spec
    end

    %% Auxiliary Tools
    subgraph "Auxiliary Tools"
        Utility["Utility Scripts"]:::utility
        PyProject["pyproject.toml"]:::utility
        subgraph "Build/CI Tools"
            Makefile["Makefile"]:::build
            Workflows[".github/workflows"]:::build
            PreCommit[".pre-commit-config.yaml"]:::build
        end
    end

    %% External Dependencies
    subgraph "External Dependencies"
         Terraform["Terraform Provider"]:::external
         GoRuntime["Go Runtime"]:::external
         PythonRuntime["Python"]:::external
    end

    %% Connections and Relationships
    ArchNote --- CLI
    CLI -->|"uses"| SDK
    SDK -->|"reliesOn"| Core
    SpecManipulator -->|"processesSpecs"| SDK
    OpenAPICustom -->|"customizesSpecs"| SDK
    Utility -->|"aidsSpecManipulation"| SpecManipulator
    Makefile -->|"builds"| CLI
    Workflows -->|"builds"| CLI
    PreCommit -->|"ensuresQuality"| CLI
    SDK -->|"exposes"| Terraform
    GoRuntime --- CLI
    GoRuntime --- SDK
    GoRuntime --- Core
    PythonRuntime --- Utility

    %% Click Events
    click CLI "https://github.com/magalucloud/magalu/tree/main/mgc/cli"
    click SDK "https://github.com/magalucloud/magalu/tree/main/mgc/sdk"
    click Core "https://github.com/magalucloud/magalu/tree/main/mgc/core"
    click SpecManipulator "https://github.com/magalucloud/magalu/tree/main/mgc/spec_manipulator"
    click OpenAPICustom "https://github.com/magalucloud/magalu/tree/main/openapi-customizations"
    click Utility "https://github.com/magalucloud/magalu/tree/main/scripts"
    click PyProject "https://github.com/magalucloud/magalu/blob/main/pyproject.toml"
    click Makefile "https://github.com/magalucloud/magalu/tree/main/Makefile"
    click Workflows "https://github.com/magalucloud/magalu/tree/main/.github/workflows"
    click PreCommit "https://github.com/magalucloud/magalu/blob/main/.pre-commit-config.yaml"

    %% Styles
    classDef cli fill:#ffcccc,stroke:#660000,stroke-width:2px;
    classDef sdk fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef core fill:#ccccff,stroke:#000066,stroke-width:2px;
    classDef spec fill:#ffffcc,stroke:#666600,stroke-width:2px;
    classDef utility fill:#d1e7dd,stroke:#0f5132,stroke-width:2px;
    classDef build fill:#cff4fc,stroke:#055160,stroke-width:2px;
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef note fill:#f8d7da,stroke:#842029,stroke-width:2px;
```
