# synccatcode/miauterm architecture

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

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

## Overview

Miauterm is an experimental Android terminal running Debian 13 ARM64 under PRoot. The main user workflow is first-run rootfs installation, then opening a terminal session that launches Debian through a PTY and displays the shell in the terminal UI. Separate branches cover session restore, Linux file management, backup/reset and settings, and optional app commands/local services. The graph uses README statements and the supplied excerpts/index; unsampled subsystem details and links are kept conservative.

Main entry points: [`app/src/main/java/org/cortex/terminal/MainActivity.kt`](https://github.com/synccatcode/miauterm/blob/main/app/src/main/java/org/cortex/terminal/MainActivity.kt) (Terminal screen), [`app/src/main/java/org/cortex/terminal/session/TerminalSession.kt`](https://github.com/synccatcode/miauterm/blob/main/app/src/main/java/org/cortex/terminal/session/TerminalSession.kt) (Debian session), [`app/src/main/java/org/cortex/terminal/service/CortexService.kt`](https://github.com/synccatcode/miauterm/blob/main/app/src/main/java/org/cortex/terminal/service/CortexService.kt) (Foreground service), [`app/src/main/java/org/cortex/terminal/api/ApiCommands.kt`](https://github.com/synccatcode/miauterm/blob/main/app/src/main/java/org/cortex/terminal/api/ApiCommands.kt) (miauterm-cmd actions)

## Diagram (Mermaid)

```mermaid
flowchart TD

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

subgraph group_runtime["Debian runtime"]
  node_debian_runtime["Debian installer<br/>[DebianRuntime.kt]"]
  node_environment["Runtime environment<br/>[Environment.kt]"]
  node_elf_patcher["ELF linker patching"]
  node_backup["Backup and restore<br/>[DebianBackup.kt]"]
end

subgraph group_sessions["Terminal sessions"]
  node_session_manager["Session manager<br/>[SessionManager.kt]"]
  node_session_store[("Saved sessions<br/>[SessionStore.kt]")]
  node_terminal_session["Debian session<br/>[TerminalSession.kt]"]
  node_terminal_ui["Terminal view<br/>[TerminalView.kt]"]
end

subgraph group_engine["Terminal engine"]
  node_emulator["Terminal emulator"]
  node_pty_process["PTY process<br/>[PtyProcess.kt]"]
  node_pty_native["Native PTY<br/>[PtyNative.kt]"]
end

subgraph group_integration["App integrations"]
  node_service["Foreground service<br/>[CortexService.kt]"]
  node_api_server["App command server<br/>[ApiServer.kt]"]
  node_api_commands["miauterm-cmd actions<br/>[ApiCommands.kt]"]
  node_local_servers["Local servers<br/>[LocalServers.kt]"]
end

node_user(("Android user"))

node_user -->|"opens terminal"| node_main
node_main -->|"starts service"| node_service
node_main -->|"gets manager"| node_session_manager
node_main -->|"ensures Debian"| node_debian_runtime
node_debian_runtime -->|"patches linkers"| node_elf_patcher
node_environment -->|"builds environment"| node_debian_runtime
node_session_manager -->|"creates sessions"| node_terminal_session
node_session_manager -->|"saves state"| node_session_store
node_terminal_session -->|"launches Debian"| node_debian_runtime
node_terminal_session -->|"reads environment"| node_environment
node_terminal_session -->|"starts PTY"| node_pty_process
node_terminal_session -->|"feeds terminal output"| node_emulator
node_pty_process -->|"uses native PTY"| node_pty_native
node_main -->|"shows terminal"| node_terminal_ui
node_main -.->|"opens settings"| node_settings
node_main -->|"opens files"| node_file_browser
node_settings -->|"exports backup"| node_backup
node_settings -->|"styles dialogs"| node_chrome
node_file_browser -->|"locates Debian files"| node_environment
node_service -->|"starts server"| node_api_server
node_service -->|"starts servers"| node_local_servers
node_user -->|"runs shell command"| node_api_commands
node_api_commands -->|"invokes app functions"| node_service
node_api_commands -->|"requests terminal actions"| node_main
node_terminal_session -->|"reports command events"| node_api_commands

click node_main "https://github.com/synccatcode/miauterm/blob/main/app/src/main/java/org/cortex/terminal/MainActivity.kt"
click node_settings "https://github.com/synccatcode/miauterm/blob/main/app/src/main/java/org/cortex/terminal/SettingsActivity.kt"
click node_file_browser "https://github.com/synccatcode/miauterm/blob/main/app/src/main/java/org/cortex/terminal/DebianFilesActivity.kt"
click node_chrome "https://github.com/synccatcode/miauterm/blob/main/app/src/main/java/org/cortex/terminal/view/Chrome.kt"
click node_debian_runtime "https://github.com/synccatcode/miauterm/blob/main/app/src/main/java/org/cortex/terminal/runtime/DebianRuntime.kt"
click node_environment "https://github.com/synccatcode/miauterm/blob/main/app/src/main/java/org/cortex/terminal/runtime/Environment.kt"
click node_elf_patcher "https://github.com/synccatcode/miauterm/blob/main/app/src/main/java/org/cortex/terminal/runtime/ElfLinkerPatcher.kt"
click node_backup "https://github.com/synccatcode/miauterm/blob/main/app/src/main/java/org/cortex/terminal/runtime/DebianBackup.kt"
click node_session_manager "https://github.com/synccatcode/miauterm/blob/main/app/src/main/java/org/cortex/terminal/session/SessionManager.kt"
click node_session_store "https://github.com/synccatcode/miauterm/blob/main/app/src/main/java/org/cortex/terminal/session/SessionStore.kt"
click node_terminal_session "https://github.com/synccatcode/miauterm/blob/main/app/src/main/java/org/cortex/terminal/session/TerminalSession.kt"
click node_terminal_ui "https://github.com/synccatcode/miauterm/blob/main/app/src/main/java/org/cortex/terminal/view/TerminalView.kt"
click node_emulator "https://github.com/synccatcode/miauterm/blob/main/core/terminal-engine/src/main/java/org/cortex/terminal/emulator/TerminalEmulator.kt"
click node_pty_process "https://github.com/synccatcode/miauterm/blob/main/core/terminal-engine/src/main/java/org/cortex/terminal/pty/PtyProcess.kt"
click node_pty_native "https://github.com/synccatcode/miauterm/blob/main/core/terminal-engine/src/main/java/org/cortex/terminal/pty/PtyNative.kt"
click node_service "https://github.com/synccatcode/miauterm/blob/main/app/src/main/java/org/cortex/terminal/service/CortexService.kt"
click node_api_server "https://github.com/synccatcode/miauterm/blob/main/app/src/main/java/org/cortex/terminal/api/ApiServer.kt"
click node_api_commands "https://github.com/synccatcode/miauterm/blob/main/app/src/main/java/org/cortex/terminal/api/ApiCommands.kt"
click node_local_servers "https://github.com/synccatcode/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_file_browser,node_chrome,node_user toneBlue
class node_debian_runtime,node_environment,node_elf_patcher,node_backup toneAmber
class node_session_manager,node_session_store,node_terminal_session,node_terminal_ui toneMint
class node_emulator,node_pty_process,node_pty_native toneRose
class node_service,node_api_server,node_api_commands,node_local_servers toneIndigo
```

## Components

### Android app

- [Terminal screen](https://github.com/synccatcode/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/synccatcode/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/synccatcode/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/synccatcode/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 installer](https://github.com/synccatcode/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/synccatcode/miauterm/blob/main/app/src/main/java/org/cortex/terminal/runtime/Environment.kt): `app/src/main/java/org/cortex/terminal/runtime/Environment.kt`
- [ELF linker patching](https://github.com/synccatcode/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/synccatcode/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/synccatcode/miauterm/blob/main/app/src/main/java/org/cortex/terminal/session/SessionManager.kt): `app/src/main/java/org/cortex/terminal/session/SessionManager.kt`
- [Saved sessions](https://github.com/synccatcode/miauterm/blob/main/app/src/main/java/org/cortex/terminal/session/SessionStore.kt): `app/src/main/java/org/cortex/terminal/session/SessionStore.kt`
- [Debian session](https://github.com/synccatcode/miauterm/blob/main/app/src/main/java/org/cortex/terminal/session/TerminalSession.kt): `app/src/main/java/org/cortex/terminal/session/TerminalSession.kt`
- [Terminal view](https://github.com/synccatcode/miauterm/blob/main/app/src/main/java/org/cortex/terminal/view/TerminalView.kt): `app/src/main/java/org/cortex/terminal/view/TerminalView.kt`

### Terminal engine

- [Terminal emulator](https://github.com/synccatcode/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`
- [PTY process](https://github.com/synccatcode/miauterm/blob/main/core/terminal-engine/src/main/java/org/cortex/terminal/pty/PtyProcess.kt): `core/terminal-engine/src/main/java/org/cortex/terminal/pty/PtyProcess.kt`
- [Native PTY](https://github.com/synccatcode/miauterm/blob/main/core/terminal-engine/src/main/java/org/cortex/terminal/pty/PtyNative.kt): `core/terminal-engine/src/main/java/org/cortex/terminal/pty/PtyNative.kt`

### App integrations

- [Foreground service](https://github.com/synccatcode/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 server](https://github.com/synccatcode/miauterm/blob/main/app/src/main/java/org/cortex/terminal/api/ApiServer.kt): `app/src/main/java/org/cortex/terminal/api/ApiServer.kt`
- [miauterm-cmd actions](https://github.com/synccatcode/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/synccatcode/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**

## Connections

- Android user → Terminal screen: opens terminal (evidence: `README.md`)
- Terminal screen → Foreground service: starts service (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 installer: ensures Debian (evidence: `app/src/main/java/org/cortex/terminal/MainActivity.kt`)
- Debian installer → ELF linker patching: patches linkers (evidence: `app/src/main/java/org/cortex/terminal/runtime/DebianRuntime.kt`)
- Runtime environment → Debian installer: builds environment (evidence: `app/src/main/java/org/cortex/terminal/runtime/Environment.kt`)
- Session manager → Debian 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`)
- Debian session → Debian installer: launches Debian (evidence: `app/src/main/java/org/cortex/terminal/session/TerminalSession.kt`)
- Debian session → Runtime environment: reads environment (evidence: `app/src/main/java/org/cortex/terminal/session/TerminalSession.kt`)
- Debian session → PTY process: starts PTY (evidence: `app/src/main/java/org/cortex/terminal/session/TerminalSession.kt`)
- Debian session → Terminal emulator: feeds terminal output (evidence: `app/src/main/java/org/cortex/terminal/session/TerminalSession.kt`)
- PTY process → Native PTY: uses native PTY (evidence: `core/terminal-engine/src/main/java/org/cortex/terminal/pty/PtyProcess.kt`)
- Terminal screen → Terminal view: shows terminal (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`)
- Terminal screen → Linux file browser: opens files (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 → Theme styling: styles dialogs (evidence: `app/src/main/java/org/cortex/terminal/SettingsActivity.kt`)
- Linux file browser → Runtime environment: locates Debian files (evidence: `app/src/main/java/org/cortex/terminal/DebianFilesActivity.kt`)
- Foreground service → App command server: starts server (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`)
- Android user → miauterm-cmd actions: runs shell command (evidence: `README.md`)
- miauterm-cmd actions → Foreground service: invokes app functions (evidence: `app/src/main/java/org/cortex/terminal/api/ApiCommands.kt`)
- miauterm-cmd actions → Terminal screen: requests terminal actions (evidence: `app/src/main/java/org/cortex/terminal/api/ApiCommands.kt`)
- Debian session → miauterm-cmd actions: reports command events (evidence: `app/src/main/java/org/cortex/terminal/session/TerminalSession.kt`)