# pathlanddev/pathland architecture

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

- Interactive diagram: https://gitdiagram.com/pathlanddev/pathland
- Repository: https://github.com/pathlanddev/pathland

## Overview

Pathland is a cross-language declarative UI protocol and runtime. The main workflow is a view DSL rendered and retained on the server, with initial HTML followed by binary deltas to a browser client; the same protocol also supports native renderers. The README documents these product-level flows and proxy composition. Source excerpts show parts of the Kotlin view/reactivity, Rust engine, browser client, routing, and proxy behavior; unsampled internals and some runtime connections are represented only where documentation supports them.

Main entry points: [`lib/java/pathland-server-core/src/main/java/dev/pathland/server/PathlandSession.java`](https://github.com/pathlanddev/pathland/blob/main/lib/java/pathland-server-core/src/main/java/dev/pathland/server/PathlandSession.java) (Server session), [`lib/java/pathland-view-core/src/main/kotlin/dev/pathland/view/dsl/CoreView.kt`](https://github.com/pathlanddev/pathland/blob/main/lib/java/pathland-view-core/src/main/kotlin/dev/pathland/view/dsl/CoreView.kt) (Kotlin view DSL), [`lib/rust/crates/pathland-engine/src/engine.rs`](https://github.com/pathlanddev/pathland/blob/main/lib/rust/crates/pathland-engine/src/engine.rs) (Rust diff engine), [`lib/typescript/src/index.ts`](https://github.com/pathlanddev/pathland/blob/main/lib/typescript/src/index.ts) (Client connection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["View authoring"]
  node_kotlin_dsl["Kotlin view DSL<br/>[CoreView.kt]"]
  node_rust_dsl["Rust view API<br/>[lib.rs]"]
  node_reactivity["Signals and state<br/>[Signals.kt]"]
  node_routing["View routing<br/>[Router.kt]"]
end

subgraph group_runtime["Protocol runtime"]
  node_session["Server session"]
  node_protocol["Opcode protocol<br/>[Commands.java]"]
  node_transport["Frame transport<br/>[FrameCodec.java]"]
  node_rust_engine["Rust diff engine<br/>[engine.rs]"]
end

subgraph group_web["Web surface"]
  node_html_renderer["HTML rendering<br/>[HtmlRenderer.java]"]
  node_jvm_host["JVM host adapters"]
  node_web_client["DOM delta client<br/>[apply.ts]"]
  node_client_boot["Client connection<br/>[index.ts]"]
  node_service_worker["Stateful navigation<br/>[service-worker.ts]"]
end

subgraph group_native["Native surfaces"]
  node_gtk_renderer["GTK renderer<br/>[lib.rs]"]
  node_qt_renderer["Qt renderer<br/>[renderer.rs]"]
end

subgraph group_composition["Composition"]
  node_proxy_session["Proxy session<br/>[ProxySession.java]"]
end

node_developer(("Application developer"))
node_browser(("Browser user"))
node_origin_server(("Origin Pathland server"))

node_developer -->|"declares views"| node_kotlin_dsl
node_developer -->|"declares views"| node_rust_dsl
node_kotlin_dsl -.->|"uses signals"| node_reactivity
node_kotlin_dsl -.->|"supports navigation"| node_routing
node_kotlin_dsl -->|"mounts in"| node_session
node_session -->|"renders initial HTML"| node_html_renderer
node_session -->|"emits deltas"| node_protocol
node_session -->|"sends frames"| node_transport
node_rust_dsl -.->|"drives view engine"| node_rust_engine
node_rust_engine -->|"emits opcodes"| node_protocol
node_protocol -.->|"encoded as frames"| node_transport
node_jvm_host -->|"hosts sessions"| node_session
node_html_renderer -->|"serves HTML"| node_browser
node_browser -->|"opens live connection"| node_client_boot
node_client_boot -->|"exchanges deltas"| node_transport
node_client_boot -->|"applies incoming frames"| node_web_client
node_web_client -->|"updates DOM"| node_browser
node_client_boot -->|"registers worker"| node_service_worker
node_rust_engine -.->|"drives native surface"| node_gtk_renderer
node_rust_engine -.->|"drives native surface"| node_qt_renderer
node_session -->|"composes subtree"| node_proxy_session
node_proxy_session -->|"connects as client"| node_origin_server
node_proxy_session -->|"splices opcode stream"| node_session

click node_kotlin_dsl "https://github.com/pathlanddev/pathland/blob/main/lib/java/pathland-view-core/src/main/kotlin/dev/pathland/view/dsl/CoreView.kt"
click node_rust_dsl "https://github.com/pathlanddev/pathland/blob/main/lib/rust/crates/pathland-view/src/lib.rs"
click node_reactivity "https://github.com/pathlanddev/pathland/blob/main/lib/java/pathland-view-core/src/main/kotlin/dev/pathland/view/core/signal/Signals.kt"
click node_routing "https://github.com/pathlanddev/pathland/blob/main/lib/java/pathland-view-core/src/main/kotlin/dev/pathland/view/core/router/Router.kt"
click node_session "https://github.com/pathlanddev/pathland/blob/main/lib/java/pathland-server-core/src/main/java/dev/pathland/server/PathlandSession.java"
click node_protocol "https://github.com/pathlanddev/pathland/blob/main/lib/java/pathland-core/src/main/java/dev/pathland/core/protocol/Commands.java"
click node_transport "https://github.com/pathlanddev/pathland/blob/main/lib/java/pathland-core/src/main/java/dev/pathland/core/transport/FrameCodec.java"
click node_rust_engine "https://github.com/pathlanddev/pathland/blob/main/lib/rust/crates/pathland-engine/src/engine.rs"
click node_html_renderer "https://github.com/pathlanddev/pathland/blob/main/lib/java/pathland-render-html/src/main/java/dev/pathland/render/html/HtmlRenderer.java"
click node_jvm_host "https://github.com/pathlanddev/pathland/blob/main/lib/java/pathland-quarkus/src/main/java/dev/pathland/quarkus/PathlandSocket.java"
click node_web_client "https://github.com/pathlanddev/pathland/blob/main/lib/typescript/src/apply.ts"
click node_client_boot "https://github.com/pathlanddev/pathland/blob/main/lib/typescript/src/index.ts"
click node_service_worker "https://github.com/pathlanddev/pathland/blob/main/lib/typescript/src/service-worker.ts"
click node_gtk_renderer "https://github.com/pathlanddev/pathland/blob/main/lib/rust/crates/pathland-render-gtk/src/lib.rs"
click node_qt_renderer "https://github.com/pathlanddev/pathland/blob/main/lib/rust/crates/pathland-render-qt/src/renderer.rs"
click node_proxy_session "https://github.com/pathlanddev/pathland/blob/main/lib/java/pathland-server-core/src/main/java/dev/pathland/server/proxy/ProxySession.java"

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_kotlin_dsl,node_rust_dsl,node_reactivity,node_routing,node_browser toneBlue
class node_session,node_protocol,node_transport,node_rust_engine toneAmber
class node_html_renderer,node_jvm_host,node_web_client,node_client_boot,node_service_worker,node_origin_server toneMint
class node_gtk_renderer,node_qt_renderer toneRose
class node_proxy_session,node_developer toneIndigo
```

## Components

### View authoring

- [Kotlin view DSL](https://github.com/pathlanddev/pathland/blob/main/lib/java/pathland-view-core/src/main/kotlin/dev/pathland/view/dsl/CoreView.kt): `lib/java/pathland-view-core/src/main/kotlin/dev/pathland/view/dsl/CoreView.kt`
- [Rust view API](https://github.com/pathlanddev/pathland/blob/main/lib/rust/crates/pathland-view/src/lib.rs): `lib/rust/crates/pathland-view/src/lib.rs`
- [Signals and state](https://github.com/pathlanddev/pathland/blob/main/lib/java/pathland-view-core/src/main/kotlin/dev/pathland/view/core/signal/Signals.kt): `lib/java/pathland-view-core/src/main/kotlin/dev/pathland/view/core/signal/Signals.kt`
- [View routing](https://github.com/pathlanddev/pathland/blob/main/lib/java/pathland-view-core/src/main/kotlin/dev/pathland/view/core/router/Router.kt): `lib/java/pathland-view-core/src/main/kotlin/dev/pathland/view/core/router/Router.kt`

### Protocol runtime

- [Server session](https://github.com/pathlanddev/pathland/blob/main/lib/java/pathland-server-core/src/main/java/dev/pathland/server/PathlandSession.java): `lib/java/pathland-server-core/src/main/java/dev/pathland/server/PathlandSession.java`
- [Opcode protocol](https://github.com/pathlanddev/pathland/blob/main/lib/java/pathland-core/src/main/java/dev/pathland/core/protocol/Commands.java): `lib/java/pathland-core/src/main/java/dev/pathland/core/protocol/Commands.java`
- [Frame transport](https://github.com/pathlanddev/pathland/blob/main/lib/java/pathland-core/src/main/java/dev/pathland/core/transport/FrameCodec.java): `lib/java/pathland-core/src/main/java/dev/pathland/core/transport/FrameCodec.java`
- [Rust diff engine](https://github.com/pathlanddev/pathland/blob/main/lib/rust/crates/pathland-engine/src/engine.rs): `lib/rust/crates/pathland-engine/src/engine.rs`

### Web surface

- [HTML rendering](https://github.com/pathlanddev/pathland/blob/main/lib/java/pathland-render-html/src/main/java/dev/pathland/render/html/HtmlRenderer.java): `lib/java/pathland-render-html/src/main/java/dev/pathland/render/html/HtmlRenderer.java`
- [JVM host adapters](https://github.com/pathlanddev/pathland/blob/main/lib/java/pathland-quarkus/src/main/java/dev/pathland/quarkus/PathlandSocket.java): `lib/java/pathland-quarkus/src/main/java/dev/pathland/quarkus/PathlandSocket.java`
- [DOM delta client](https://github.com/pathlanddev/pathland/blob/main/lib/typescript/src/apply.ts): `lib/typescript/src/apply.ts`
- [Client connection](https://github.com/pathlanddev/pathland/blob/main/lib/typescript/src/index.ts): `lib/typescript/src/index.ts`
- [Stateful navigation](https://github.com/pathlanddev/pathland/blob/main/lib/typescript/src/service-worker.ts): `lib/typescript/src/service-worker.ts`

### Native surfaces

- [GTK renderer](https://github.com/pathlanddev/pathland/blob/main/lib/rust/crates/pathland-render-gtk/src/lib.rs): `lib/rust/crates/pathland-render-gtk/src/lib.rs`
- [Qt renderer](https://github.com/pathlanddev/pathland/blob/main/lib/rust/crates/pathland-render-qt/src/renderer.rs): `lib/rust/crates/pathland-render-qt/src/renderer.rs`

### Composition

- [Proxy session](https://github.com/pathlanddev/pathland/blob/main/lib/java/pathland-server-core/src/main/java/dev/pathland/server/proxy/ProxySession.java): `lib/java/pathland-server-core/src/main/java/dev/pathland/server/proxy/ProxySession.java`

### Other components

- **Application developer**
- **Browser user**
- **Origin Pathland server**

## Connections

- Application developer → Kotlin view DSL: declares views (evidence: `README.md`)
- Application developer → Rust view API: declares views (evidence: `README.md`)
- Kotlin view DSL → Signals and state: uses signals
- Kotlin view DSL → View routing: supports navigation
- Kotlin view DSL → Server session: mounts in (evidence: `README.md`)
- Server session → HTML rendering: renders initial HTML (evidence: `lib/java/pathland-server-core/src/main/java/dev/pathland/server/PathlandSession.java`)
- Server session → Opcode protocol: emits deltas (evidence: `README.md`)
- Server session → Frame transport: sends frames (evidence: `lib/java/pathland-server-core/src/main/java/dev/pathland/server/PathlandSession.java`)
- Rust view API → Rust diff engine: drives view engine
- Rust diff engine → Opcode protocol: emits opcodes (evidence: `lib/rust/crates/pathland-engine/src/engine.rs`)
- Opcode protocol → Frame transport: encoded as frames (evidence: `lib/java/pathland-core/src/main/java/dev/pathland/core/transport/FrameCodec.java`)
- JVM host adapters → Server session: hosts sessions (evidence: `README.md`)
- HTML rendering → Browser user: serves HTML (evidence: `README.md`)
- Browser user → Client connection: opens live connection (evidence: `README.md`)
- Client connection → Frame transport: exchanges deltas (evidence: `README.md`)
- Client connection → DOM delta client: applies incoming frames (evidence: `lib/typescript/src/index.ts`)
- DOM delta client → Browser user: updates DOM (evidence: `README.md`)
- Client connection → Stateful navigation: registers worker (evidence: `lib/typescript/src/index.ts`)
- Rust diff engine → GTK renderer: drives native surface (evidence: `README.md`)
- Rust diff engine → Qt renderer: drives native surface (evidence: `README.md`)
- Server session → Proxy session: composes subtree (evidence: `lib/java/pathland-server-core/src/main/java/dev/pathland/server/PathlandSession.java`)
- Proxy session → Origin Pathland server: connects as client (evidence: `README.md`)
- Proxy session → Server session: splices opcode stream (evidence: `README.md`)