# codemagic-ci-cd/cli-tools architecture

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

- Interactive diagram: https://gitdiagram.com/codemagic-ci-cd/cli-tools
- Repository: https://github.com/codemagic-ci-cd/cli-tools

## Overview

##### Project type and purpose
- This is a Python-based, full-stack CLI application (a CLI-tools suite) that provides a collection of developer utilities for mobile-app packaging, code signing, and deployment.
- It bundles multiple executables (android-app-bundle, android-keystore, app-store-connect, git-changelog, google-play, keychain, universal-apk, xcode-project, plus a master command codemagic-cli-tools).
- Its primary use case is orchestrating mobile build pipelines by calling external APIs (App Store Connect, Google Play Developer, Firebase) and system tools (bundletool, keytool, jarsigner, xcodebuild).

##### File structure
- Top-level directories:
- src/codemagic – the core library
– /cli: argument parsing, CLI app, actions, action groups
– /tools: Python wrappers for each executable
– /apple & /google: service clients, resource definitions, API sessions
– /models: domain models for packages, certificates, xctests, etc.
– /shell_tools: thin wrappers around bundled JARs and system commands
– /utilities & /mixins: cross-cutting helpers (logging, decorators, file readers)
- docs – Markdown-based user guide for each CLI command
- tests – pytest-based coverage of every module and CLI entry point
- configuration: pyproject.toml, codemagic.yaml, pre-commit, workflow CI

##### README for additional insights
- Confirms Python 3.8+, Poetry for dependency management, CLI entrypoints added to PATH.
- Describes dual interface: CLI tools and mirror Python API under codemagic.tools.
- Lists external dependencies (App Store Connect API, Google Play Developer API, Firebase Distribution).
- Quality tools: Black, Ruff, Mypy, pytest.

##### Elements
- User → CLI Entrypoint
- CLI Entrypoint → CLI Core → Tools Implementation → Service or Shell Tools → External
- External → Service → Tools → CLI → User
- Blue = internal code modules
- Green = external systems/APIs
- Orange = node_modules/shell JARs & system commands
- Grey = utilities/mixins

