# kkelly-offical/kkcode architecture

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

- Interactive diagram: https://gitdiagram.com/kkelly-offical/kkcode
- Repository: https://github.com/kkelly-offical/kkcode

## Overview

KK Code is a terminal-first AI coding workspace, with Web, Android, and remote-device clients. The main workflow is a user prompt entering the CLI/session engine, proceeding through a turn loop to a configured model, and returning a response; modes, permissions, and tools shape that work. Other product branches include durable/background tasks, strict runs and artifacts, browser and MCP integrations, and shared remote sessions. The README documents major capabilities not fully visible in the sampled source; their paths below are supported by the tree, while uncertain internal call links are omitted.

Main entry points: [`src/kernel/session/engine.mjs`](https://github.com/kkelly-offical/kkcode/blob/main/src/kernel/session/engine.mjs) (Session Engine), [`src/kernel/tool/executor.mjs`](https://github.com/kkelly-offical/kkcode/blob/main/src/kernel/tool/executor.mjs) (Tool Executor), [`src/device/server.mjs`](https://github.com/kkelly-offical/kkcode/blob/main/src/device/server.mjs) (Device API), [`android/app/src/main/java/cn/kkcode/remote/MainActivity.kt`](https://github.com/kkelly-offical/kkcode/blob/main/android/app/src/main/java/cn/kkcode/remote/MainActivity.kt) (Android Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User Interfaces"]
  node_cli["CLI Entry<br/>[index.mjs]"]
  node_repl["Terminal REPL<br/>[repl.mjs]"]
  node_web["Web Client<br/>[main.tsx]"]
  node_android["Android Client<br/>[MainActivity.kt]"]
end

subgraph group_core["Session Runtime"]
  node_engine["Session Engine<br/>[engine.mjs]"]
  node_turnloop["Turn Loop<br/>[loop.mjs]"]
  node_sessions[("Session Store<br/>[store.mjs]")]
  node_background["Background Tasks"]
end

subgraph group_governance["Governed Work"]
  node_permissions["Permission Engine<br/>[engine.mjs]"]
  node_strict["Strict Runs"]
  node_artifacts[("Artifacts<br/>[artifact-store.mjs]")]
  node_audit[("Audit Trail<br/>[audit-store.mjs]")]
end

subgraph group_integrations["Tools And Models"]
  node_provider["Model Providers<br/>[router.mjs]"]
  node_executor["Tool Executor<br/>[executor.mjs]"]
  node_browser["Browser Tools<br/>[controller.mjs]"]
  node_mcp["MCP Clients<br/>[registry.mjs]"]
  node_plugins["Plugins And Skills<br/>[manager.mjs]"]
end

subgraph group_remote["Remote Access"]
  node_device["Device API<br/>[server.mjs]"]
  node_gateway["Remote Gateway<br/>[main.mjs]"]
  node_ssh["Android SSH<br/>[ssh-host.mjs]"]
  node_client["Web SDK Client<br/>[client.mjs]"]
end

node_user(("User"))
node_modelservice{{"Model Service"}}
node_remoteuser(("Remote User"))

node_user -->|"starts"| node_cli
node_cli -->|"opens"| node_repl
node_repl -->|"submits prompt"| node_engine
node_engine -->|"runs turn"| node_turnloop
node_turnloop -->|"requests completion"| node_provider
node_provider -->|"sends request"| node_modelservice
node_engine -->|"reads and updates"| node_sessions
node_user -->|"uses"| node_web
node_web -->|"calls"| node_client
node_client -->|"sends RPC"| node_device
node_android -->|"connects"| node_device
node_android -.->|"connects directly"| node_ssh
node_remoteuser -->|"authenticates"| node_gateway
node_gateway -->|"relays access"| node_device
node_device -->|"shares sessions"| node_sessions
node_executor -->|"checks authorization"| node_permissions
node_executor -->|"dispatches browser work"| node_browser
node_executor -->|"dispatches MCP tools"| node_mcp
node_engine -->|"supports long work"| node_background
node_engine -->|"coordinates strict runs"| node_strict
node_strict -->|"records evidence"| node_artifacts
node_permissions -->|"writes decisions"| node_audit
node_plugins -.->|"extends tools"| node_executor

click node_cli "https://github.com/kkelly-offical/kkcode/blob/main/src/index.mjs"
click node_repl "https://github.com/kkelly-offical/kkcode/blob/main/src/repl.mjs"
click node_web "https://github.com/kkelly-offical/kkcode/blob/main/apps/web/src/main.tsx"
click node_android "https://github.com/kkelly-offical/kkcode/blob/main/android/app/src/main/java/cn/kkcode/remote/MainActivity.kt"
click node_engine "https://github.com/kkelly-offical/kkcode/blob/main/src/kernel/session/engine.mjs"
click node_turnloop "https://github.com/kkelly-offical/kkcode/blob/main/src/kernel/session/loop.mjs"
click node_sessions "https://github.com/kkelly-offical/kkcode/blob/main/src/kernel/session/store.mjs"
click node_provider "https://github.com/kkelly-offical/kkcode/blob/main/src/kernel/provider/router.mjs"
click node_permissions "https://github.com/kkelly-offical/kkcode/blob/main/src/kernel/permission/engine.mjs"
click node_executor "https://github.com/kkelly-offical/kkcode/blob/main/src/kernel/tool/executor.mjs"
click node_browser "https://github.com/kkelly-offical/kkcode/blob/main/src/kernel/browser/controller.mjs"
click node_mcp "https://github.com/kkelly-offical/kkcode/blob/main/src/kernel/mcp/registry.mjs"
click node_plugins "https://github.com/kkelly-offical/kkcode/blob/main/src/kernel/plugin/manager.mjs"
click node_background "https://github.com/kkelly-offical/kkcode/blob/main/src/kernel/orchestration/background-manager.mjs"
click node_strict "https://github.com/kkelly-offical/kkcode/blob/main/src/kernel/orchestration/run-coordinator.mjs"
click node_artifacts "https://github.com/kkelly-offical/kkcode/blob/main/src/storage/artifact-store.mjs"
click node_audit "https://github.com/kkelly-offical/kkcode/blob/main/src/storage/audit-store.mjs"
click node_device "https://github.com/kkelly-offical/kkcode/blob/main/src/device/server.mjs"
click node_gateway "https://github.com/kkelly-offical/kkcode/blob/main/apps/gateway/main.mjs"
click node_ssh "https://github.com/kkelly-offical/kkcode/blob/main/src/remote/ssh-host.mjs"
click node_client "https://github.com/kkelly-offical/kkcode/blob/main/src/sdk/client.mjs"

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_repl,node_web,node_android,node_user,node_remoteuser toneBlue
class node_engine,node_turnloop,node_sessions,node_background toneAmber
class node_permissions,node_strict,node_artifacts,node_audit toneMint
class node_provider,node_executor,node_browser,node_mcp,node_plugins toneRose
class node_device,node_gateway,node_ssh,node_client,node_modelservice toneIndigo
```

## Components

### User Interfaces

- [CLI Entry](https://github.com/kkelly-offical/kkcode/blob/main/src/index.mjs): `src/index.mjs`
- [Terminal REPL](https://github.com/kkelly-offical/kkcode/blob/main/src/repl.mjs): `src/repl.mjs`
- [Web Client](https://github.com/kkelly-offical/kkcode/blob/main/apps/web/src/main.tsx): `apps/web/src/main.tsx`
- [Android Client](https://github.com/kkelly-offical/kkcode/blob/main/android/app/src/main/java/cn/kkcode/remote/MainActivity.kt): `android/app/src/main/java/cn/kkcode/remote/MainActivity.kt`

### Session Runtime

- [Session Engine](https://github.com/kkelly-offical/kkcode/blob/main/src/kernel/session/engine.mjs): `src/kernel/session/engine.mjs`
- [Turn Loop](https://github.com/kkelly-offical/kkcode/blob/main/src/kernel/session/loop.mjs): `src/kernel/session/loop.mjs`
- [Session Store](https://github.com/kkelly-offical/kkcode/blob/main/src/kernel/session/store.mjs): `src/kernel/session/store.mjs`
- [Background Tasks](https://github.com/kkelly-offical/kkcode/blob/main/src/kernel/orchestration/background-manager.mjs): `src/kernel/orchestration/background-manager.mjs`

### Governed Work

- [Permission Engine](https://github.com/kkelly-offical/kkcode/blob/main/src/kernel/permission/engine.mjs): `src/kernel/permission/engine.mjs`
- [Strict Runs](https://github.com/kkelly-offical/kkcode/blob/main/src/kernel/orchestration/run-coordinator.mjs): `src/kernel/orchestration/run-coordinator.mjs`
- [Artifacts](https://github.com/kkelly-offical/kkcode/blob/main/src/storage/artifact-store.mjs): `src/storage/artifact-store.mjs`
- [Audit Trail](https://github.com/kkelly-offical/kkcode/blob/main/src/storage/audit-store.mjs): `src/storage/audit-store.mjs`

### Tools And Models

- [Model Providers](https://github.com/kkelly-offical/kkcode/blob/main/src/kernel/provider/router.mjs): `src/kernel/provider/router.mjs`
- [Tool Executor](https://github.com/kkelly-offical/kkcode/blob/main/src/kernel/tool/executor.mjs): `src/kernel/tool/executor.mjs`
- [Browser Tools](https://github.com/kkelly-offical/kkcode/blob/main/src/kernel/browser/controller.mjs): `src/kernel/browser/controller.mjs`
- [MCP Clients](https://github.com/kkelly-offical/kkcode/blob/main/src/kernel/mcp/registry.mjs): `src/kernel/mcp/registry.mjs`
- [Plugins And Skills](https://github.com/kkelly-offical/kkcode/blob/main/src/kernel/plugin/manager.mjs): `src/kernel/plugin/manager.mjs`

### Remote Access

- [Device API](https://github.com/kkelly-offical/kkcode/blob/main/src/device/server.mjs): `src/device/server.mjs`
- [Remote Gateway](https://github.com/kkelly-offical/kkcode/blob/main/apps/gateway/main.mjs): `apps/gateway/main.mjs`
- [Android SSH](https://github.com/kkelly-offical/kkcode/blob/main/src/remote/ssh-host.mjs): `src/remote/ssh-host.mjs`
- [Web SDK Client](https://github.com/kkelly-offical/kkcode/blob/main/src/sdk/client.mjs): `src/sdk/client.mjs`

### Other components

- **User**
- **Model Service**
- **Remote User**

## Connections

- User → CLI Entry: starts
- CLI Entry → Terminal REPL: opens
- Terminal REPL → Session Engine: submits prompt
- Session Engine → Turn Loop: runs turn
- Turn Loop → Model Providers: requests completion
- Model Providers → Model Service: sends request
- Session Engine → Session Store: reads and updates
- User → Web Client: uses
- Web Client → Web SDK Client: calls
- Web SDK Client → Device API: sends RPC
- Android Client → Device API: connects
- Android Client → Android SSH: connects directly
- Remote User → Remote Gateway: authenticates
- Remote Gateway → Device API: relays access
- Device API → Session Store: shares sessions
- Tool Executor → Permission Engine: checks authorization
- Tool Executor → Browser Tools: dispatches browser work
- Tool Executor → MCP Clients: dispatches MCP tools
- Session Engine → Background Tasks: supports long work
- Session Engine → Strict Runs: coordinates strict runs
- Strict Runs → Artifacts: records evidence
- Permission Engine → Audit Trail: writes decisions
- Plugins And Skills → Tool Executor: extends tools