# kandoraq/miauterm architecture

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

- Interactive diagram: https://gitdiagram.com/kandoraq/miauterm
- Repository: https://github.com/kandoraq/miauterm

## Overview

Miauterm is an experimental Android terminal that runs Debian 13 ARM64 in PRoot. Users start the app, initialize or reuse the Debian root filesystem, launch shell sessions, and interact through terminal views; settings and file browsing provide adjacent workflows. The graph also preserves documented backup/restore, optional Android-folder sharing, themes, extra keys, and app-command access. Source excerpts establish selected wiring; broader runtime capabilities and constraints are taken from the README, so unsampled implementation details and links are omitted rather than inferred.

Main entry points: [`app/src/main/java/org/cortex/terminal/runtime/DebianRuntime.kt`](https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/runtime/DebianRuntime.kt) (Debian setup), [`app/src/main/java/org/cortex/terminal/MainActivity.kt`](https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/MainActivity.kt) (Terminal screen), [`app/src/main/java/org/cortex/terminal/SettingsActivity.kt`](https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/SettingsActivity.kt) (Settings), [`app/src/main/java/org/cortex/terminal/session/TerminalSession.kt`](https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/session/TerminalSession.kt) (PTY session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Android app"]
  node_main["Terminal screen<br/>[MainActivity.kt]"]
  node_settings["Settings"]
  node_files["Linux file browser"]
  node_chrome["Theme styling<br/>[Chrome.kt]"]
end

subgraph group_runtime["Debian runtime"]
  node_runtime["Debian setup<br/>[DebianRuntime.kt]"]
  node_environment["Runtime environment<br/>[Environment.kt]"]
  node_installer["Safe installation<br/>[FileInstaller.kt]"]
  node_patcher["ELF linker patching"]
  node_backup["Backup and restore<br/>[DebianBackup.kt]"]
end

subgraph group_sessions["Terminal sessions"]
  node_sessionmanager["Session manager<br/>[SessionManager.kt]"]
  node_session["PTY session<br/>[TerminalSession.kt]"]
  node_store[("Saved sessions<br/>[SessionStore.kt]")]
end

subgraph group_engine["Terminal engine"]
  node_emulator["Terminal emulator"]
  node_search["Terminal search<br/>[TerminalSearch.kt]"]
  node_pty["Native PTY<br/>[cortex-pty.c]"]
  node_fse["FSE codec<br/>[fse.h]"]
  node_zstd["Zstd decompressor<br/>[zstd_decompress.c]"]
end

subgraph group_integration["App integrations"]
  node_service["Foreground service<br/>[CortexService.kt]"]
  node_api["App command API<br/>[ApiCommands.kt]"]
  node_localservers["Local servers<br/>[LocalServers.kt]"]
end

node_user(("Android user"))
node_debian(("Debian shell"))
node_androidfolders[("Android folders")]

node_user -->|"opens"| node_main
node_main -->|"starts"| node_service
node_main -->|"gets manager"| node_sessionmanager
node_main -->|"prepares runtime"| node_runtime
node_main -->|"opens browser"| node_files
node_main -.->|"opens settings"| node_settings
node_settings -->|"exports backup"| node_backup
node_settings -->|"runs operations"| node_runtime
node_settings -->|"styles dialogs"| node_chrome
node_main -->|"uses theme"| node_chrome
node_runtime -->|"provides paths"| node_environment
node_runtime -->|"installs files"| node_installer
node_runtime -->|"patches linkers"| node_patcher
node_runtime -.->|"unpacks rootfs"| node_zstd
node_runtime -.->|"shares selected"| node_androidfolders
node_sessionmanager -->|"creates sessions"| node_session
node_sessionmanager -->|"saves state"| node_store
node_session -->|"launches Debian"| node_runtime
node_session -->|"feeds terminal data"| node_emulator
node_session -->|"starts PTY"| node_pty
node_search -->|"searches buffer"| node_emulator
node_debian -.->|"invokes commands"| node_api
node_service -->|"starts API"| node_api
node_service -->|"starts servers"| node_localservers
node_fse -.->|"decodes entropy"| node_zstd

click node_main "https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/MainActivity.kt"
click node_settings "https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/SettingsActivity.kt"
click node_files "https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/DebianFilesActivity.kt"
click node_chrome "https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/view/Chrome.kt"
click node_runtime "https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/runtime/DebianRuntime.kt"
click node_environment "https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/runtime/Environment.kt"
click node_installer "https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/runtime/FileInstaller.kt"
click node_patcher "https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/runtime/ElfLinkerPatcher.kt"
click node_backup "https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/runtime/DebianBackup.kt"
click node_sessionmanager "https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/session/SessionManager.kt"
click node_session "https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/session/TerminalSession.kt"
click node_store "https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/session/SessionStore.kt"
click node_emulator "https://github.com/kandoraq/miauterm/blob/main/core/terminal-engine/src/main/java/org/cortex/terminal/emulator/TerminalEmulator.kt"
click node_search "https://github.com/kandoraq/miauterm/blob/main/core/terminal-engine/src/main/java/org/cortex/terminal/emulator/TerminalSearch.kt"
click node_pty "https://github.com/kandoraq/miauterm/blob/main/core/terminal-engine/src/main/cpp/cortex-pty.c"
click node_fse "https://github.com/kandoraq/miauterm/blob/main/core/terminal-engine/src/main/cpp/zstd/common/fse.h"
click node_zstd "https://github.com/kandoraq/miauterm/blob/main/core/terminal-engine/src/main/cpp/zstd/decompress/zstd_decompress.c"
click node_service "https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/service/CortexService.kt"
click node_api "https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/api/ApiCommands.kt"
click node_localservers "https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/service/LocalServers.kt"

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_main,node_settings,node_files,node_chrome,node_user toneBlue
class node_runtime,node_environment,node_installer,node_patcher,node_backup,node_androidfolders toneAmber
class node_sessionmanager,node_session,node_store toneMint
class node_emulator,node_search,node_pty,node_fse,node_zstd toneRose
class node_service,node_api,node_localservers,node_debian toneIndigo
```

## Components

### Android app

- [Terminal screen](https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/MainActivity.kt): `app/src/main/java/org/cortex/terminal/MainActivity.kt`
- [Settings](https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/SettingsActivity.kt): `app/src/main/java/org/cortex/terminal/SettingsActivity.kt`
- [Linux file browser](https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/DebianFilesActivity.kt): `app/src/main/java/org/cortex/terminal/DebianFilesActivity.kt`
- [Theme styling](https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/view/Chrome.kt): `app/src/main/java/org/cortex/terminal/view/Chrome.kt`

### Debian runtime

- [Debian setup](https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/runtime/DebianRuntime.kt): `app/src/main/java/org/cortex/terminal/runtime/DebianRuntime.kt`
- [Runtime environment](https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/runtime/Environment.kt): `app/src/main/java/org/cortex/terminal/runtime/Environment.kt`
- [Safe installation](https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/runtime/FileInstaller.kt): `app/src/main/java/org/cortex/terminal/runtime/FileInstaller.kt`
- [ELF linker patching](https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/runtime/ElfLinkerPatcher.kt): `app/src/main/java/org/cortex/terminal/runtime/ElfLinkerPatcher.kt`
- [Backup and restore](https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/runtime/DebianBackup.kt): `app/src/main/java/org/cortex/terminal/runtime/DebianBackup.kt`

### Terminal sessions

- [Session manager](https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/session/SessionManager.kt): `app/src/main/java/org/cortex/terminal/session/SessionManager.kt`
- [PTY session](https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/session/TerminalSession.kt): `app/src/main/java/org/cortex/terminal/session/TerminalSession.kt`
- [Saved sessions](https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/session/SessionStore.kt): `app/src/main/java/org/cortex/terminal/session/SessionStore.kt`

### Terminal engine

- [Terminal emulator](https://github.com/kandoraq/miauterm/blob/main/core/terminal-engine/src/main/java/org/cortex/terminal/emulator/TerminalEmulator.kt): `core/terminal-engine/src/main/java/org/cortex/terminal/emulator/TerminalEmulator.kt`
- [Terminal search](https://github.com/kandoraq/miauterm/blob/main/core/terminal-engine/src/main/java/org/cortex/terminal/emulator/TerminalSearch.kt): `core/terminal-engine/src/main/java/org/cortex/terminal/emulator/TerminalSearch.kt`
- [Native PTY](https://github.com/kandoraq/miauterm/blob/main/core/terminal-engine/src/main/cpp/cortex-pty.c): `core/terminal-engine/src/main/cpp/cortex-pty.c`
- [FSE codec](https://github.com/kandoraq/miauterm/blob/main/core/terminal-engine/src/main/cpp/zstd/common/fse.h): `core/terminal-engine/src/main/cpp/zstd/common/fse.h`
- [Zstd decompressor](https://github.com/kandoraq/miauterm/blob/main/core/terminal-engine/src/main/cpp/zstd/decompress/zstd_decompress.c): `core/terminal-engine/src/main/cpp/zstd/decompress/zstd_decompress.c`

### App integrations

- [Foreground service](https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/service/CortexService.kt): `app/src/main/java/org/cortex/terminal/service/CortexService.kt`
- [App command API](https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/api/ApiCommands.kt): `app/src/main/java/org/cortex/terminal/api/ApiCommands.kt`
- [Local servers](https://github.com/kandoraq/miauterm/blob/main/app/src/main/java/org/cortex/terminal/service/LocalServers.kt): `app/src/main/java/org/cortex/terminal/service/LocalServers.kt`

### Other components

- **Android user**
- **Debian shell**
- **Android folders**

## Connections

- Android user → Terminal screen: opens (evidence: `README.md`)
- Terminal screen → Foreground service: starts (evidence: `app/src/main/java/org/cortex/terminal/MainActivity.kt`)
- Terminal screen → Session manager: gets manager (evidence: `app/src/main/java/org/cortex/terminal/MainActivity.kt`)
- Terminal screen → Debian setup: prepares runtime (evidence: `app/src/main/java/org/cortex/terminal/MainActivity.kt`)
- Terminal screen → Linux file browser: opens browser (evidence: `app/src/main/java/org/cortex/terminal/MainActivity.kt`)
- Terminal screen → Settings: opens settings (evidence: `app/src/main/java/org/cortex/terminal/MainActivity.kt`)
- Settings → Backup and restore: exports backup (evidence: `app/src/main/java/org/cortex/terminal/SettingsActivity.kt`)
- Settings → Debian setup: runs operations (evidence: `app/src/main/java/org/cortex/terminal/SettingsActivity.kt`)
- Settings → Theme styling: styles dialogs (evidence: `app/src/main/java/org/cortex/terminal/SettingsActivity.kt`)
- Terminal screen → Theme styling: uses theme (evidence: `app/src/main/java/org/cortex/terminal/MainActivity.kt`)
- Debian setup → Runtime environment: provides paths (evidence: `app/src/main/java/org/cortex/terminal/runtime/Environment.kt`)
- Debian setup → Safe installation: installs files (evidence: `app/src/main/java/org/cortex/terminal/runtime/DebianRuntime.kt`)
- Debian setup → ELF linker patching: patches linkers (evidence: `app/src/main/java/org/cortex/terminal/runtime/DebianRuntime.kt`)
- Debian setup → Zstd decompressor: unpacks rootfs (evidence: `README.md`)
- Debian setup → Android folders: shares selected (evidence: `README.md`)
- Session manager → PTY session: creates sessions (evidence: `app/src/main/java/org/cortex/terminal/session/SessionManager.kt`)
- Session manager → Saved sessions: saves state (evidence: `app/src/main/java/org/cortex/terminal/session/SessionManager.kt`)
- PTY session → Debian setup: launches Debian (evidence: `app/src/main/java/org/cortex/terminal/session/TerminalSession.kt`)
- PTY session → Terminal emulator: feeds terminal data (evidence: `app/src/main/java/org/cortex/terminal/session/TerminalSession.kt`)
- PTY session → Native PTY: starts PTY
- Terminal search → Terminal emulator: searches buffer (evidence: `core/terminal-engine/src/main/java/org/cortex/terminal/emulator/TerminalSearch.kt`)
- Debian shell → App command API: invokes commands (evidence: `README.md`)
- Foreground service → App command API: starts API (evidence: `app/src/main/java/org/cortex/terminal/service/CortexService.kt`)
- Foreground service → Local servers: starts servers (evidence: `app/src/main/java/org/cortex/terminal/service/CortexService.kt`)
- FSE codec → Zstd decompressor: decodes entropy (evidence: `core/terminal-engine/src/main/cpp/zstd/decompress/zstd_decompress.c`)