# seanaxxx/qodex architecture

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

- Interactive diagram: https://gitdiagram.com/seanaxxx/qodex
- Repository: https://github.com/seanaxxx/qodex

## Overview

Qodex is an on-device Android coding agent: a user chats in the Compose app, the host starts and provisions an embedded Node.js Bionic runtime, and framed stdio RPC carries work to the agent engine. The engine can stream model output, use tools against a workspace, and return results to the UI; the README also documents credentials, background execution, and optional elevated shell access. Edges rely on the README or shown source references; unsampled subsystems are represented without speculative internal call chains.

Main entry points: [`android/app/src/main/java/com/qodex/app/runtime/EngineProcess.kt`](https://github.com/seanaxxx/qodex/blob/main/android/app/src/main/java/com/qodex/app/runtime/EngineProcess.kt) (Engine process), [`apps/qodex-cli`](https://github.com/seanaxxx/qodex/tree/main/apps/qodex-cli) (Agent engine), [`android/app/src/main/java/com/qodex/app/runtime/Provisioner.kt`](https://github.com/seanaxxx/qodex/blob/main/android/app/src/main/java/com/qodex/app/runtime/Provisioner.kt) (Runtime provisioning), [`apps/qodex-cli/packages/bootstrap/src/app/workspace-hook-review-controller.ts`](https://github.com/seanaxxx/qodex/blob/main/apps/qodex-cli/packages/bootstrap/src/app/workspace-hook-review-controller.ts) (Hook review)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_android["Android host"]
  node_ui["Compose interface"]
  node_viewmodel["App state"]
  node_rpc["RPC client<br/>[QodexRpcClient.kt]"]
  node_engineproc["Engine process<br/>[EngineProcess.kt]"]
  node_provision["Runtime provisioning<br/>[Provisioner.kt]"]
  node_bionic["Bionic environment<br/>[BionicEnv.kt]"]
  node_runtimebus["Runtime status<br/>[RuntimeBus.kt]"]
  node_logger["File logging<br/>[FileLogger.kt]"]
  node_keepalive["Background service"]
end

subgraph group_engine["Agent engine"]
  node_agent["Agent engine"]
  node_tools["Tool execution"]
  node_models["Model adapters"]
  node_workspace["Workspace files"]
end

subgraph group_workflow["Workflow and trust"]
  node_workflow["Dynamic workflow<br/>[engine.ts]"]
  node_artifacts["Workflow artifacts"]
  node_registry["Workflow registry<br/>[registry.ts]"]
  node_hookreview["Hook review"]
  node_hooktypes["Hook review types"]
  node_hooktelemetry["Hook telemetry"]
end

subgraph group_support["Other modules"]
  node_proof["Formal proof<br/>[main.ts]"]
  node_serverpaths["Server runtime paths<br/>[paths.ts]"]
  node_servicemgr["Server services<br/>[serviceManager.ts]"]
end

node_user(("Android user"))
node_native["Native utilities"]

node_user -->|"submits tasks"| node_ui
node_ui -.->|"updates state"| node_viewmodel
node_viewmodel -.->|"sends requests"| node_rpc
node_rpc -->|"stdio RPC"| node_engineproc
node_engineproc -->|"resolves runtime"| node_provision
node_engineproc -->|"sets environment"| node_bionic
node_engineproc -->|"reports phase"| node_runtimebus
node_engineproc -->|"logs launch"| node_logger
node_provision -->|"reports progress"| node_runtimebus
node_provision -->|"logs setup"| node_logger
node_keepalive -.->|"keeps active"| node_engineproc
node_engineproc -->|"starts Node"| node_agent
node_agent -->|"dispatches tools"| node_tools
node_agent -->|"streams model calls"| node_models
node_tools -->|"reads and edits"| node_workspace
node_tools -->|"runs utilities"| node_native
node_agent -.->|"runs workflows"| node_workflow
node_workflow -->|"manages artifacts"| node_artifacts
node_artifacts -->|"checks presets"| node_registry
node_agent -.->|"reviews workspace hooks"| node_hookreview
node_hookreview -->|"uses contracts"| node_hooktypes
node_hookreview -->|"supervises review"| node_hooktelemetry
node_servicemgr -->|"uses runtime paths"| node_serverpaths

click node_ui "https://github.com/seanaxxx/qodex/tree/main/android/app/src/main/java/com/qodex/app/ui"
click node_viewmodel "https://github.com/seanaxxx/qodex/blob/main/android/app/src/main/java/com/qodex/app/state/QodexAppViewModel.kt"
click node_rpc "https://github.com/seanaxxx/qodex/blob/main/android/app/src/main/java/com/qodex/app/rpc/QodexRpcClient.kt"
click node_engineproc "https://github.com/seanaxxx/qodex/blob/main/android/app/src/main/java/com/qodex/app/runtime/EngineProcess.kt"
click node_provision "https://github.com/seanaxxx/qodex/blob/main/android/app/src/main/java/com/qodex/app/runtime/Provisioner.kt"
click node_bionic "https://github.com/seanaxxx/qodex/blob/main/android/app/src/main/java/com/qodex/app/runtime/BionicEnv.kt"
click node_runtimebus "https://github.com/seanaxxx/qodex/blob/main/android/app/src/main/java/com/qodex/app/runtime/RuntimeBus.kt"
click node_logger "https://github.com/seanaxxx/qodex/blob/main/android/app/src/main/java/com/qodex/app/utils/FileLogger.kt"
click node_keepalive "https://github.com/seanaxxx/qodex/blob/main/android/app/src/main/java/com/qodex/app/runtime/AgentKeepAliveService.kt"
click node_agent "https://github.com/seanaxxx/qodex/tree/main/apps/qodex-cli"
click node_tools "https://github.com/seanaxxx/qodex/tree/main/apps/qodex-cli"
click node_models "https://github.com/seanaxxx/qodex/tree/main/apps/qodex-cli/packages/adapters/src/model"
click node_workspace "https://github.com/seanaxxx/qodex/tree/main/apps/qodex-cli/packages/adapters/src/fs"
click node_workflow "https://github.com/seanaxxx/qodex/blob/main/apps/qodex-cli/packages/dynamic-workflow/src/engine/engine.ts"
click node_artifacts "https://github.com/seanaxxx/qodex/blob/main/apps/qodex-cli/packages/dynamic-workflow/src/engine/engine-artifacts.ts"
click node_registry "https://github.com/seanaxxx/qodex/blob/main/apps/qodex-cli/packages/dynamic-workflow/src/facade/registry.ts"
click node_hookreview "https://github.com/seanaxxx/qodex/blob/main/apps/qodex-cli/packages/bootstrap/src/app/workspace-hook-review-controller.ts"
click node_hooktypes "https://github.com/seanaxxx/qodex/blob/main/apps/qodex-cli/packages/bootstrap/src/app/workspace-hook-review-types.ts"
click node_hooktelemetry "https://github.com/seanaxxx/qodex/blob/main/apps/qodex-cli/packages/bootstrap/src/app/workspace-hook-review-telemetry.ts"
click node_proof "https://github.com/seanaxxx/qodex/blob/main/packages/formal-proof/src/main.ts"
click node_serverpaths "https://github.com/seanaxxx/qodex/blob/main/packages/qodex-server-cli/src/runtime/paths.ts"
click node_servicemgr "https://github.com/seanaxxx/qodex/blob/main/packages/qodex-server-cli/src/platform/serviceManager.ts"

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_ui,node_viewmodel,node_rpc,node_engineproc,node_provision,node_bionic,node_runtimebus,node_logger,node_keepalive,node_user toneBlue
class node_agent,node_tools,node_models,node_workspace toneAmber
class node_workflow,node_artifacts,node_registry,node_hookreview,node_hooktypes,node_hooktelemetry toneMint
class node_proof,node_serverpaths,node_servicemgr toneRose
class node_native toneIndigo
```

## Components

### Android host

- [Compose interface](https://github.com/seanaxxx/qodex/tree/main/android/app/src/main/java/com/qodex/app/ui): `android/app/src/main/java/com/qodex/app/ui`
- [App state](https://github.com/seanaxxx/qodex/blob/main/android/app/src/main/java/com/qodex/app/state/QodexAppViewModel.kt): `android/app/src/main/java/com/qodex/app/state/QodexAppViewModel.kt`
- [RPC client](https://github.com/seanaxxx/qodex/blob/main/android/app/src/main/java/com/qodex/app/rpc/QodexRpcClient.kt): `android/app/src/main/java/com/qodex/app/rpc/QodexRpcClient.kt`
- [Engine process](https://github.com/seanaxxx/qodex/blob/main/android/app/src/main/java/com/qodex/app/runtime/EngineProcess.kt): `android/app/src/main/java/com/qodex/app/runtime/EngineProcess.kt`
- [Runtime provisioning](https://github.com/seanaxxx/qodex/blob/main/android/app/src/main/java/com/qodex/app/runtime/Provisioner.kt): `android/app/src/main/java/com/qodex/app/runtime/Provisioner.kt`
- [Bionic environment](https://github.com/seanaxxx/qodex/blob/main/android/app/src/main/java/com/qodex/app/runtime/BionicEnv.kt): `android/app/src/main/java/com/qodex/app/runtime/BionicEnv.kt`
- [Runtime status](https://github.com/seanaxxx/qodex/blob/main/android/app/src/main/java/com/qodex/app/runtime/RuntimeBus.kt): `android/app/src/main/java/com/qodex/app/runtime/RuntimeBus.kt`
- [File logging](https://github.com/seanaxxx/qodex/blob/main/android/app/src/main/java/com/qodex/app/utils/FileLogger.kt): `android/app/src/main/java/com/qodex/app/utils/FileLogger.kt`
- [Background service](https://github.com/seanaxxx/qodex/blob/main/android/app/src/main/java/com/qodex/app/runtime/AgentKeepAliveService.kt): `android/app/src/main/java/com/qodex/app/runtime/AgentKeepAliveService.kt`

### Agent engine

- [Agent engine](https://github.com/seanaxxx/qodex/tree/main/apps/qodex-cli): `apps/qodex-cli`
- [Tool execution](https://github.com/seanaxxx/qodex/tree/main/apps/qodex-cli): `apps/qodex-cli`
- [Model adapters](https://github.com/seanaxxx/qodex/tree/main/apps/qodex-cli/packages/adapters/src/model): `apps/qodex-cli/packages/adapters/src/model`
- [Workspace files](https://github.com/seanaxxx/qodex/tree/main/apps/qodex-cli/packages/adapters/src/fs): `apps/qodex-cli/packages/adapters/src/fs`

### Workflow and trust

- [Dynamic workflow](https://github.com/seanaxxx/qodex/blob/main/apps/qodex-cli/packages/dynamic-workflow/src/engine/engine.ts): `apps/qodex-cli/packages/dynamic-workflow/src/engine/engine.ts`
- [Workflow artifacts](https://github.com/seanaxxx/qodex/blob/main/apps/qodex-cli/packages/dynamic-workflow/src/engine/engine-artifacts.ts): `apps/qodex-cli/packages/dynamic-workflow/src/engine/engine-artifacts.ts`
- [Workflow registry](https://github.com/seanaxxx/qodex/blob/main/apps/qodex-cli/packages/dynamic-workflow/src/facade/registry.ts): `apps/qodex-cli/packages/dynamic-workflow/src/facade/registry.ts`
- [Hook review](https://github.com/seanaxxx/qodex/blob/main/apps/qodex-cli/packages/bootstrap/src/app/workspace-hook-review-controller.ts): `apps/qodex-cli/packages/bootstrap/src/app/workspace-hook-review-controller.ts`
- [Hook review types](https://github.com/seanaxxx/qodex/blob/main/apps/qodex-cli/packages/bootstrap/src/app/workspace-hook-review-types.ts): `apps/qodex-cli/packages/bootstrap/src/app/workspace-hook-review-types.ts`
- [Hook telemetry](https://github.com/seanaxxx/qodex/blob/main/apps/qodex-cli/packages/bootstrap/src/app/workspace-hook-review-telemetry.ts): `apps/qodex-cli/packages/bootstrap/src/app/workspace-hook-review-telemetry.ts`

### Other modules

- [Formal proof](https://github.com/seanaxxx/qodex/blob/main/packages/formal-proof/src/main.ts): `packages/formal-proof/src/main.ts`
- [Server runtime paths](https://github.com/seanaxxx/qodex/blob/main/packages/qodex-server-cli/src/runtime/paths.ts): `packages/qodex-server-cli/src/runtime/paths.ts`
- [Server services](https://github.com/seanaxxx/qodex/blob/main/packages/qodex-server-cli/src/platform/serviceManager.ts): `packages/qodex-server-cli/src/platform/serviceManager.ts`

### Other components

- **Android user**
- **Native utilities**

## Connections

- Android user → Compose interface: submits tasks (evidence: `README.md`)
- Compose interface → App state: updates state
- App state → RPC client: sends requests
- RPC client → Engine process: stdio RPC (evidence: `README.md`)
- Engine process → Runtime provisioning: resolves runtime (evidence: `android/app/src/main/java/com/qodex/app/runtime/EngineProcess.kt`)
- Engine process → Bionic environment: sets environment (evidence: `android/app/src/main/java/com/qodex/app/runtime/EngineProcess.kt`)
- Engine process → Runtime status: reports phase (evidence: `android/app/src/main/java/com/qodex/app/runtime/EngineProcess.kt`)
- Engine process → File logging: logs launch (evidence: `android/app/src/main/java/com/qodex/app/runtime/EngineProcess.kt`)
- Runtime provisioning → Runtime status: reports progress (evidence: `android/app/src/main/java/com/qodex/app/runtime/Provisioner.kt`)
- Runtime provisioning → File logging: logs setup (evidence: `android/app/src/main/java/com/qodex/app/runtime/Provisioner.kt`)
- Background service → Engine process: keeps active
- Engine process → Agent engine: starts Node (evidence: `README.md`)
- Agent engine → Tool execution: dispatches tools (evidence: `README.md`)
- Agent engine → Model adapters: streams model calls (evidence: `README.md`)
- Tool execution → Workspace files: reads and edits (evidence: `README.md`)
- Tool execution → Native utilities: runs utilities (evidence: `README.md`)
- Agent engine → Dynamic workflow: runs workflows (evidence: `apps/qodex-cli/packages/dynamic-workflow/src/engine/engine.ts`)
- Dynamic workflow → Workflow artifacts: manages artifacts (evidence: `apps/qodex-cli/packages/dynamic-workflow/src/engine/engine.ts`)
- Workflow artifacts → Workflow registry: checks presets (evidence: `apps/qodex-cli/packages/dynamic-workflow/src/engine/engine-artifacts.ts`)
- Agent engine → Hook review: reviews workspace hooks (evidence: `apps/qodex-cli/packages/bootstrap/src/app/workspace-hook-review-controller.ts`)
- Hook review → Hook review types: uses contracts (evidence: `apps/qodex-cli/packages/bootstrap/src/app/workspace-hook-review-controller.ts`)
- Hook review → Hook telemetry: supervises review (evidence: `apps/qodex-cli/packages/bootstrap/src/app/workspace-hook-review-controller.ts`)
- Server services → Server runtime paths: uses runtime paths (evidence: `packages/qodex-server-cli/src/platform/serviceManager.ts`)
