# nikgapps/project architecture

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

- Interactive diagram: https://gitdiagram.com/nikgapps/project
- Repository: https://github.com/nikgapps/project

## Overview

##### Project type and purpose
- This is an open-source, command-line Python tool (“NikGapps”) for building custom Google Apps (GApps) packages for Android.
- It packages, overlays, compresses, and releases GApps variants based on user configuration.

##### File structure
- Top-level:
- Dockerfile, setup.py, requirements.txt – build & packaging.
- script.sh, update_version.py – release automation.
- NikGapps/ – the Python package.
- Inside NikGapps/:
- build/ – core build engine: Build.py, Manager, Overlay logic, Release slicing.
- config/ – configuration loader & definitions.
- helper/ – utility subsystems (AppSet, Assets, Package, git wrappers, overlay metadata, compression).
- cache.py, copy_repos.py, overlay_control.py – orchestration scripts.
- main.py – CLI entrypoint; test.py – test harness.
- assets (shell scripts, JSON/YAML) under helper/assets drive installer scripts and defaults.
- Configuration files (build_config.py, config_upload.py) govern build parameters.

##### README insights
- Outlines build prerequisites (python3, aapt, apktool, git, git-lfs).
- Describes feature set (custom partitioning, addon.d support, debloater config).
- CLI usage: `nikgapps --androidVersion X --packageList Y`.
- Emphasis on full configurability and variant packaging.

##### Main components & interactions
a. Components
1. CLI Interface (main.py)
2. Configuration Loader (NikGapps/config)
3. Build Manager (NikGapps/build/NikGappsManager.py)
4. Overlay & Release Engine (NikGapps/build & helper/overlay)
5. Compression Engine (helper/compression)
6. Asset Generator (helper/assets shell scripts)
7. Git & Repository Interface (helper/git)
8. Cache & File System (cache.py, copy_repos.py)
9. External Tools (aapt, apktool, git, zip utilities)
10. Output Sink (Releases directory)

b. Relationships & data flow
- User invokes CLI →
Configuration Loader parses command-line args & nikgapps.config →
Build Manager orchestrates:
– fetches sources (helper/git & copy_repos) →
– generates overlays & metadata (helper/overlay) →
– invokes compression routines (helper/compression) →
– assembles shell assets (helper/assets) →
– writes to output directories →
– triggers Release module to tag, zip, and move packages.
- All file operations go through cache and temp folders.
- External tools invoked at overlay extraction and asset packaging steps.

c. Architectural patterns & principles
- Modular layered architecture: CLI → Core → Helpers → External tools.
- Separation of concerns: config parsing, build orchestration, overlay processing, packaging.
- Plugin-like helpers: easy to extend overlay or compression strategies.
- Declarative assets: shell scripts and JSON/YAML define install behaviors.

