# jasonkneen/curf architecture

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

- Interactive diagram: https://gitdiagram.com/jasonkneen/curf
- Repository: https://github.com/jasonkneen/curf

## Overview

curf is a scriptable browser with a graphical front end and a loopback HTTP API. The principal workflow is a user or agent entering a URL/search, browsing a page, then extracting or manipulating page content and recording annotations or changes. The README documents distinct Cluso Inspector and security/site-info capabilities as well. The Qt front end and shared helpers are sampled; the native WebKit front end and detailed route implementations are not, so their internal wiring is not expanded.

Main entry points: [`src/qt/main.cpp`](https://github.com/jasonkneen/curf/blob/main/src/qt/main.cpp) (Qt browser), [`src/main.mm`](https://github.com/jasonkneen/curf/blob/main/src/main.mm) (WebKit browser), [`src/inject.js.hpp`](https://github.com/jasonkneen/curf/blob/main/src/inject.js.hpp) (Page instrumentation), [`src/cluso.js.hpp`](https://github.com/jasonkneen/curf/blob/main/src/cluso.js.hpp) (Embedded Inspector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser UI"]
  node_qt["Qt browser<br/>[main.cpp]"]
  node_webkit["WebKit browser<br/>[main.mm]"]
  node_url["Input resolver<br/>[url_util.cpp]"]
end

subgraph group_automation["Script Control"]
  node_control["HTTP control server<br/>[control_server.cpp]"]
  node_ctl["curfctl client<br/>[curfctl.py]"]
end

subgraph group_page["Page Interaction"]
  node_inject["Page instrumentation<br/>[inject.js.hpp]"]
  node_changes[("Change log<br/>[main.cpp]")]
  node_annotations[("Annotations<br/>[main.cpp]")]
end

subgraph group_inspection["Inspection Tools"]
  node_cluso["Cluso Inspector<br/>[cluso.hpp]"]
  node_clusojs["Embedded Inspector<br/>[cluso.js.hpp]"]
end

node_person(("Browser user"))
node_agent(("Automation client"))
node_web["Web content"]
node_relay["Cluso relay"]
node_cert["Certificate services"]

node_person -->|"browses"| node_qt
node_person -->|"browses"| node_webkit
node_qt -->|"resolves input"| node_url
node_qt -->|"loads page"| node_web
node_webkit -->|"resolves input"| node_url
node_webkit -->|"loads page"| node_web
node_agent -->|"issues commands"| node_ctl
node_ctl -->|"HTTP requests"| node_control
node_control -->|"dispatches routes"| node_qt
node_qt -->|"injects script"| node_inject
node_inject -->|"observes and acts"| node_web
node_qt -->|"records changes"| node_changes
node_inject -->|"reports mutations"| node_qt
node_qt -->|"saves annotations"| node_annotations
node_qt -->|"configures inspector"| node_cluso
node_cluso -->|"embeds script"| node_clusojs
node_clusojs -->|"injects inspector"| node_web
node_clusojs -.->|"sends comments"| node_relay
node_qt -->|"checks certificates"| node_cert

click node_qt "https://github.com/jasonkneen/curf/blob/main/src/qt/main.cpp"
click node_webkit "https://github.com/jasonkneen/curf/blob/main/src/main.mm"
click node_url "https://github.com/jasonkneen/curf/blob/main/src/url_util.cpp"
click node_control "https://github.com/jasonkneen/curf/blob/main/src/control_server.cpp"
click node_ctl "https://github.com/jasonkneen/curf/blob/main/curfctl.py"
click node_inject "https://github.com/jasonkneen/curf/blob/main/src/inject.js.hpp"
click node_changes "https://github.com/jasonkneen/curf/blob/main/src/qt/main.cpp"
click node_annotations "https://github.com/jasonkneen/curf/blob/main/src/qt/main.cpp"
click node_cluso "https://github.com/jasonkneen/curf/blob/main/src/cluso.hpp"
click node_clusojs "https://github.com/jasonkneen/curf/blob/main/src/cluso.js.hpp"

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_qt,node_webkit,node_url,node_person,node_agent toneBlue
class node_control,node_ctl toneAmber
class node_inject,node_changes,node_annotations toneMint
class node_cluso,node_clusojs toneRose
class node_web,node_relay,node_cert toneIndigo
```

## Components

### Browser UI

- [Qt browser](https://github.com/jasonkneen/curf/blob/main/src/qt/main.cpp): `src/qt/main.cpp`
- [WebKit browser](https://github.com/jasonkneen/curf/blob/main/src/main.mm): `src/main.mm`
- [Input resolver](https://github.com/jasonkneen/curf/blob/main/src/url_util.cpp): `src/url_util.cpp`

### Script Control

- [HTTP control server](https://github.com/jasonkneen/curf/blob/main/src/control_server.cpp): `src/control_server.cpp`
- [curfctl client](https://github.com/jasonkneen/curf/blob/main/curfctl.py): `curfctl.py`

### Page Interaction

- [Page instrumentation](https://github.com/jasonkneen/curf/blob/main/src/inject.js.hpp): `src/inject.js.hpp`
- [Change log](https://github.com/jasonkneen/curf/blob/main/src/qt/main.cpp): `src/qt/main.cpp`
- [Annotations](https://github.com/jasonkneen/curf/blob/main/src/qt/main.cpp): `src/qt/main.cpp`

### Inspection Tools

- [Cluso Inspector](https://github.com/jasonkneen/curf/blob/main/src/cluso.hpp): `src/cluso.hpp`
- [Embedded Inspector](https://github.com/jasonkneen/curf/blob/main/src/cluso.js.hpp): `src/cluso.js.hpp`

### Other components

- **Browser user**
- **Automation client**
- **Web content**
- **Cluso relay**
- **Certificate services**

## Connections

- Browser user → Qt browser: browses
- Browser user → WebKit browser: browses
- Qt browser → Input resolver: resolves input
- Qt browser → Web content: loads page
- WebKit browser → Input resolver: resolves input
- WebKit browser → Web content: loads page
- Automation client → curfctl client: issues commands
- curfctl client → HTTP control server: HTTP requests
- HTTP control server → Qt browser: dispatches routes
- Qt browser → Page instrumentation: injects script
- Page instrumentation → Web content: observes and acts
- Qt browser → Change log: records changes
- Page instrumentation → Qt browser: reports mutations
- Qt browser → Annotations: saves annotations
- Qt browser → Cluso Inspector: configures inspector
- Cluso Inspector → Embedded Inspector: embeds script
- Embedded Inspector → Web content: injects inspector
- Embedded Inspector → Cluso relay: sends comments
- Qt browser → Certificate services: checks certificates