# daozhang66/python_runner architecture

> Architecture diagram of the GitHub repository daozhang66/python_runner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/daozhang66/python_runner
- Repository: https://github.com/daozhang66/python_runner

## Overview

Python Runner is a Flutter Android app for organizing and editing Python scripts, running them in an interactive terminal, managing packages across two Python runtimes, and inspecting script network activity. The main workflow starts in the script workspace or editor, passes execution requests through the Flutter execution layer and native bridge, then runs them through Chaquopy or the Linux-like environment and streams output back to the console. Separate branches cover project files, package management, request overrides and inspection, and diagnostics. README capabilities supplement the sampled runtime excerpts; wiring for unsampled Flutter and Android components is shown only where documented or supported by the repository structure.

Main entry points: [`android/app/src/main/kotlin/com/daozhang/py/ScriptExecutionController.kt`](https://github.com/daozhang66/python_runner/blob/main/android/app/src/main/kotlin/com/daozhang/py/ScriptExecutionController.kt) (Script execution), [`lib/features/scripts/application/script_workspace_controller.dart`](https://github.com/daozhang66/python_runner/blob/main/lib/features/scripts/application/script_workspace_controller.dart) (Workspace controller), [`lib/features/scripts/presentation/pages`](https://github.com/daozhang66/python_runner/tree/main/lib/features/scripts/presentation/pages) (Script pages), [`lib/features/scripts/presentation/pages/script_editor_page.dart`](https://github.com/daozhang66/python_runner/blob/main/lib/features/scripts/presentation/pages/script_editor_page.dart) (Code editor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["App interface"]
  node_app["Flutter app<br/>[main.dart]"]
  node_script_pages["Script pages"]
  node_editor["Code editor"]
  node_console["Run console"]
end

subgraph group_scripts["Script workspace"]
  node_workspace["Workspace controller"]
  node_script_repo["Script repository"]
  node_project_service["Project service"]
  node_project_store["Project files"]
end

subgraph group_execution["Execution runtime"]
  node_execution_repo["Execution repository"]
  node_execution_provider["Execution state"]
  node_native_bridge["Native bridge<br/>[native_bridge.dart]"]
  node_android_entry["Android channel entry<br/>[MainActivity.kt]"]
  node_script_controller["Script execution"]
  node_runtime_manager["Runtime manager"]
  node_chaquopy["Chaquopy backend"]
  node_linux_backend["Linux-like backend"]
  node_linux_manager["Linux environment"]
  node_python_runner["Python runner<br/>[script_runner.py]"]
  node_foreground["Foreground service"]
end

subgraph group_packages["Runtime packages"]
  node_package_ui["Package manager UI"]
  node_package_controller["Package controller"]
  node_chaquopy_packages["Chaquopy packages"]
  node_linux_packages["Linux-like packages"]
end

subgraph group_diagnostics["Network diagnostics"]
  node_network_ui["Network inspector"]
  node_network_repo["Inspector repository"]
  node_network_store[("Request store")]
  node_http_hook["HTTP debug hook<br/>[http_debug_hook.py]"]
  node_override_config["Override config"]
  node_logs["App logs<br/>[app_logs_page.dart]"]
  node_database[("App database")]
end

node_user(("App user"))
node_pypi(("Package index"))

node_user -->|"uses"| node_app
node_app -->|"opens"| node_script_pages
node_script_pages -->|"manages scripts"| node_workspace
node_workspace -->|"loads and saves"| node_script_repo
node_workspace -->|"manages projects"| node_project_service
node_project_service -->|"accesses project files"| node_project_store
node_script_pages -->|"edits scripts"| node_editor
node_editor -->|"saves and runs"| node_workspace
node_editor -->|"opens execution"| node_console
node_console -->|"controls run"| node_execution_provider
node_execution_provider -->|"requests execution"| node_execution_repo
node_execution_repo -->|"sends commands"| node_native_bridge
node_native_bridge -->|"invokes channel"| node_android_entry
node_android_entry -->|"dispatches execution"| node_script_controller
node_script_controller -->|"selects runtime"| node_runtime_manager
node_runtime_manager -->|"runs with"| node_chaquopy
node_runtime_manager -->|"runs with"| node_linux_backend
node_linux_backend -->|"uses environment"| node_linux_manager
node_script_controller -->|"executes script"| node_python_runner
node_script_controller -->|"starts service"| node_foreground
node_script_controller -->|"streams results"| node_execution_provider
node_user -->|"manages packages"| node_package_ui
node_package_ui -->|"submits package actions"| node_package_controller
node_package_controller -->|"dispatches Chaquopy"| node_chaquopy_packages
node_package_controller -->|"dispatches Linux-like"| node_linux_packages
node_chaquopy_packages -.->|"installs packages"| node_pypi
node_linux_packages -.->|"installs packages"| node_pypi
node_user -->|"inspects requests"| node_network_ui
node_network_ui -->|"queries records"| node_network_repo
node_network_repo -->|"reads records"| node_network_store
node_python_runner -->|"initializes hook"| node_http_hook
node_http_hook -->|"emits request records"| node_network_store
node_override_config -->|"configures overrides"| node_http_hook
node_user -->|"views diagnostics"| node_logs
node_logs -->|"reads logs"| node_database

click node_app "https://github.com/daozhang66/python_runner/blob/main/lib/main.dart"
click node_script_pages "https://github.com/daozhang66/python_runner/tree/main/lib/features/scripts/presentation/pages"
click node_editor "https://github.com/daozhang66/python_runner/blob/main/lib/features/scripts/presentation/pages/script_editor_page.dart"
click node_console "https://github.com/daozhang66/python_runner/blob/main/lib/features/console/presentation/pages/run_console_page.dart"
click node_workspace "https://github.com/daozhang66/python_runner/blob/main/lib/features/scripts/application/script_workspace_controller.dart"
click node_script_repo "https://github.com/daozhang66/python_runner/blob/main/lib/features/scripts/application/script_repository.dart"
click node_project_service "https://github.com/daozhang66/python_runner/blob/main/lib/services/script_project_service.dart"
click node_project_store "https://github.com/daozhang66/python_runner/blob/main/android/app/src/main/kotlin/com/daozhang/py/ScriptProjectStore.kt"
click node_execution_repo "https://github.com/daozhang66/python_runner/blob/main/lib/features/console/application/execution_repository.dart"
click node_execution_provider "https://github.com/daozhang66/python_runner/blob/main/lib/providers/execution_provider.dart"
click node_native_bridge "https://github.com/daozhang66/python_runner/blob/main/lib/services/native_bridge.dart"
click node_android_entry "https://github.com/daozhang66/python_runner/blob/main/android/app/src/main/kotlin/com/daozhang/py/MainActivity.kt"
click node_script_controller "https://github.com/daozhang66/python_runner/blob/main/android/app/src/main/kotlin/com/daozhang/py/ScriptExecutionController.kt"
click node_runtime_manager "https://github.com/daozhang66/python_runner/blob/main/lib/runtime/runtime_manager.dart"
click node_chaquopy "https://github.com/daozhang66/python_runner/blob/main/lib/runtime/chaquopy_backend.dart"
click node_linux_backend "https://github.com/daozhang66/python_runner/blob/main/lib/runtime/linux_like_backend.dart"
click node_linux_manager "https://github.com/daozhang66/python_runner/blob/main/android/app/src/main/kotlin/com/daozhang/py/LinuxLikeRuntimeManager.kt"
click node_python_runner "https://github.com/daozhang66/python_runner/blob/main/android/app/src/main/python/script_runner.py"
click node_foreground "https://github.com/daozhang66/python_runner/blob/main/android/app/src/main/kotlin/com/daozhang/py/PythonForegroundService.kt"
click node_package_ui "https://github.com/daozhang66/python_runner/blob/main/lib/pages/package_manager_page.dart"
click node_package_controller "https://github.com/daozhang66/python_runner/blob/main/lib/features/packages/application/package_controller.dart"
click node_chaquopy_packages "https://github.com/daozhang66/python_runner/blob/main/android/app/src/main/kotlin/com/daozhang/py/ChaquopyPackageController.kt"
click node_linux_packages "https://github.com/daozhang66/python_runner/blob/main/android/app/src/main/kotlin/com/daozhang/py/LinuxLikePackageController.kt"
click node_network_ui "https://github.com/daozhang66/python_runner/blob/main/lib/pages/network_inspector_page.dart"
click node_network_repo "https://github.com/daozhang66/python_runner/blob/main/lib/features/network/application/network_inspector_repository.dart"
click node_network_store "https://github.com/daozhang66/python_runner/blob/main/lib/services/http_inspector_store.dart"
click node_http_hook "https://github.com/daozhang66/python_runner/blob/main/android/app/src/main/python/http_debug_hook.py"
click node_override_config "https://github.com/daozhang66/python_runner/blob/main/lib/services/request_override_config.dart"
click node_logs "https://github.com/daozhang66/python_runner/blob/main/lib/pages/app_logs_page.dart"
click node_database "https://github.com/daozhang66/python_runner/blob/main/lib/services/database_service.dart"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_script_pages,node_editor,node_console,node_user toneBlue
class node_workspace,node_script_repo,node_project_service,node_project_store toneAmber
class node_execution_repo,node_execution_provider,node_native_bridge,node_android_entry,node_script_controller,node_runtime_manager,node_chaquopy,node_linux_backend,node_linux_manager,node_python_runner,node_foreground toneMint
class node_package_ui,node_package_controller,node_chaquopy_packages,node_linux_packages toneRose
class node_network_ui,node_network_repo,node_network_store,node_http_hook,node_override_config,node_logs,node_database,node_pypi toneIndigo
```

## Components

### App interface

- [Flutter app](https://github.com/daozhang66/python_runner/blob/main/lib/main.dart): `lib/main.dart`
- [Script pages](https://github.com/daozhang66/python_runner/tree/main/lib/features/scripts/presentation/pages): `lib/features/scripts/presentation/pages`
- [Code editor](https://github.com/daozhang66/python_runner/blob/main/lib/features/scripts/presentation/pages/script_editor_page.dart): `lib/features/scripts/presentation/pages/script_editor_page.dart`
- [Run console](https://github.com/daozhang66/python_runner/blob/main/lib/features/console/presentation/pages/run_console_page.dart): `lib/features/console/presentation/pages/run_console_page.dart`

### Script workspace

- [Workspace controller](https://github.com/daozhang66/python_runner/blob/main/lib/features/scripts/application/script_workspace_controller.dart): `lib/features/scripts/application/script_workspace_controller.dart`
- [Script repository](https://github.com/daozhang66/python_runner/blob/main/lib/features/scripts/application/script_repository.dart): `lib/features/scripts/application/script_repository.dart`
- [Project service](https://github.com/daozhang66/python_runner/blob/main/lib/services/script_project_service.dart): `lib/services/script_project_service.dart`
- [Project files](https://github.com/daozhang66/python_runner/blob/main/android/app/src/main/kotlin/com/daozhang/py/ScriptProjectStore.kt): `android/app/src/main/kotlin/com/daozhang/py/ScriptProjectStore.kt`

### Execution runtime

- [Execution repository](https://github.com/daozhang66/python_runner/blob/main/lib/features/console/application/execution_repository.dart): `lib/features/console/application/execution_repository.dart`
- [Execution state](https://github.com/daozhang66/python_runner/blob/main/lib/providers/execution_provider.dart): `lib/providers/execution_provider.dart`
- [Native bridge](https://github.com/daozhang66/python_runner/blob/main/lib/services/native_bridge.dart): `lib/services/native_bridge.dart`
- [Android channel entry](https://github.com/daozhang66/python_runner/blob/main/android/app/src/main/kotlin/com/daozhang/py/MainActivity.kt): `android/app/src/main/kotlin/com/daozhang/py/MainActivity.kt`
- [Script execution](https://github.com/daozhang66/python_runner/blob/main/android/app/src/main/kotlin/com/daozhang/py/ScriptExecutionController.kt): `android/app/src/main/kotlin/com/daozhang/py/ScriptExecutionController.kt`
- [Runtime manager](https://github.com/daozhang66/python_runner/blob/main/lib/runtime/runtime_manager.dart): `lib/runtime/runtime_manager.dart`
- [Chaquopy backend](https://github.com/daozhang66/python_runner/blob/main/lib/runtime/chaquopy_backend.dart): `lib/runtime/chaquopy_backend.dart`
- [Linux-like backend](https://github.com/daozhang66/python_runner/blob/main/lib/runtime/linux_like_backend.dart): `lib/runtime/linux_like_backend.dart`
- [Linux environment](https://github.com/daozhang66/python_runner/blob/main/android/app/src/main/kotlin/com/daozhang/py/LinuxLikeRuntimeManager.kt): `android/app/src/main/kotlin/com/daozhang/py/LinuxLikeRuntimeManager.kt`
- [Python runner](https://github.com/daozhang66/python_runner/blob/main/android/app/src/main/python/script_runner.py): `android/app/src/main/python/script_runner.py`
- [Foreground service](https://github.com/daozhang66/python_runner/blob/main/android/app/src/main/kotlin/com/daozhang/py/PythonForegroundService.kt): `android/app/src/main/kotlin/com/daozhang/py/PythonForegroundService.kt`

### Runtime packages

- [Package manager UI](https://github.com/daozhang66/python_runner/blob/main/lib/pages/package_manager_page.dart): `lib/pages/package_manager_page.dart`
- [Package controller](https://github.com/daozhang66/python_runner/blob/main/lib/features/packages/application/package_controller.dart): `lib/features/packages/application/package_controller.dart`
- [Chaquopy packages](https://github.com/daozhang66/python_runner/blob/main/android/app/src/main/kotlin/com/daozhang/py/ChaquopyPackageController.kt): `android/app/src/main/kotlin/com/daozhang/py/ChaquopyPackageController.kt`
- [Linux-like packages](https://github.com/daozhang66/python_runner/blob/main/android/app/src/main/kotlin/com/daozhang/py/LinuxLikePackageController.kt): `android/app/src/main/kotlin/com/daozhang/py/LinuxLikePackageController.kt`

### Network diagnostics

- [Network inspector](https://github.com/daozhang66/python_runner/blob/main/lib/pages/network_inspector_page.dart): `lib/pages/network_inspector_page.dart`
- [Inspector repository](https://github.com/daozhang66/python_runner/blob/main/lib/features/network/application/network_inspector_repository.dart): `lib/features/network/application/network_inspector_repository.dart`
- [Request store](https://github.com/daozhang66/python_runner/blob/main/lib/services/http_inspector_store.dart): `lib/services/http_inspector_store.dart`
- [HTTP debug hook](https://github.com/daozhang66/python_runner/blob/main/android/app/src/main/python/http_debug_hook.py): `android/app/src/main/python/http_debug_hook.py`
- [Override config](https://github.com/daozhang66/python_runner/blob/main/lib/services/request_override_config.dart): `lib/services/request_override_config.dart`
- [App logs](https://github.com/daozhang66/python_runner/blob/main/lib/pages/app_logs_page.dart): `lib/pages/app_logs_page.dart`
- [App database](https://github.com/daozhang66/python_runner/blob/main/lib/services/database_service.dart): `lib/services/database_service.dart`

### Other components

- **App user**
- **Package index**

## Connections

- App user → Flutter app: uses
- Flutter app → Script pages: opens
- Script pages → Workspace controller: manages scripts
- Workspace controller → Script repository: loads and saves
- Workspace controller → Project service: manages projects
- Project service → Project files: accesses project files
- Script pages → Code editor: edits scripts
- Code editor → Workspace controller: saves and runs
- Code editor → Run console: opens execution
- Run console → Execution state: controls run
- Execution state → Execution repository: requests execution
- Execution repository → Native bridge: sends commands
- Native bridge → Android channel entry: invokes channel
- Android channel entry → Script execution: dispatches execution
- Script execution → Runtime manager: selects runtime
- Runtime manager → Chaquopy backend: runs with
- Runtime manager → Linux-like backend: runs with
- Linux-like backend → Linux environment: uses environment
- Script execution → Python runner: executes script
- Script execution → Foreground service: starts service
- Script execution → Execution state: streams results
- App user → Package manager UI: manages packages
- Package manager UI → Package controller: submits package actions
- Package controller → Chaquopy packages: dispatches Chaquopy
- Package controller → Linux-like packages: dispatches Linux-like
- Chaquopy packages → Package index: installs packages
- Linux-like packages → Package index: installs packages
- App user → Network inspector: inspects requests
- Network inspector → Inspector repository: queries records
- Inspector repository → Request store: reads records
- Python runner → HTTP debug hook: initializes hook
- HTTP debug hook → Request store: emits request records
- Override config → HTTP debug hook: configures overrides
- App user → App logs: views diagnostics
- App logs → App database: reads logs