# netcracker/qubership-git-system-follower architecture

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

- Interactive diagram: https://gitdiagram.com/netcracker/qubership-git-system-follower
- Repository: https://github.com/netcracker/qubership-git-system-follower

## Overview

##### Project Overview and Components
- This project is a Python-based package manager dedicated to Git providers (with a strong focus on GitLab). It automates the management of repository branch content—specifically handling installation, update, and removal of “gears” (i.e. Git packages).
- The architecture centers on several major parts:
- The Command Line Interface (CLI) layer (found in modules like git_system_follower/cli.py and related plugins) where users or automation tools invoke commands.
- The Core Package Management subsystem (in git_system_follower/package) that handles operations such as installation, updates, rollbacks, and removal of package configurations.
- The API Abstraction Layer (in git_system_follower/git_api) that encapsulates communications with external Git providers – currently tailored for GitLab.
- The Developer Interface (in git_system_follower/develop) and associated modules (api, cicd_variables, templates, types) that assist package developers in defining custom behaviors for gear installation and migrations.
- Supporting utilities (in git_system_follower/utils and logger) for retries, temporary directories, output formatting, and logging.
- Plugin infrastructure (in git_system_follower/plugins) that allows for CLI extension points, thereby enabling dynamic command execution or configuration adjustments.
- External state management using a designated file (the .state.yaml mentioned in the README) to persist the current state and hash values to verify the integrity of changes.

##### Analyzing the File Structure for Architectural Patterns
- The organization into directories such as “git_system_follower” and its submodules (“develop”, “git_api”, “package”, “plugins”, “utils”) suggests a modular design with separation of concerns.
- The “docs” directory is rich with API and CLI references, concepts, and how-to guides; use it as a reference for core functionality and integration points to external systems.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        CLI["CLI Interface"]:::cli
    end

    %% Core Engine
    subgraph "Core Engine"
        CMP["Core Package Manager"]:::core
        GAPI["Git API Abstraction"]:::core
        STATE["State Manager"]:::core
    end

    %% Developer Tools
    subgraph "Developer Tools"
        DEVAPI["Developer Interface"]:::developer
    end

    %% Plugin Infrastructure
    subgraph "Plugin Infrastructure"
        PLUG["Plugin Manager"]:::plugin
        CLI_PLUG["CLI Plugin Extensions"]:::plugin
    end

    %% Supporting Utilities
    subgraph "Utilities"
        UTILS["Supporting Utilities"]:::util
        LOGGER["Logger"]:::util
    end

    %% External Services
    subgraph "External Services"
        GITLAB["GitLab"]:::external
        REGISTRY["Gear Registry (Nexus/Docker/Artifactory)"]:::external
    end

    %% Development Environment
    subgraph "Dev Environment"
        DEVBOX["Devbox Environment"]:::dev
        DEV_DOCKER["Docker Compose"]:::dev
        DEV_NGINX["Nginx Config"]:::dev
        DEV_SCRIPTS["Devbox Scripts"]:::dev
    end

    %% Connections - Internal Flows
    CLI -->|"triggers"| CMP
    PLUG -->|"extends"| CLI
    CLI_PLUG -->|"integrates"| CLI
    CMP -->|"calls"| GAPI
    CMP -->|"updates"| STATE
    CMP -->|"invokes"| DEVAPI
    CMP -->|"utilizes"| UTILS
    CMP -->|"logsTo"| LOGGER
    GAPI -->|"communicates"| GITLAB
    GITLAB -->|"notifies"| REGISTRY

    %% Connections - Dev Environment Testing/Simulation
    DEVBOX -->|"simulates"| CLI
    DEVBOX -->|"tests"| CMP
    DEVBOX -->|"tests"| GAPI
    DEVBOX -->|"tests"| DEVAPI
    DEVBOX -->|"tests"| PLUG
    DEVBOX -->|"tests"| UTILS

    %% Connections - Dev Environment Files Linking
    DEVBOX -.-> DEV_DOCKER
    DEVBOX -.-> DEV_NGINX
    DEVBOX -.-> DEV_SCRIPTS

    %% Click Events
    click CLI "https://github.com/netcracker/qubership-git-system-follower/blob/main/git_system_follower/cli.py"
    click CMP "https://github.com/netcracker/qubership-git-system-follower/tree/main/git_system_follower/package/"
    click GAPI "https://github.com/netcracker/qubership-git-system-follower/tree/main/git_system_follower/git_api/"
    click STATE "https://github.com/netcracker/qubership-git-system-follower/blob/main/git_system_follower/states.py"
    click DEVAPI "https://github.com/netcracker/qubership-git-system-follower/tree/main/git_system_follower/develop/api/"
    click PLUG "https://github.com/netcracker/qubership-git-system-follower/tree/main/git_system_follower/plugins/"
    click CLI_PLUG "https://github.com/netcracker/qubership-git-system-follower/tree/main/git_system_follower/plugins/cli/"
    click UTILS "https://github.com/netcracker/qubership-git-system-follower/tree/main/git_system_follower/utils/"
    click LOGGER "https://github.com/netcracker/qubership-git-system-follower/blob/main/git_system_follower/logger.py"
    click DEVBOX "https://github.com/netcracker/qubership-git-system-follower/tree/main/devbox/"
    click DEV_DOCKER "https://github.com/netcracker/qubership-git-system-follower/blob/main/devbox/docker-compose.yml"
    click DEV_NGINX "https://github.com/netcracker/qubership-git-system-follower/blob/main/devbox/nginx.conf"
    click DEV_SCRIPTS "https://github.com/netcracker/qubership-git-system-follower/tree/main/devbox/scripts/"

    %% Styles
    classDef cli fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef core fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef developer fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef plugin fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef util fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef external fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef dev fill:#fefefe,stroke:#818182,stroke-width:2px;
```
