# ssfuisu/cortex architecture

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

- Interactive diagram: https://gitdiagram.com/ssfuisu/cortex
- Repository: https://github.com/ssfuisu/cortex

## Overview

Cortex is an Android terminal app providing a native Ubuntu userspace without virtualization or root. The main workflow starts in the terminal UI, obtains a managed session, launches a shell through the PTY bridge with Cortex’s runtime environment, then parses and renders terminal output. Separate branches provide bootstrap/runtime setup, session and background-service management, search and keyboard interaction, URL opening, settings, and app updates. Some feature wiring is documented in the README but its implementation was not sampled, so those relationships are cited there.

Main entry points: [`app/src/main/java/org/cortex/terminal/MainActivity.kt`](https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/MainActivity.kt) (Main activity), [`app/src/main/java/org/cortex/terminal/view/TerminalView.kt`](https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/view/TerminalView.kt) (Terminal view), [`app/src/main/java/org/cortex/terminal/session/TerminalSession.kt`](https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/session/TerminalSession.kt) (Terminal session), [`app/src/main/java/org/cortex/terminal/emulator/TerminalBuffer.kt`](https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/emulator/TerminalBuffer.kt) (Screen and scrollback)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Terminal interface"]
  node_main["Main activity<br/>[MainActivity.kt]"]
  node_terminal_view["Terminal view<br/>[TerminalView.kt]"]
  node_extra_keys["Virtual keys<br/>[ExtraKeysView.kt]"]
  node_search_bar["Search bar"]
  node_settings["Settings"]
end

subgraph group_execution["Terminal execution"]
  node_sessions["Session manager<br/>[SessionManager.kt]"]
  node_session["Terminal session<br/>[TerminalSession.kt]"]
  node_pty_process["PTY process<br/>[PtyProcess.kt]"]
  node_pty_native["Native PTY<br/>[PtyNative.kt]"]
  node_emulator["Terminal emulator"]
  node_buffer["Screen and scrollback<br/>[TerminalBuffer.kt]"]
  node_row["Terminal rows<br/>[TerminalRow.kt]"]
  node_colors["Color schemes<br/>[TerminalColor.kt]"]
  node_search["Buffer search<br/>[TerminalSearch.kt]"]
  node_key_mapper["Key mapping<br/>[KeyMapper.kt]"]
end

subgraph group_runtime["Ubuntu runtime"]
  node_bootstrap["Ubuntu bootstrap"]
  node_environment["Runtime environment<br/>[Environment.kt]"]
  node_runtime["Runtime facade<br/>[CortexRuntime.kt]"]
  node_hook["Userspace hook<br/>[cortex-hook.c]"]
end

subgraph group_services["App services"]
  node_service["Foreground service<br/>[CortexService.kt]"]
  node_url_server["URL opener server<br/>[UrlOpenerServer.kt]"]
  node_updater["App updater<br/>[UpdateManager.kt]"]
end

node_user(("User"))
node_kernel["Android Linux kernel"]
node_release_service["Release and APK host"]

node_user -->|"uses"| node_main
node_main -->|"starts"| node_service
node_main -->|"obtains"| node_sessions
node_main -->|"configures"| node_terminal_view
node_main -->|"handles search"| node_search_bar
node_main -->|"configures"| node_extra_keys
node_main -->|"offers updates"| node_updater
node_user -->|"configures"| node_settings
node_sessions -->|"creates"| node_session
node_session -->|"launches shell"| node_pty_process
node_pty_process -->|"calls"| node_pty_native
node_pty_native -->|"creates PTY"| node_kernel
node_session -->|"feeds output"| node_emulator
node_terminal_view -->|"displays and writes"| node_session
node_emulator -->|"updates screen"| node_buffer
node_buffer -->|"stores rows"| node_row
node_buffer -->|"uses colors"| node_colors
node_terminal_view -->|"searches buffer"| node_search
node_terminal_view -->|"maps input"| node_key_mapper
node_runtime -->|"delegates setup"| node_bootstrap
node_bootstrap -->|"uses paths"| node_environment
node_session -->|"builds environment"| node_environment
node_environment -->|"sets preload"| node_hook
node_hook -->|"redirects userspace paths"| node_kernel
node_service -->|"manages sessions"| node_sessions
node_service -->|"starts"| node_url_server
node_updater -->|"checks and downloads"| node_release_service
node_user -->|"requests update"| node_updater
node_user -->|"searches scrollback"| node_terminal_view
node_user -->|"opens links and inserts images"| node_terminal_view
node_user -->|"runs native programs"| node_kernel

