# hotwired/turbo architecture

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

- Interactive diagram: https://gitdiagram.com/hotwired/turbo
- Repository: https://github.com/hotwired/turbo

## Overview

Turbo is a browser-side HTML-over-the-wire navigation library. Its main workflow intercepts eligible links and forms, fetches responses, then updates page/history state without a full reload; Frames scope that workflow to regions, while Streams apply server-supplied actions. The README also identifies Turbo Native as an adapter capability. The map follows documented responsibilities and sampled calls; some subsystem links are omitted where source excerpts do not establish exact wiring.

Main entry points: [`src/core/session.js`](https://github.com/hotwired/turbo/blob/main/src/core/session.js) (Session), [`src/core/drive/visit.js`](https://github.com/hotwired/turbo/blob/main/src/core/drive/visit.js) (Visit), [`src/core/frames/frame_controller.js`](https://github.com/hotwired/turbo/blob/main/src/core/frames/frame_controller.js) (Frame controller), [`src/http/fetch_request.js`](https://github.com/hotwired/turbo/blob/main/src/http/fetch_request.js) (Fetch requests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_drive["Turbo Drive"]
  node_session["Session<br/>[session.js]"]
  node_linkobs["Link observers"]
  node_formobs["Form observers"]
  node_prefetch["Link prefetch"]
  node_navigator["Navigator<br/>[navigator.js]"]
  node_visit["Visit<br/>[visit.js]"]
  node_pageview["Page view<br/>[page_view.js]"]
  node_renderer["Page renderer<br/>[page_renderer.js]"]
  node_snapshot["Page snapshots<br/>[page_snapshot.js]"]
  node_history["History<br/>[history.js]"]
end

subgraph group_frames["Turbo Frames"]
  node_frameelement["Frame element<br/>[frame_element.js]"]
  node_framecontroller["Frame controller"]
  node_frameview["Frame view<br/>[frame_view.js]"]
  node_framerenderer["Frame renderer<br/>[frame_renderer.js]"]
end

subgraph group_streams["Turbo Streams"]
  node_streamsource["Stream source"]
  node_streamelement["Stream element<br/>[stream_element.js]"]
  node_streammessage["Stream message<br/>[stream_message.js]"]
  node_streamrenderer["Stream renderer"]
end

subgraph group_runtime["Runtime Services"]
  node_entry["Turbo entry<br/>[index.js]"]
  node_http["Fetch requests<br/>[fetch_request.js]"]
  node_response["Fetch response<br/>[fetch_response.js]"]
  node_cache[("Snapshot cache<br/>[snapshot_cache.js]")]
  node_adapter["Browser adapter<br/>[browser_adapter.js]"]
end

node_user(("Browser user"))
node_server(("HTML server"))
node_native(("Native app adapter"))

node_entry -->|"starts"| node_session
node_user -->|"clicks link"| node_linkobs
node_user -->|"submits form"| node_formobs
node_session -->|"starts observer"| node_linkobs
node_session -->|"starts observer"| node_formobs
node_session -->|"starts observer"| node_prefetch
node_linkobs -->|"proposes visit"| node_session
node_formobs -->|"submits navigation"| node_session
node_session -->|"proposes visit"| node_navigator
node_navigator -->|"starts visit"| node_visit
node_visit -->|"issues request"| node_http
node_http -->|"sends HTTP"| node_server
node_server -->|"returns HTML"| node_response
node_response -->|"provides response"| node_visit
node_visit -->|"renders snapshot"| node_pageview
node_pageview -->|"renders page"| node_renderer
node_renderer -->|"uses snapshot"| node_snapshot
node_visit -->|"updates history"| node_history
node_pageview -->|"reads and writes"| node_cache
node_session -->|"coordinates visit"| node_adapter
node_adapter -.->|"registers adapter"| node_native
node_prefetch -->|"prefetches request"| node_http
node_user -->|"interacts"| node_frameelement
node_entry -->|"registers element"| node_frameelement
node_frameelement -->|"delegates behavior"| node_framecontroller
node_framecontroller -->|"fetches frame"| node_http
node_http -->|"returns response"| node_framecontroller
node_framecontroller -->|"renders frame"| node_frameview
node_frameview -->|"uses renderer"| node_framerenderer
node_framecontroller -->|"proposes visit"| node_session
node_server -.->|"supplies stream"| node_streamsource
node_streamsource -->|"connects source"| node_session
node_server -->|"sends stream HTML"| node_streammessage
node_entry -->|"registers element"| node_streamelement
node_streamelement -->|"parses message"| node_streammessage
node_session -->|"renders message"| node_streamrenderer
node_streamrenderer -->|"applies actions"| node_streammessage

click node_entry "https://github.com/hotwired/turbo/blob/main/src/index.js"
click node_session "https://github.com/hotwired/turbo/blob/main/src/core/session.js"
click node_linkobs "https://github.com/hotwired/turbo/blob/main/src/observers/link_click_observer.js"
click node_formobs "https://github.com/hotwired/turbo/blob/main/src/observers/form_submit_observer.js"
click node_prefetch "https://github.com/hotwired/turbo/blob/main/src/observers/link_prefetch_observer.js"
click node_navigator "https://github.com/hotwired/turbo/blob/main/src/core/drive/navigator.js"
click node_visit "https://github.com/hotwired/turbo/blob/main/src/core/drive/visit.js"
click node_http "https://github.com/hotwired/turbo/blob/main/src/http/fetch_request.js"
click node_response "https://github.com/hotwired/turbo/blob/main/src/http/fetch_response.js"
click node_pageview "https://github.com/hotwired/turbo/blob/main/src/core/drive/page_view.js"
click node_renderer "https://github.com/hotwired/turbo/blob/main/src/core/drive/page_renderer.js"
click node_snapshot "https://github.com/hotwired/turbo/blob/main/src/core/drive/page_snapshot.js"
click node_history "https://github.com/hotwired/turbo/blob/main/src/core/drive/history.js"
click node_cache "https://github.com/hotwired/turbo/blob/main/src/core/drive/snapshot_cache.js"
click node_adapter "https://github.com/hotwired/turbo/blob/main/src/core/native/browser_adapter.js"
click node_frameelement "https://github.com/hotwired/turbo/blob/main/src/elements/frame_element.js"
click node_framecontroller "https://github.com/hotwired/turbo/blob/main/src/core/frames/frame_controller.js"
click node_frameview "https://github.com/hotwired/turbo/blob/main/src/core/frames/frame_view.js"
click node_framerenderer "https://github.com/hotwired/turbo/blob/main/src/core/frames/frame_renderer.js"
click node_streamsource "https://github.com/hotwired/turbo/blob/main/src/elements/stream_source_element.js"
click node_streamelement "https://github.com/hotwired/turbo/blob/main/src/elements/stream_element.js"
click node_streammessage "https://github.com/hotwired/turbo/blob/main/src/core/streams/stream_message.js"
click node_streamrenderer "https://github.com/hotwired/turbo/blob/main/src/core/streams/stream_message_renderer.js"

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_session,node_linkobs,node_formobs,node_prefetch,node_navigator,node_visit,node_pageview,node_renderer,node_snapshot,node_history,node_user toneBlue
class node_frameelement,node_framecontroller,node_frameview,node_framerenderer toneAmber
class node_streamsource,node_streamelement,node_streammessage,node_streamrenderer,node_server toneMint
class node_entry,node_http,node_response,node_cache,node_adapter toneRose
class node_native toneIndigo
```

## Components

### Turbo Drive

- [Session](https://github.com/hotwired/turbo/blob/main/src/core/session.js): `src/core/session.js`
- [Link observers](https://github.com/hotwired/turbo/blob/main/src/observers/link_click_observer.js): `src/observers/link_click_observer.js`
- [Form observers](https://github.com/hotwired/turbo/blob/main/src/observers/form_submit_observer.js): `src/observers/form_submit_observer.js`
- [Link prefetch](https://github.com/hotwired/turbo/blob/main/src/observers/link_prefetch_observer.js): `src/observers/link_prefetch_observer.js`
- [Navigator](https://github.com/hotwired/turbo/blob/main/src/core/drive/navigator.js): `src/core/drive/navigator.js`
- [Visit](https://github.com/hotwired/turbo/blob/main/src/core/drive/visit.js): `src/core/drive/visit.js`
- [Page view](https://github.com/hotwired/turbo/blob/main/src/core/drive/page_view.js): `src/core/drive/page_view.js`
- [Page renderer](https://github.com/hotwired/turbo/blob/main/src/core/drive/page_renderer.js): `src/core/drive/page_renderer.js`
- [Page snapshots](https://github.com/hotwired/turbo/blob/main/src/core/drive/page_snapshot.js): `src/core/drive/page_snapshot.js`
- [History](https://github.com/hotwired/turbo/blob/main/src/core/drive/history.js): `src/core/drive/history.js`

### Turbo Frames

- [Frame element](https://github.com/hotwired/turbo/blob/main/src/elements/frame_element.js): `src/elements/frame_element.js`
- [Frame controller](https://github.com/hotwired/turbo/blob/main/src/core/frames/frame_controller.js): `src/core/frames/frame_controller.js`
- [Frame view](https://github.com/hotwired/turbo/blob/main/src/core/frames/frame_view.js): `src/core/frames/frame_view.js`
- [Frame renderer](https://github.com/hotwired/turbo/blob/main/src/core/frames/frame_renderer.js): `src/core/frames/frame_renderer.js`

### Turbo Streams

- [Stream source](https://github.com/hotwired/turbo/blob/main/src/elements/stream_source_element.js): `src/elements/stream_source_element.js`
- [Stream element](https://github.com/hotwired/turbo/blob/main/src/elements/stream_element.js): `src/elements/stream_element.js`
- [Stream message](https://github.com/hotwired/turbo/blob/main/src/core/streams/stream_message.js): `src/core/streams/stream_message.js`
- [Stream renderer](https://github.com/hotwired/turbo/blob/main/src/core/streams/stream_message_renderer.js): `src/core/streams/stream_message_renderer.js`

### Runtime Services

- [Turbo entry](https://github.com/hotwired/turbo/blob/main/src/index.js): `src/index.js`
- [Fetch requests](https://github.com/hotwired/turbo/blob/main/src/http/fetch_request.js): `src/http/fetch_request.js`
- [Fetch response](https://github.com/hotwired/turbo/blob/main/src/http/fetch_response.js): `src/http/fetch_response.js`
- [Snapshot cache](https://github.com/hotwired/turbo/blob/main/src/core/drive/snapshot_cache.js): `src/core/drive/snapshot_cache.js`
- [Browser adapter](https://github.com/hotwired/turbo/blob/main/src/core/native/browser_adapter.js): `src/core/native/browser_adapter.js`

### Other components

- **Browser user**
- **HTML server**
- **Native app adapter**

## Connections

- Turbo entry → Session: starts
- Browser user → Link observers: clicks link
- Browser user → Form observers: submits form
- Session → Link observers: starts observer
- Session → Form observers: starts observer
- Session → Link prefetch: starts observer
- Link observers → Session: proposes visit
- Form observers → Session: submits navigation
- Session → Navigator: proposes visit
- Navigator → Visit: starts visit
- Visit → Fetch requests: issues request
- Fetch requests → HTML server: sends HTTP
- HTML server → Fetch response: returns HTML
- Fetch response → Visit: provides response
- Visit → Page view: renders snapshot
- Page view → Page renderer: renders page
- Page renderer → Page snapshots: uses snapshot
- Visit → History: updates history
- Page view → Snapshot cache: reads and writes
- Session → Browser adapter: coordinates visit
- Browser adapter → Native app adapter: registers adapter
- Link prefetch → Fetch requests: prefetches request
- Browser user → Frame element: interacts
- Turbo entry → Frame element: registers element
- Frame element → Frame controller: delegates behavior
- Frame controller → Fetch requests: fetches frame
- Fetch requests → Frame controller: returns response
- Frame controller → Frame view: renders frame
- Frame view → Frame renderer: uses renderer
- Frame controller → Session: proposes visit
- HTML server → Stream source: supplies stream
- Stream source → Session: connects source
- HTML server → Stream message: sends stream HTML
- Turbo entry → Stream element: registers element
- Stream element → Stream message: parses message
- Session → Stream renderer: renders message
- Stream renderer → Stream message: applies actions