# sunilnull/python-for-android architecture

> Architecture diagram of the GitHub repository sunilnull/python-for-android, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sunilnull/python-for-android
- Repository: https://github.com/sunilnull/python-for-android

## Overview

##### Project Type and Purpose
- This is a CLI-based packaging tool (“python-for-android”) that builds and bundles Python applications into Android APKs.
- It orchestrates a recipe-based build system, cross‐compiles Python modules and native libraries against the Android NDK, and assembles them with chosen bootstraps (SDL2, WebView, Service, etc.) into a final APK.

##### Key Top‐Level Components (from file tree)
- CLI Entrypoint: `p4a` script via `entrypoints.py` and main modules (`build.py`, `distribution.py`, `toolchain.py`).
- Core Library: `pythonforandroid/` contains sub‐packages:
- `recipe.py`, `graph.py`, `pythonpackage.py`, `patching.py`, `archs.py`, `util.py`, `logger.py`
- `recipes/`: directory of individual build “recipes” (one per dependency).
- `bootstraps/`: templates & code for different Android app backends.
- `tools/`: helper utilities for binary linking (`biglink`, `liblink.sh`).
- Configuration & CI:
- Dockerfile, Makefile, `.travis.yml`, GitHub Actions workflow, `.deepsource.toml`.
- Documentation: `doc/` (Sphinx sources and custom theme).
- Tests: `tests/` and `testapps/`.

##### Relationships and Data Flow
- User invokes `p4a` CLI → parses arguments (e.g., requirements, bootstrap choice) → calls into `distribution.py` / `build.py`.
- The graph engine (`graph.py`) builds a dependency DAG of requested recipes.
- For each recipe:
- `recipe.py` defines metadata (source, configure/build steps).
- `toolchain.py` orchestrates cross‐compilation using the Android NDK, C/C++ toolchain, JNI helpers.
- Patches / source manipulations via `patching.py`.
- Intermediate artifacts (compiled .so, Python stdlib, site-packages) → packaged by `pythonpackage.py`.
- Bootstrap templates from `bootstraps/` are populated with assets and launchers (Java/Gradle, AndroidManifest templates) → assembled alongside compiled libraries.
- Final packaging step invokes the Android SDK/Gradle (or Ant) to produce a signed APK.

##### Important Architectural Patterns & Design Principles
- Modular “recipe” pattern: each dependency is encapsulated in its own recipe directory, enabling parallel builds and easy extension.
- Graph-based dependency resolution: recipe graph ensures correct build order.
- Separation of concerns:
- CLI & argument parsing
- Dependency graph resolution
- Recipe build logic
- Toolchain invocation (compiler, linker)
- Packaging & distribution
- Pluggable bootstraps: allows multiple app backends with shared build machinery.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Main Workflow
    P4A["p4a CLI Entrypoint"]:::core
    ArgParser["Argument Parser & Dispatcher"]:::core
    GraphBuilder["Dependency Graph Builder"]:::core
    RecipeManager["Recipe Manager"]:::core
    Toolchain["Toolchain Coordinator"]:::core
    Intermediate(("Intermediate Artifacts (.so, site-packages)")):::artifact
    PackageBuilder["Python Package Builder"]:::core
    Bootstrap["Bootstrap Templates"]:::template
    SDKTools["Android SDK/NDK & Build Tools Interface"]:::external
    APKPackager["Final APK Packager"]:::core
    APKOutput["Signed APK (.apk)"]:::output

    %% External Systems and File System
    FS[/"File System (recipes, patches, templates)"/]:::external
    NDK(("Android NDK Toolchain")):::external
    SDK[/"Android SDK / Gradle / Ant"/]:::external

    %% Workflow Connections
    P4A --> ArgParser
    ArgParser --> GraphBuilder
    GraphBuilder --> RecipeManager
    RecipeManager --> Toolchain
    Toolchain --> Intermediate
    Intermediate --> PackageBuilder
    PackageBuilder --> Bootstrap
    Bootstrap --> APKPackager
    APKPackager --> APKOutput

    %% Toolchain ↔ NDK
    Toolchain --> NDK
    NDK --> Toolchain

    %% APK Packager ↔ SDK
    APKPackager --> SDK
    SDK --> APKPackager

    %% FS connections
    FS --> RecipeManager
    FS --> Bootstrap

    %% Legend
    subgraph Legend
        direction LR
        C1["Rectangle: Internal Component"]:::core
        C2["Rectangle: Templates & Assets"]:::template
        C3["Rectangle: External Tool/Service"]:::external
        C4["Cylinder: Intermediate Artifact Store"]:::artifact
        C5["Rectangle: Final Output"]:::output
    end

    %% Click Events
    click P4A "https://github.com/sunilnull/python-for-android/blob/develop/pythonforandroid/entrypoints.py"
    click ArgParser "https://github.com/sunilnull/python-for-android/blob/develop/pythonforandroid/distribution.py"
    click ArgParser "https://github.com/sunilnull/python-for-android/blob/develop/pythonforandroid/build.py"
    click GraphBuilder "https://github.com/sunilnull/python-for-android/blob/develop/pythonforandroid/graph.py"
    click RecipeManager "https://github.com/sunilnull/python-for-android/blob/develop/pythonforandroid/recipe.py"
    click RecipeManager "https://github.com/sunilnull/python-for-android/tree/develop/pythonforandroid/recipes/"
    click Toolchain "https://github.com/sunilnull/python-for-android/blob/develop/pythonforandroid/toolchain.py"
    click PackageBuilder "https://github.com/sunilnull/python-for-android/blob/develop/pythonforandroid/pythonpackage.py"
    click Bootstrap "https://github.com/sunilnull/python-for-android/tree/develop/pythonforandroid/bootstraps/"
    click SDKTools "https://github.com/sunilnull/python-for-android/tree/develop/pythonforandroid/tools/"
    click APKPackager "https://github.com/sunilnull/python-for-android/blob/develop/pythonforandroid/bdistapk.py"

    %% Styles
    classDef core fill:#D0E1F9,stroke:#1F618D,stroke-width:1px
    classDef external fill:#FDEBD0,stroke:#D35400,stroke-width:1px
    classDef template fill:#D5F5E3,stroke:#27AE60,stroke-width:1px
    classDef output fill:#FCF3CF,stroke:#B7950B,stroke-width:1px
    classDef artifact fill:#F4ECF7,stroke:#8E44AD,stroke-width:1px
```