click node_main "https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/MainActivity.kt"
click node_terminal_view "https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/view/TerminalView.kt"
click node_extra_keys "https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/view/ExtraKeysView.kt"
click node_search_bar "https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/view/TerminalSearchBar.kt"
click node_settings "https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/SettingsActivity.kt"
click node_sessions "https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/session/SessionManager.kt"
click node_session "https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/session/TerminalSession.kt"
click node_pty_process "https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/pty/PtyProcess.kt"
click node_pty_native "https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/pty/PtyNative.kt"
click node_emulator "https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/emulator/TerminalEmulator.kt"
click node_buffer "https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/emulator/TerminalBuffer.kt"
click node_row "https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/emulator/TerminalRow.kt"
click node_colors "https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/emulator/TerminalColor.kt"
click node_search "https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/emulator/TerminalSearch.kt"
click node_key_mapper "https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/emulator/KeyMapper.kt"
click node_bootstrap "https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/runtime/BootstrapManager.kt"
click node_environment "https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/runtime/Environment.kt"
click node_runtime "https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/runtime/CortexRuntime.kt"
click node_hook "https://github.com/ssfuisu/cortex/blob/main/app/src/main/cpp/cortex-hook.c"
click node_service "https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/service/CortexService.kt"
click node_url_server "https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/runtime/UrlOpenerServer.kt"
click node_updater "https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/update/UpdateManager.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_terminal_view,node_extra_keys,node_search_bar,node_settings,node_user toneBlue
class node_sessions,node_session,node_pty_process,node_pty_native,node_emulator,node_buffer,node_row,node_colors,node_search,node_key_mapper toneAmber
class node_bootstrap,node_environment,node_runtime,node_hook toneMint
class node_service,node_url_server,node_updater toneRose
class node_kernel,node_release_service toneIndigo
```

## Components

### Terminal interface

- [Main activity](https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/MainActivity.kt): `app/src/main/java/org/cortex/terminal/MainActivity.kt`
- [Terminal view](https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/view/TerminalView.kt): `app/src/main/java/org/cortex/terminal/view/TerminalView.kt`
- [Virtual keys](https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/view/ExtraKeysView.kt): `app/src/main/java/org/cortex/terminal/view/ExtraKeysView.kt`
- [Search bar](https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/view/TerminalSearchBar.kt): `app/src/main/java/org/cortex/terminal/view/TerminalSearchBar.kt`
- [Settings](https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/SettingsActivity.kt): `app/src/main/java/org/cortex/terminal/SettingsActivity.kt`

### Terminal execution

- [Session manager](https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/session/SessionManager.kt): `app/src/main/java/org/cortex/terminal/session/SessionManager.kt`
- [Terminal session](https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/session/TerminalSession.kt): `app/src/main/java/org/cortex/terminal/session/TerminalSession.kt`
- [PTY process](https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/pty/PtyProcess.kt): `app/src/main/java/org/cortex/terminal/pty/PtyProcess.kt`
- [Native PTY](https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/pty/PtyNative.kt): `app/src/main/java/org/cortex/terminal/pty/PtyNative.kt`
- [Terminal emulator](https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/emulator/TerminalEmulator.kt): `app/src/main/java/org/cortex/terminal/emulator/TerminalEmulator.kt`
- [Screen and scrollback](https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/emulator/TerminalBuffer.kt): `app/src/main/java/org/cortex/terminal/emulator/TerminalBuffer.kt`
- [Terminal rows](https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/emulator/TerminalRow.kt): `app/src/main/java/org/cortex/terminal/emulator/TerminalRow.kt`
- [Color schemes](https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/emulator/TerminalColor.kt): `app/src/main/java/org/cortex/terminal/emulator/TerminalColor.kt`
- [Buffer search](https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/emulator/TerminalSearch.kt): `app/src/main/java/org/cortex/terminal/emulator/TerminalSearch.kt`
- [Key mapping](https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/emulator/KeyMapper.kt): `app/src/main/java/org/cortex/terminal/emulator/KeyMapper.kt`

### Ubuntu runtime

- [Ubuntu bootstrap](https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/runtime/BootstrapManager.kt): `app/src/main/java/org/cortex/terminal/runtime/BootstrapManager.kt`
- [Runtime environment](https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/runtime/Environment.kt): `app/src/main/java/org/cortex/terminal/runtime/Environment.kt`
- [Runtime facade](https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/runtime/CortexRuntime.kt): `app/src/main/java/org/cortex/terminal/runtime/CortexRuntime.kt`
- [Userspace hook](https://github.com/ssfuisu/cortex/blob/main/app/src/main/cpp/cortex-hook.c): `app/src/main/cpp/cortex-hook.c`

### App services

- [Foreground service](https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/service/CortexService.kt): `app/src/main/java/org/cortex/terminal/service/CortexService.kt`
- [URL opener server](https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/runtime/UrlOpenerServer.kt): `app/src/main/java/org/cortex/terminal/runtime/UrlOpenerServer.kt`
- [App updater](https://github.com/ssfuisu/cortex/blob/main/app/src/main/java/org/cortex/terminal/update/UpdateManager.kt): `app/src/main/java/org/cortex/terminal/update/UpdateManager.kt`

### Other components

- **User**
- **Android Linux kernel**
- **Release and APK host**

## Connections

- User → Main activity: uses (evidence: `README.md`)
- Main activity → Foreground service: starts (evidence: `app/src/main/java/org/cortex/terminal/MainActivity.kt`)
- Main activity → Session manager: obtains (evidence: `app/src/main/java/org/cortex/terminal/MainActivity.kt`)
- Main activity → Terminal view: configures (evidence: `app/src/main/java/org/cortex/terminal/MainActivity.kt`)
- Main activity → Search bar: handles search (evidence: `app/src/main/java/org/cortex/terminal/MainActivity.kt`)
- Main activity → Virtual keys: configures (evidence: `app/src/main/java/org/cortex/terminal/MainActivity.kt`)
- Main activity → App updater: offers updates (evidence: `app/src/main/java/org/cortex/terminal/MainActivity.kt`)
- User → Settings: configures (evidence: `app/src/main/java/org/cortex/terminal/SettingsActivity.kt`)
- Session manager → Terminal session: creates (evidence: `app/src/main/java/org/cortex/terminal/session/SessionManager.kt`)
- Terminal session → PTY process: launches shell (evidence: `app/src/main/java/org/cortex/terminal/session/TerminalSession.kt`)
- PTY process → Native PTY: calls (evidence: `app/src/main/java/org/cortex/terminal/pty/PtyProcess.kt`)
- Native PTY → Android Linux kernel: creates PTY (evidence: `README.md`)
- Terminal session → Terminal emulator: feeds output (evidence: `app/src/main/java/org/cortex/terminal/session/TerminalSession.kt`)
- Terminal view → Terminal session: displays and writes (evidence: `app/src/main/java/org/cortex/terminal/view/TerminalView.kt`)
- Terminal emulator → Screen and scrollback: updates screen (evidence: `app/src/main/java/org/cortex/terminal/emulator/TerminalEmulator.kt`)
- Screen and scrollback → Terminal rows: stores rows (evidence: `app/src/main/java/org/cortex/terminal/emulator/TerminalBuffer.kt`)
- Screen and scrollback → Color schemes: uses colors (evidence: `app/src/main/java/org/cortex/terminal/emulator/TerminalBuffer.kt`)
- Terminal view → Buffer search: searches buffer (evidence: `app/src/main/java/org/cortex/terminal/view/TerminalView.kt`)
- Terminal view → Key mapping: maps input (evidence: `app/src/main/java/org/cortex/terminal/view/TerminalView.kt`)
- Runtime facade → Ubuntu bootstrap: delegates setup (evidence: `app/src/main/java/org/cortex/terminal/runtime/CortexRuntime.kt`)
- Ubuntu bootstrap → Runtime environment: uses paths (evidence: `app/src/main/java/org/cortex/terminal/runtime/BootstrapManager.kt`)
- Terminal session → Runtime environment: builds environment (evidence: `app/src/main/java/org/cortex/terminal/session/TerminalSession.kt`)
- Runtime environment → Userspace hook: sets preload (evidence: `README.md`)
- Userspace hook → Android Linux kernel: redirects userspace paths (evidence: `README.md`)
- Foreground service → Session manager: manages sessions (evidence: `app/src/main/java/org/cortex/terminal/service/CortexService.kt`)
- Foreground service → URL opener server: starts (evidence: `app/src/main/java/org/cortex/terminal/service/CortexService.kt`)
- App updater → Release and APK host: checks and downloads (evidence: `app/src/main/java/org/cortex/terminal/update/UpdateManager.kt`)
- User → App updater: requests update (evidence: `README.md`)
- User → Terminal view: searches scrollback (evidence: `README.md`)
- User → Terminal view: opens links and inserts images (evidence: `README.md`)
- User → Android Linux kernel: runs native programs (evidence: `README.md`)