d. Key technologies & frameworks
- Python 3.x packaging (setup.py, installable NikGapps CLI)
- Shell scripting (helper/assets/*.sh)
- apktool, aapt (Android package processing)
- Git & Git-LFS (source retrieval)
- Standard compression libraries (zip, tar) via Python and shell

##### Detail
- External commands (aapt, apktool, git) as separate nodes.
- Configuration files (nikgapps.config, debloater.config) feeding into the Manager.
- Final output directory and release process.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI Interface\nmain.py"]:::internal
        ConfigLoader["Configuration Loader\nNikGappsConfig.py"]:::internal
        ConfigUpload["Config Upload Script\nconfig_upload.py"]:::internal
    end

    %% Core Engine
    subgraph "Core Engine"
        BuildManager["Build Manager\nNikGappsManager.py"]:::internal
        BuildLogic["Core Build Logic\nBuild.py"]:::internal
        OverlaysController["Overlay Engine Controller\nNikGappsOverlays.py"]:::internal
        ReleaseSlicing["Release Slicing & Packaging\nRelease.py"]:::internal
        PackageConstants["Package Constants\nPackageConstants.py"]:::internal
    end

    %% Helper Modules
    subgraph "Helper Modules"
        subgraph "Compression Engine"
            CompressionOps["CompOps.py"]:::internal
            CompressionExport["Export.py"]:::internal
        end
        AssetScripts["Asset Generator\nhelper/assets"]:::assets
        GitInterface["Git & Repo Interface\nTestGit.py"]:::internal
        subgraph "Overlay Helpers"
            Overlay["Overlay.py"]:::internal
            ApkMetaInfo["ApkMetaInfo.py"]:::internal
            Manifest["Manifest.py"]:::internal
            Resources["Resources.py"]:::internal
            String["String.py"]:::internal
            StringArray["StringArray.py"]:::internal
            Library["Library.py"]:::internal
            Bool["Bool.py"]:::internal
        end
        subgraph "Utility Subsystems"
            AppSet["AppSet.py"]:::internal
            PackageUtil["Package.py"]:::internal
            ConfigUtil["Config.py"]:::internal
            ConfigObj["ConfigObj.py"]:::internal
            ArgsUtil["Args.py"]:::internal
            AssetsUtil["Assets.py"]:::internal
        end
    end

    %% File System / Storage
    subgraph "File System / Storage"
        CacheStore[(Cache & Temp Folders)]:::storage
        ReleasesDir[(Releases Directory)]:::storage
    end

    %% External Tools
    subgraph "External Tools"
        AAPT["aapt"]:::external
        APKTOOL["apktool"]:::external
        GIT["git / git-lfs"]:::external
        ZIP["zip/tar"]:::external
    end

    %% Connections
    CLI -->|invokes| ConfigLoader
    CLI -->|invokes| BuildManager
    ConfigLoader -->|provides configs| BuildManager
    BuildManager -->|uses| GitInterface
    BuildManager -->|copies repos| CacheStore
    BuildManager -->|orchestrates| OverlaysController
    OverlaysController -->|utilizes| Overlay
    OverlaysController --> ApkMetaInfo
    OverlaysController --> Manifest
    OverlaysController --> Resources
    OverlaysController --> String
    OverlaysController --> StringArray
    OverlaysController --> Library
    OverlaysController --> Bool
    OverlaysController -->|invokes| APKTOOL
    BuildManager -->|executes| CompressionOps
    BuildManager --> CompressionExport
    CompressionOps -->|writes to| CacheStore
    CompressionExport -->|writes to| CacheStore
    BuildManager -->|generates assets| AssetScripts
    AssetScripts -->|shell scripts| CacheStore
    BuildManager -->|defines constants| PackageConstants
    BuildManager -->|triggers| ReleaseSlicing
    ReleaseSlicing -->|reads from| CacheStore
    ReleaseSlicing -->|writes zips to| ReleasesDir
    ReleaseSlicing -->|invokes| ZIP
    ReleaseSlicing -->|tags repo via| GIT

    %% Test Harnesses
    Test1["Project Test Harness\nNikGapps/test.py"]:::internal
    Test2["Root Test Script\ntest.py"]:::internal
    Test1 --> CacheStore
    Test2 --> CacheStore

    %% Styling
    classDef internal fill:#D0E6FF,stroke:#569CD6,color:#000
    classDef assets fill:#E6FFDD,stroke:#8CC152,color:#000
    classDef external fill:#FFE7C0,stroke:#E69138,color:#000
    classDef storage fill:#EEEEEE,stroke:#666666,color:#000

    %% Click Events
    click CLI "https://github.com/nikgapps/project/blob/main/NikGapps/main.py"
    click ConfigLoader "https://github.com/nikgapps/project/blob/main/NikGapps/config/NikGappsConfig.py"
    click ConfigUpload "https://github.com/nikgapps/project/blob/main/NikGapps/config_upload.py"
    click BuildManager "https://github.com/nikgapps/project/blob/main/NikGapps/build/NikGappsManager.py"
    click BuildLogic "https://github.com/nikgapps/project/blob/main/NikGapps/build/Build.py"
    click OverlaysController "https://github.com/nikgapps/project/blob/main/NikGapps/build/NikGappsOverlays.py"
    click ReleaseSlicing "https://github.com/nikgapps/project/blob/main/NikGapps/build/Release.py"
    click PackageConstants "https://github.com/nikgapps/project/blob/main/NikGapps/build/PackageConstants.py"
    click CompressionOps "https://github.com/nikgapps/project/blob/main/NikGapps/helper/compression/CompOps.py"
    click CompressionExport "https://github.com/nikgapps/project/blob/main/NikGapps/helper/compression/Export.py"
    click AssetScripts "https://github.com/nikgapps/project/tree/main/NikGapps/helper/assets/"
    click GitInterface "https://github.com/nikgapps/project/blob/main/NikGapps/helper/git/TestGit.py"
    click Overlay "https://github.com/nikgapps/project/blob/main/NikGapps/helper/overlay/Overlay.py"
    click ApkMetaInfo "https://github.com/nikgapps/project/blob/main/NikGapps/helper/overlay/ApkMetaInfo.py"
    click Manifest "https://github.com/nikgapps/project/blob/main/NikGapps/helper/overlay/Manifest.py"
    click Resources "https://github.com/nikgapps/project/blob/main/NikGapps/helper/overlay/Resources.py"
    click String "https://github.com/nikgapps/project/blob/main/NikGapps/helper/overlay/String.py"
    click StringArray "https://github.com/nikgapps/project/blob/main/NikGapps/helper/overlay/StringArray.py"
    click Library "https://github.com/nikgapps/project/blob/main/NikGapps/helper/overlay/Library.py"
    click Bool "https://github.com/nikgapps/project/blob/main/NikGapps/helper/overlay/Bool.py"
    click AppSet "https://github.com/nikgapps/project/blob/main/NikGapps/helper/AppSet.py"
    click PackageUtil "https://github.com/nikgapps/project/blob/main/NikGapps/helper/Package.py"
    click ConfigUtil "https://github.com/nikgapps/project/blob/main/NikGapps/helper/Config.py"
    click ConfigObj "https://github.com/nikgapps/project/blob/main/NikGapps/helper/ConfigObj.py"
    click ArgsUtil "https://github.com/nikgapps/project/blob/main/NikGapps/helper/Args.py"
    click AssetsUtil "https://github.com/nikgapps/project/blob/main/NikGapps/helper/Assets.py"
    click CacheStore "https://github.com/nikgapps/project/blob/main/NikGapps/cache.py"
    click CacheStore "https://github.com/nikgapps/project/blob/main/NikGapps/copy_repos.py"
    click Test1 "https://github.com/nikgapps/project/blob/main/NikGapps/test.py"
    click Test2 "https://github.com/nikgapps/project/blob/main/test.py"
```
