# thisuxhq/dukoi architecture

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

- Interactive diagram: https://gitdiagram.com/thisuxhq/dukoi
- Repository: https://github.com/thisuxhq/dukoi

## Overview

Dukoi turns an Android phone into a persistent app server: a user pairs a computer with the phone, deploys an app, then manages its releases, runtime, databases, logs, and public access. The graph includes the phone agent and service, CLI and dashboard surfaces, and the public site. Several subsystems are represented from the README and source index, but their internal wiring was not sampled; those relationships are omitted rather than inferred.

Main entry points: [`cli/src/main.ts`](https://github.com/thisuxhq/dukoi/blob/main/cli/src/main.ts) (CLI dispatcher), [`agent/src/app-routes.ts`](https://github.com/thisuxhq/dukoi/blob/main/agent/src/app-routes.ts) (App routes), [`agent/src/http.ts`](https://github.com/thisuxhq/dukoi/blob/main/agent/src/http.ts) (Agent API), [`android/app/src/main/kotlin/com/thisux/dukoi/AgentService.kt`](https://github.com/thisuxhq/dukoi/blob/main/android/app/src/main/kotlin/com/thisux/dukoi/AgentService.kt) (Foreground service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User interfaces"]
  node_cli["CLI dispatcher<br/>[main.ts]"]
  node_cli_deploy["Deploy command<br/>[deploy.ts]"]
  node_cli_apps["App controls<br/>[apps.ts]"]
  node_cli_pair["Pairing command<br/>[pair.ts]"]
  node_cli_observe["Observe commands<br/>[observe.ts]"]
  node_cli_db["Database commands<br/>[db.ts]"]
  node_dashboard["Web dashboard<br/>[+page.svelte]"]
  node_android_ui["Phone UI<br/>[MainActivity.kt]"]
end

subgraph group_phone["Phone runtime"]
  node_agent_service["Foreground service<br/>[AgentService.kt]"]
  node_supervisor["Agent supervisor<br/>[AgentSupervisor.kt]"]
  node_phone_pairing["Phone pairing<br/>[Pairing.kt]"]
  node_battery["Battery care<br/>[Battery.kt]"]
  node_agent_api["Agent API<br/>[http.ts]"]
end

subgraph group_features["App capabilities"]
  node_app_routes["App routes<br/>[app-routes.ts]"]
  node_app_runtime["App lifecycle and releases<br/>[apps.ts]"]
  node_database_routes["Database routes<br/>[database-routes.ts]"]
  node_database_runtime["Database management<br/>[databases.ts]"]
  node_observe_routes["Logs and health<br/>[observe-routes.ts]"]
  node_log_file["Log storage<br/>[log-file.ts]"]
  node_tunnels["Public exposure<br/>[tunnels.ts]"]
  node_domains["Custom domains<br/>[domains.ts]"]
  node_templates["App templates<br/>[templates.ts]"]
end

subgraph group_shared["Shared contracts"]
  node_shared_api["API contracts<br/>[api.ts]"]
end

subgraph group_public["Public services"]
  node_website["Dukoi website<br/>[worker.ts]"]
end

node_user(("Developer"))
node_cloudflare["Cloudflare tunnel service"]
node_app_user(("Deployed app user"))

node_user -->|"runs commands"| node_cli
node_cli -->|"dispatches deploy"| node_cli_deploy
node_cli -->|"dispatches controls"| node_cli_apps
node_cli -->|"dispatches pairing"| node_cli_pair
node_cli -->|"dispatches observation"| node_cli_observe
node_cli -->|"dispatches database"| node_cli_db
node_cli_apps -->|"sends app requests"| node_agent_api
node_agent_api -.->|"routes requests"| node_app_routes
node_app_routes -->|"calls lifecycle"| node_app_runtime
node_app_routes -->|"exposes apps"| node_tunnels
node_app_routes -->|"manages domains"| node_domains
node_app_routes -->|"deploys templates"| node_templates
node_database_routes -->|"calls management"| node_database_runtime
node_observe_routes -->|"reads and follows"| node_log_file
node_agent_service -->|"starts supervisor"| node_supervisor
node_agent_service -->|"watches pairing"| node_phone_pairing
node_agent_service -->|"samples battery"| node_battery
node_dashboard -.->|"manages apps and health"| node_agent_api
node_cli_pair -.->|"pairs with phone"| node_agent_api
node_tunnels -.->|"creates public links"| node_cloudflare
node_app_user -.->|"accesses exposed apps"| node_tunnels
node_website -.->|"uses Cloudflare platform"| node_cloudflare

click node_cli "https://github.com/thisuxhq/dukoi/blob/main/cli/src/main.ts"
click node_cli_deploy "https://github.com/thisuxhq/dukoi/blob/main/cli/src/commands/deploy.ts"
click node_cli_apps "https://github.com/thisuxhq/dukoi/blob/main/cli/src/commands/apps.ts"
click node_cli_pair "https://github.com/thisuxhq/dukoi/blob/main/cli/src/commands/pair.ts"
click node_cli_observe "https://github.com/thisuxhq/dukoi/blob/main/cli/src/commands/observe.ts"
click node_cli_db "https://github.com/thisuxhq/dukoi/blob/main/cli/src/commands/db.ts"
click node_dashboard "https://github.com/thisuxhq/dukoi/blob/main/dashboard/src/routes/%2Bpage.svelte"
click node_android_ui "https://github.com/thisuxhq/dukoi/blob/main/android/app/src/main/kotlin/com/thisux/dukoi/MainActivity.kt"
click node_agent_service "https://github.com/thisuxhq/dukoi/blob/main/android/app/src/main/kotlin/com/thisux/dukoi/AgentService.kt"
click node_supervisor "https://github.com/thisuxhq/dukoi/blob/main/android/app/src/main/kotlin/com/thisux/dukoi/AgentSupervisor.kt"
click node_phone_pairing "https://github.com/thisuxhq/dukoi/blob/main/android/app/src/main/kotlin/com/thisux/dukoi/Pairing.kt"
click node_battery "https://github.com/thisuxhq/dukoi/blob/main/android/app/src/main/kotlin/com/thisux/dukoi/Battery.kt"
click node_agent_api "https://github.com/thisuxhq/dukoi/blob/main/agent/src/http.ts"
click node_app_routes "https://github.com/thisuxhq/dukoi/blob/main/agent/src/app-routes.ts"
click node_app_runtime "https://github.com/thisuxhq/dukoi/blob/main/agent/src/apps.ts"
click node_database_routes "https://github.com/thisuxhq/dukoi/blob/main/agent/src/database-routes.ts"
click node_database_runtime "https://github.com/thisuxhq/dukoi/blob/main/agent/src/databases.ts"
click node_observe_routes "https://github.com/thisuxhq/dukoi/blob/main/agent/src/observe-routes.ts"
click node_log_file "https://github.com/thisuxhq/dukoi/blob/main/agent/src/log-file.ts"
click node_tunnels "https://github.com/thisuxhq/dukoi/blob/main/agent/src/tunnels.ts"
click node_domains "https://github.com/thisuxhq/dukoi/blob/main/agent/src/domains.ts"
click node_templates "https://github.com/thisuxhq/dukoi/blob/main/agent/src/templates.ts"
click node_shared_api "https://github.com/thisuxhq/dukoi/blob/main/shared/src/api.ts"
click node_website "https://github.com/thisuxhq/dukoi/blob/main/site/worker.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_cli,node_cli_deploy,node_cli_apps,node_cli_pair,node_cli_observe,node_cli_db,node_dashboard,node_android_ui,node_app_user toneBlue
class node_agent_service,node_supervisor,node_phone_pairing,node_battery,node_agent_api toneAmber
class node_app_routes,node_app_runtime,node_database_routes,node_database_runtime,node_observe_routes,node_log_file,node_tunnels,node_domains,node_templates toneMint
class node_shared_api toneRose
class node_website,node_user,node_cloudflare toneIndigo
```

## Components

### User interfaces

- [CLI dispatcher](https://github.com/thisuxhq/dukoi/blob/main/cli/src/main.ts): `cli/src/main.ts`
- [Deploy command](https://github.com/thisuxhq/dukoi/blob/main/cli/src/commands/deploy.ts): `cli/src/commands/deploy.ts`
- [App controls](https://github.com/thisuxhq/dukoi/blob/main/cli/src/commands/apps.ts): `cli/src/commands/apps.ts`
- [Pairing command](https://github.com/thisuxhq/dukoi/blob/main/cli/src/commands/pair.ts): `cli/src/commands/pair.ts`
- [Observe commands](https://github.com/thisuxhq/dukoi/blob/main/cli/src/commands/observe.ts): `cli/src/commands/observe.ts`
- [Database commands](https://github.com/thisuxhq/dukoi/blob/main/cli/src/commands/db.ts): `cli/src/commands/db.ts`
- [Web dashboard](https://github.com/thisuxhq/dukoi/blob/main/dashboard/src/routes/%2Bpage.svelte): `dashboard/src/routes/+page.svelte`
- [Phone UI](https://github.com/thisuxhq/dukoi/blob/main/android/app/src/main/kotlin/com/thisux/dukoi/MainActivity.kt): `android/app/src/main/kotlin/com/thisux/dukoi/MainActivity.kt`

### Phone runtime

- [Foreground service](https://github.com/thisuxhq/dukoi/blob/main/android/app/src/main/kotlin/com/thisux/dukoi/AgentService.kt): `android/app/src/main/kotlin/com/thisux/dukoi/AgentService.kt`
- [Agent supervisor](https://github.com/thisuxhq/dukoi/blob/main/android/app/src/main/kotlin/com/thisux/dukoi/AgentSupervisor.kt): `android/app/src/main/kotlin/com/thisux/dukoi/AgentSupervisor.kt`
- [Phone pairing](https://github.com/thisuxhq/dukoi/blob/main/android/app/src/main/kotlin/com/thisux/dukoi/Pairing.kt): `android/app/src/main/kotlin/com/thisux/dukoi/Pairing.kt`
- [Battery care](https://github.com/thisuxhq/dukoi/blob/main/android/app/src/main/kotlin/com/thisux/dukoi/Battery.kt): `android/app/src/main/kotlin/com/thisux/dukoi/Battery.kt`
- [Agent API](https://github.com/thisuxhq/dukoi/blob/main/agent/src/http.ts): `agent/src/http.ts`

### App capabilities

- [App routes](https://github.com/thisuxhq/dukoi/blob/main/agent/src/app-routes.ts): `agent/src/app-routes.ts`
- [App lifecycle and releases](https://github.com/thisuxhq/dukoi/blob/main/agent/src/apps.ts): `agent/src/apps.ts`
- [Database routes](https://github.com/thisuxhq/dukoi/blob/main/agent/src/database-routes.ts): `agent/src/database-routes.ts`
- [Database management](https://github.com/thisuxhq/dukoi/blob/main/agent/src/databases.ts): `agent/src/databases.ts`
- [Logs and health](https://github.com/thisuxhq/dukoi/blob/main/agent/src/observe-routes.ts): `agent/src/observe-routes.ts`
- [Log storage](https://github.com/thisuxhq/dukoi/blob/main/agent/src/log-file.ts): `agent/src/log-file.ts`
- [Public exposure](https://github.com/thisuxhq/dukoi/blob/main/agent/src/tunnels.ts): `agent/src/tunnels.ts`
- [Custom domains](https://github.com/thisuxhq/dukoi/blob/main/agent/src/domains.ts): `agent/src/domains.ts`
- [App templates](https://github.com/thisuxhq/dukoi/blob/main/agent/src/templates.ts): `agent/src/templates.ts`

### Shared contracts

- [API contracts](https://github.com/thisuxhq/dukoi/blob/main/shared/src/api.ts): `shared/src/api.ts`

### Public services

- [Dukoi website](https://github.com/thisuxhq/dukoi/blob/main/site/worker.ts): `site/worker.ts`

### Other components

- **Developer**
- **Cloudflare tunnel service**
- **Deployed app user**

## Connections

- Developer → CLI dispatcher: runs commands
- CLI dispatcher → Deploy command: dispatches deploy (evidence: `cli/src/main.ts`)
- CLI dispatcher → App controls: dispatches controls (evidence: `cli/src/main.ts`)
- CLI dispatcher → Pairing command: dispatches pairing (evidence: `cli/src/main.ts`)
- CLI dispatcher → Observe commands: dispatches observation (evidence: `cli/src/main.ts`)
- CLI dispatcher → Database commands: dispatches database (evidence: `cli/src/main.ts`)
- App controls → Agent API: sends app requests (evidence: `cli/src/commands/apps.ts`)
- Agent API → App routes: routes requests (evidence: `agent/src/app-routes.ts`)
- App routes → App lifecycle and releases: calls lifecycle (evidence: `agent/src/app-routes.ts`)
- App routes → Public exposure: exposes apps (evidence: `agent/src/app-routes.ts`)
- App routes → Custom domains: manages domains (evidence: `agent/src/app-routes.ts`)
- App routes → App templates: deploys templates (evidence: `agent/src/app-routes.ts`)
- Database routes → Database management: calls management (evidence: `agent/src/database-routes.ts`)
- Logs and health → Log storage: reads and follows (evidence: `agent/src/observe-routes.ts`)
- Foreground service → Agent supervisor: starts supervisor (evidence: `android/app/src/main/kotlin/com/thisux/dukoi/AgentService.kt`)
- Foreground service → Phone pairing: watches pairing (evidence: `android/app/src/main/kotlin/com/thisux/dukoi/AgentService.kt`)
- Foreground service → Battery care: samples battery (evidence: `android/app/src/main/kotlin/com/thisux/dukoi/AgentService.kt`)
- Web dashboard → Agent API: manages apps and health
- Pairing command → Agent API: pairs with phone
- Public exposure → Cloudflare tunnel service: creates public links
- Deployed app user → Public exposure: accesses exposed apps
- Dukoi website → Cloudflare tunnel service: uses Cloudflare platform