# phucvohoai/nyx architecture

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

- Interactive diagram: https://gitdiagram.com/phucvohoai/nyx
- Repository: https://github.com/phucvohoai/nyx

## Overview

Nyx is a keyboard-driven terminal text browser. The primary workflow is user search or direct navigation, followed by page retrieval, structured reader extraction, and interactive reading; forms, images, and Tor routing are additional capabilities. The graph includes the documented subsystems, but some wiring is represented only where the excerpts or README establish it; unsampled implementation details are not assumed.

Main entry points: [`crates/nyx-tui/src/main.rs`](https://github.com/phucvohoai/nyx/blob/main/crates/nyx-tui/src/main.rs) (Terminal app), [`crates/nyx-pal/src/lib.rs`](https://github.com/phucvohoai/nyx/blob/main/crates/nyx-pal/src/lib.rs) (Page requests), [`crates/nyx-core/src/parser.rs`](https://github.com/phucvohoai/nyx/blob/main/crates/nyx-core/src/parser.rs) (HTML extraction), [`crates/nyx-core/src/search.rs`](https://github.com/phucvohoai/nyx/blob/main/crates/nyx-core/src/search.rs) (Search parsing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Terminal interface"]
  node_tui["Terminal app<br/>[main.rs]"]
  node_linknav["Link navigation<br/>[main.rs]"]
  node_formui["Form controls<br/>[main.rs]"]
  node_imageview["Image reader<br/>[main.rs]"]
end

subgraph group_core["Browsing core"]
  node_appstate["Navigation state<br/>[state.rs]"]
  node_searchflow["Search workflow<br/>[main.rs]"]
  node_searchparse["Search parsing<br/>[search.rs]"]
  node_directurl["URL normalization<br/>[search.rs]"]
end

subgraph group_network["Networking and privacy"]
  node_pagefetch["Page requests<br/>[lib.rs]"]
  node_formsubmit["Form submission<br/>[lib.rs]"]
  node_imagerequests["Image requests<br/>[lib.rs]"]
  node_torroute["Tor route checks<br/>[lib.rs]"]
  node_vault[("Encrypted session vault<br/>[lib.rs]")]
  node_cookies["Session cookies<br/>[lib.rs]"]
end

subgraph group_content["Page features"]
  node_parser["HTML extraction<br/>[parser.rs]"]
  node_reader["Reader document<br/>[parser.rs]"]
  node_formparse["Form extraction<br/>[parser.rs]"]
end

node_user(("Browser user"))
node_searchservice["SearXNG service"]
node_web["Web pages"]
node_tor["Tor SOCKS5 service"]

node_user -->|"uses controls"| node_tui
node_tui -->|"updates views"| node_appstate
node_tui -->|"starts search"| node_searchflow
node_searchflow -->|"parses results"| node_searchparse
node_searchflow -->|"requests results"| node_searchservice
node_searchparse -.->|"provides results"| node_appstate
node_tui -.->|"normalizes address"| node_directurl
node_tui -->|"loads page"| node_pagefetch
node_pagefetch -->|"requests page"| node_web
node_pagefetch -->|"checks route"| node_torroute
node_torroute -->|"verifies proxy"| node_tor
node_pagefetch -.->|"supplies HTML"| node_parser
node_parser -->|"extracts content"| node_reader
node_reader -->|"renders document"| node_tui
node_tui -->|"dispatches selection"| node_linknav
node_linknav -->|"loads target"| node_pagefetch
node_parser -->|"extracts forms"| node_formparse
node_tui -->|"edits fields"| node_formui
node_formui -.->|"submits form"| node_formsubmit
node_formsubmit -->|"sends request"| node_web
node_tui -->|"opens images"| node_imageview
node_imageview -->|"downloads image"| node_imagerequests
node_imagerequests -->|"fetches bytes"| node_web
node_tui -->|"unlocks vault"| node_vault
node_pagefetch -.->|"uses sessions"| node_cookies

click node_tui "https://github.com/phucvohoai/nyx/blob/main/crates/nyx-tui/src/main.rs"
click node_appstate "https://github.com/phucvohoai/nyx/blob/main/crates/nyx-core/src/state.rs"
click node_searchflow "https://github.com/phucvohoai/nyx/blob/main/crates/nyx-tui/src/main.rs"
click node_searchparse "https://github.com/phucvohoai/nyx/blob/main/crates/nyx-core/src/search.rs"
click node_directurl "https://github.com/phucvohoai/nyx/blob/main/crates/nyx-core/src/search.rs"
click node_pagefetch "https://github.com/phucvohoai/nyx/blob/main/crates/nyx-pal/src/lib.rs"
click node_parser "https://github.com/phucvohoai/nyx/blob/main/crates/nyx-core/src/parser.rs"
click node_reader "https://github.com/phucvohoai/nyx/blob/main/crates/nyx-core/src/parser.rs"
click node_linknav "https://github.com/phucvohoai/nyx/blob/main/crates/nyx-tui/src/main.rs"
click node_formui "https://github.com/phucvohoai/nyx/blob/main/crates/nyx-tui/src/main.rs"
click node_formparse "https://github.com/phucvohoai/nyx/blob/main/crates/nyx-core/src/parser.rs"
click node_formsubmit "https://github.com/phucvohoai/nyx/blob/main/crates/nyx-pal/src/lib.rs"
click node_imageview "https://github.com/phucvohoai/nyx/blob/main/crates/nyx-tui/src/main.rs"
click node_imagerequests "https://github.com/phucvohoai/nyx/blob/main/crates/nyx-pal/src/lib.rs"
click node_torroute "https://github.com/phucvohoai/nyx/blob/main/crates/nyx-pal/src/lib.rs"
click node_vault "https://github.com/phucvohoai/nyx/blob/main/crates/nyx-pal/src/lib.rs"
click node_cookies "https://github.com/phucvohoai/nyx/blob/main/crates/nyx-pal/src/lib.rs"

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_tui,node_linknav,node_formui,node_imageview,node_user toneBlue
class node_appstate,node_searchflow,node_searchparse,node_directurl toneAmber
class node_pagefetch,node_formsubmit,node_imagerequests,node_torroute,node_vault,node_cookies toneMint
class node_parser,node_reader,node_formparse toneRose
class node_searchservice,node_web,node_tor toneIndigo
```

## Components

### Terminal interface

- [Terminal app](https://github.com/phucvohoai/nyx/blob/main/crates/nyx-tui/src/main.rs): `crates/nyx-tui/src/main.rs`
- [Link navigation](https://github.com/phucvohoai/nyx/blob/main/crates/nyx-tui/src/main.rs): `crates/nyx-tui/src/main.rs`
- [Form controls](https://github.com/phucvohoai/nyx/blob/main/crates/nyx-tui/src/main.rs): `crates/nyx-tui/src/main.rs`
- [Image reader](https://github.com/phucvohoai/nyx/blob/main/crates/nyx-tui/src/main.rs): `crates/nyx-tui/src/main.rs`

### Browsing core

- [Navigation state](https://github.com/phucvohoai/nyx/blob/main/crates/nyx-core/src/state.rs): `crates/nyx-core/src/state.rs`
- [Search workflow](https://github.com/phucvohoai/nyx/blob/main/crates/nyx-tui/src/main.rs): `crates/nyx-tui/src/main.rs`
- [Search parsing](https://github.com/phucvohoai/nyx/blob/main/crates/nyx-core/src/search.rs): `crates/nyx-core/src/search.rs`
- [URL normalization](https://github.com/phucvohoai/nyx/blob/main/crates/nyx-core/src/search.rs): `crates/nyx-core/src/search.rs`

### Networking and privacy

- [Page requests](https://github.com/phucvohoai/nyx/blob/main/crates/nyx-pal/src/lib.rs): `crates/nyx-pal/src/lib.rs`
- [Form submission](https://github.com/phucvohoai/nyx/blob/main/crates/nyx-pal/src/lib.rs): `crates/nyx-pal/src/lib.rs`
- [Image requests](https://github.com/phucvohoai/nyx/blob/main/crates/nyx-pal/src/lib.rs): `crates/nyx-pal/src/lib.rs`
- [Tor route checks](https://github.com/phucvohoai/nyx/blob/main/crates/nyx-pal/src/lib.rs): `crates/nyx-pal/src/lib.rs`
- [Encrypted session vault](https://github.com/phucvohoai/nyx/blob/main/crates/nyx-pal/src/lib.rs): `crates/nyx-pal/src/lib.rs`
- [Session cookies](https://github.com/phucvohoai/nyx/blob/main/crates/nyx-pal/src/lib.rs): `crates/nyx-pal/src/lib.rs`

### Page features

- [HTML extraction](https://github.com/phucvohoai/nyx/blob/main/crates/nyx-core/src/parser.rs): `crates/nyx-core/src/parser.rs`
- [Reader document](https://github.com/phucvohoai/nyx/blob/main/crates/nyx-core/src/parser.rs): `crates/nyx-core/src/parser.rs`
- [Form extraction](https://github.com/phucvohoai/nyx/blob/main/crates/nyx-core/src/parser.rs): `crates/nyx-core/src/parser.rs`

### Other components

- **Browser user**
- **SearXNG service**
- **Web pages**
- **Tor SOCKS5 service**

## Connections

- Browser user → Terminal app: uses controls (evidence: `README.md`)
- Terminal app → Navigation state: updates views (evidence: `crates/nyx-core/src/state.rs`)
- Terminal app → Search workflow: starts search (evidence: `README.md`)
- Search workflow → Search parsing: parses results (evidence: `README.md`)
- Search workflow → SearXNG service: requests results (evidence: `README.md`)
- Search parsing → Navigation state: provides results
- Terminal app → URL normalization: normalizes address
- Terminal app → Page requests: loads page (evidence: `crates/nyx-tui/src/main.rs`)
- Page requests → Web pages: requests page (evidence: `README.md`)
- Page requests → Tor route checks: checks route (evidence: `crates/nyx-pal/src/lib.rs`)
- Tor route checks → Tor SOCKS5 service: verifies proxy (evidence: `README.md`)
- Page requests → HTML extraction: supplies HTML
- HTML extraction → Reader document: extracts content (evidence: `crates/nyx-core/src/parser.rs`)
- Reader document → Terminal app: renders document (evidence: `README.md`)
- Terminal app → Link navigation: dispatches selection (evidence: `crates/nyx-tui/src/main.rs`)
- Link navigation → Page requests: loads target (evidence: `crates/nyx-tui/src/main.rs`)
- HTML extraction → Form extraction: extracts forms (evidence: `crates/nyx-core/src/parser.rs`)
- Terminal app → Form controls: edits fields (evidence: `README.md`)
- Form controls → Form submission: submits form
- Form submission → Web pages: sends request (evidence: `crates/nyx-pal/src/lib.rs`)
- Terminal app → Image reader: opens images (evidence: `README.md`)
- Image reader → Image requests: downloads image (evidence: `crates/nyx-tui/src/main.rs`)
- Image requests → Web pages: fetches bytes (evidence: `crates/nyx-pal/src/lib.rs`)
- Terminal app → Encrypted session vault: unlocks vault (evidence: `README.md`)
- Page requests → Session cookies: uses sessions (evidence: `crates/nyx-pal/src/lib.rs`)