##### Final recommendations
- Every category of code as its own logical component
- Notes for authentication flows (JWT for App Store, service-account JSON for Google/Firebase)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Define nodes and flow top-down
    direction TB

    %% User
    User(["User (Developer)"]):::external

    %% CLI Entrypoints
    subgraph "CLI Entrypoints" 
        direction TB
        AAB["android-app-bundle"]:::internal
        AK["android-keystore"]:::internal
        ASC["app-store-connect"]:::internal
        GC["git-changelog"]:::internal
        GP["google-play"]:::internal
        KC["keychain"]:::internal
        UA["universal-apk"]:::internal
        XP["xcode-project"]:::internal
        MC["codemagic-cli-tools"]:::internal
    end

    %% CLI Core
    subgraph "CLI Core" 
        direction TB
        CLIApp["CLIApp & Argument Parsing"]:::internal
        ActionGrp["ActionGroup & Actions"]:::internal
        ArgParse["argument_parser_builder & common_argument_types"]:::internal
    end

    %% Tools Implementation
    subgraph "Tools Implementation" 
        direction TB
        AKTool["Android Keystore Tool"]:::internal
        ASTool["App Store Connect Tools"]:::internal
        FATool["Firebase App Distribution"]:::internal
        GPTool["Google Play Tools"]:::internal
        XPTool["Xcode Project API"]:::internal
        UATool["Universal APK Generator"]:::internal
        GCTool["Git Changelog"]:::internal
    end

    %% Service Layer
    subgraph "Service Layer" 
        direction TB
        subgraph "Apple Services"
            direction TB
            ASC_Session["api_session & api_client"]:::internal
            JWT["json_web_token_manager"]:::internal
        end
        subgraph "Google Services"
            direction TB
            FBC["firebase_client"]:::internal
            GPC["google_play_client"]:::internal
            GClient["google_client"]:::internal
        end
    end

    %% Domain Models & Resources
    subgraph "Domain Models & Resources"
        direction TB
        CoreModels["codemagic/models"]:::internal
        AppleRes["codemagic/apple/resources"]:::internal
        GoogleRes["codemagic/google/resources"]:::internal
    end

    %% Shell Tools
    subgraph "Shell Tools" 
        direction TB
        BundleTool["bundletool"]:::infra
        KeyTool["keytool"]:::infra
        JarSigner["jarsigner"]:::infra
        XcodeBuild["xcodebuild"]:::infra
    end

    %% Utilities & Mixins
    subgraph "Utilities & Mixins"
        direction TB
        Utils["codemagic/utilities"]:::util
        Mixins["codemagic/mixins"]:::util
    end

    %% External APIs/Systems
    subgraph "External APIs/Systems"
        direction TB
        ASC_API["App Store Connect API"]:::external
        GPlay_API["Google Play Developer API"]:::external
        Firebase_API["Firebase Distribution API"]:::external 
        LocalSys["Local System Commands"]:::infra
    end

    %% Connections
    User -->|invokes| AAB
    User -->|invokes| AK
    User -->|invokes| ASC
    User -->|invokes| GC
    User -->|invokes| GP
    User -->|invokes| KC
    User -->|invokes| UA
    User -->|invokes| XP
    User -->|invokes| MC

    AAB --> CLIApp
    AK --> CLIApp
    ASC --> CLIApp
    GC --> CLIApp
    GP --> CLIApp
    KC --> CLIApp
    UA --> CLIApp
    XP --> CLIApp
    MC --> CLIApp

    CLIApp --> ActionGrp
    ActionGrp --> ArgParse

    %% Tools from CLI Core
    ActionGrp --> AKTool
    ActionGrp --> ASTool
    ActionGrp --> FATool
    ActionGrp --> GPTool
    ActionGrp --> XPTool
    ActionGrp --> UATool
    ActionGrp --> GCTool

    %% Tools call Service or Shell Tools
    AKTool -->|subprocess| BundleTool
    AKTool -->|subprocess| KeyTool
    AKTool -->|subprocess| JarSigner

    ASTool --> ASC_Session
    ASC_Session --> JWT
    ASC_Session -->|HTTP| ASC_API
    ASC_API -->|JSON| ASC_Session
    ASC_Session -->|maps to| AppleRes

    FATool --> FBC
    FBC -->|HTTP| Firebase_API
    Firebase_API -->|JSON| FBC
    FBC -->|maps to| GoogleRes

    GPTool --> GPC
    GPC -->|HTTP| GPlay_API
    GPlay_API -->|JSON| GPC
    GPC -->|maps to| GoogleRes

    XPTool -->|subprocess| XcodeBuild
    UATool -->|subprocess| BundleTool

    GCTool -->|file I/O| CoreModels

    %% Models shared
    CoreModels -->|used by| AKTool
    CoreModels -->|used by| ASTool
    CoreModels -->|used by| FATool
    CoreModels -->|used by| GPTool

    %% Utilities
    AKTool --> Utils
    ASTool --> Utils
    FATool --> Utils
    GPTool --> Utils
    XPTool --> Utils
    UATool --> Utils
    GCTool --> Utils

    ActionGrp --> Mixins
    CLIApp --> Mixins

    %% Colors / Classes
    classDef internal fill:#ADD8E6,stroke:#000;
    classDef external fill:#90EE90,stroke:#000;
    classDef infra fill:#FFA500,stroke:#000;
    classDef util fill:#D3D3D3,stroke:#000;

    %% Click Events
    click AAB "https://github.com/codemagic-ci-cd/cli-tools/blob/master/src/codemagic/tools/android_app_bundle.py"
    click AK "https://github.com/codemagic-ci-cd/cli-tools/blob/master/src/codemagic/tools/android_keystore/__main__.py"
    click ASC "https://github.com/codemagic-ci-cd/cli-tools/blob/master/src/codemagic/tools/app_store_connect/__main__.py"
    click GC "https://github.com/codemagic-ci-cd/cli-tools/blob/master/src/codemagic/tools/git_changelog.py"
    click GP "https://github.com/codemagic-ci-cd/cli-tools/blob/master/src/codemagic/tools/google_play/__main__.py"
    click KC "https://github.com/codemagic-ci-cd/cli-tools/blob/master/src/codemagic/tools/keychain.py"
    click UA "https://github.com/codemagic-ci-cd/cli-tools/blob/master/src/codemagic/tools/universal_apk_generator.py"
    click XP "https://github.com/codemagic-ci-cd/cli-tools/blob/master/src/codemagic/tools/xcode_project.py"
    click MC "https://github.com/codemagic-ci-cd/cli-tools/blob/master/src/codemagic/tools/codemagic_cli_tools.py"

    click CLIApp "https://github.com/codemagic-ci-cd/cli-tools/blob/master/src/codemagic/cli/cli_app.py"
    click ActionGrp "https://github.com/codemagic-ci-cd/cli-tools/blob/master/src/codemagic/cli/action_group.py"
    click ArgParse "https://github.com/codemagic-ci-cd/cli-tools/blob/master/src/codemagic/cli/argument/argument_parser_builder.py"

    click AKTool "https://github.com/codemagic-ci-cd/cli-tools/blob/master/src/codemagic/tools/android_keystore/android_keystore.py"
    click ASTool "https://github.com/codemagic-ci-cd/cli-tools/tree/master/src/codemagic/tools/app_store_connect/"
    click FATool "https://github.com/codemagic-ci-cd/cli-tools/tree/master/src/codemagic/tools/firebase_app_distribution/"
    click GPTool "https://github.com/codemagic-ci-cd/cli-tools/tree/master/src/codemagic/tools/google_play/"
    click XPTool "https://github.com/codemagic-ci-cd/cli-tools/tree/master/src/codemagic/tools/_xcode_project/"
    click UATool "https://github.com/codemagic-ci-cd/cli-tools/blob/master/src/codemagic/tools/universal_apk_generator.py"
    click GCTool "https://github.com/codemagic-ci-cd/cli-tools/blob/master/src/codemagic/tools/git_changelog.py"

    click ASC_Session "https://github.com/codemagic-ci-cd/cli-tools/blob/master/src/codemagic/apple/app_store_connect/api_session.py"
    click JWT "https://github.com/codemagic-ci-cd/cli-tools/blob/master/src/codemagic/apple/app_store_connect/json_web_token_manager.py"

    click FBC "https://github.com/codemagic-ci-cd/cli-tools/blob/master/src/codemagic/google/firebase_client.py"
    click GPC "https://github.com/codemagic-ci-cd/cli-tools/blob/master/src/codemagic/google/google_play_client.py"
    click GClient "https://github.com/codemagic-ci-cd/cli-tools/blob/master/src/codemagic/google/google_client.py"

    click CoreModels "https://github.com/codemagic-ci-cd/cli-tools/tree/master/src/codemagic/models/"
    click AppleRes "https://github.com/codemagic-ci-cd/cli-tools/tree/master/src/codemagic/apple/resources/"
    click GoogleRes "https://github.com/codemagic-ci-cd/cli-tools/tree/master/src/codemagic/google/resources/"

    click BundleTool "https://github.com/codemagic-ci-cd/cli-tools/blob/master/src/codemagic/shell_tools/bundletool.py"
    click KeyTool "https://github.com/codemagic-ci-cd/cli-tools/blob/master/src/codemagic/shell_tools/keytool.py"
    click JarSigner "https://github.com/codemagic-ci-cd/cli-tools/blob/master/src/codemagic/shell_tools/jarsigner.py"
    click XcodeBuild "https://github.com/codemagic-ci-cd/cli-tools/blob/master/src/codemagic/shell_tools/java_jar_tool.py"

    click Utils "https://github.com/codemagic-ci-cd/cli-tools/tree/master/src/codemagic/utilities/"
    click Mixins "https://github.com/codemagic-ci-cd/cli-tools/tree/master/src/codemagic/mixins/"
```
