# vani-tty1/velocity architecture

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

- Interactive diagram: https://gitdiagram.com/vani-tty1/velocity
- Repository: https://github.com/vani-tty1/velocity

## Overview

Velocity is a GTK/Libadwaita desktop speed-test app using LibreSpeed servers. A user opens the app, starts a test, and sees server selection, latency/jitter, download and upload results; the window also presents saved history and preferences. The sampled code shows application startup, window-to-engine use, server-list loading, history persistence, and transfer behavior. Some engine-to-stage calls are not visible in the excerpts, so those links are marked unverified rather than inferred as certain.

Main entry points: [`src/velocity-window.c`](https://github.com/vani-tty1/velocity/blob/main/src/velocity-window.c) (Test window), [`src/velocity-application.c`](https://github.com/vani-tty1/velocity/blob/main/src/velocity-application.c) (Application lifecycle), [`src/velocity-speedtest.c`](https://github.com/vani-tty1/velocity/blob/main/src/velocity-speedtest.c) (Test coordinator), [`src/velocity-speedtest-servers.c`](https://github.com/vani-tty1/velocity/blob/main/src/velocity-speedtest-servers.c) (Server discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Desktop application"]
  node_entry["Program entry<br/>[main.c]"]
  node_application["Application lifecycle"]
end

subgraph group_ui["User interface"]
  node_window["Test window<br/>[velocity-window.c]"]
  node_preferences["Preferences dialog"]
  node_accent["Accent color<br/>[velocity-accent.c]"]
  node_history[("Result history<br/>[velocity-window.c]")]
end

subgraph group_engine["Speed-test engine"]
  node_engine["Test coordinator"]
end

subgraph group_network["Server and network stages"]
  node_server_list["Server discovery"]
  node_latency["Ping and jitter"]
  node_transfer["Download and upload"]
end

node_user(("User"))
node_librespeed{{"LibreSpeed servers"}}

node_user -->|"launches"| node_entry
node_entry -->|"creates and runs"| node_application
node_application -->|"presents"| node_window
node_application -->|"opens"| node_preferences
node_application -->|"initializes"| node_accent
node_user -.->|"starts test"| node_window
node_window -->|"reads results; controls test"| node_engine
node_window -->|"reads and writes"| node_history
node_window -->|"loads servers"| node_server_list
node_engine -.->|"delegates discovery"| node_server_list
node_server_list -.->|"fetches server lists"| node_librespeed
node_server_list -->|"starts ping"| node_latency
node_engine -.->|"runs latency stage"| node_latency
node_engine -.->|"runs transfer stages"| node_transfer
node_transfer -.->|"transfers test data"| node_librespeed

click node_entry "https://github.com/vani-tty1/velocity/blob/main/src/main.c"
click node_application "https://github.com/vani-tty1/velocity/blob/main/src/velocity-application.c"
click node_window "https://github.com/vani-tty1/velocity/blob/main/src/velocity-window.c"
click node_preferences "https://github.com/vani-tty1/velocity/blob/main/src/velocity-preferences-dialog.c"
click node_accent "https://github.com/vani-tty1/velocity/blob/main/src/velocity-accent.c"
click node_history "https://github.com/vani-tty1/velocity/blob/main/src/velocity-window.c"
click node_engine "https://github.com/vani-tty1/velocity/blob/main/src/velocity-speedtest.c"
click node_server_list "https://github.com/vani-tty1/velocity/blob/main/src/velocity-speedtest-servers.c"
click node_latency "https://github.com/vani-tty1/velocity/blob/main/src/velocity-speedtest-ping.c"
click node_transfer "https://github.com/vani-tty1/velocity/blob/main/src/velocity-speedtest-transfer.c"

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_entry,node_application,node_user toneBlue
class node_window,node_preferences,node_accent,node_history toneAmber
class node_engine,node_librespeed toneMint
class node_server_list,node_latency,node_transfer toneRose
```

## Components

### Desktop application

- [Program entry](https://github.com/vani-tty1/velocity/blob/main/src/main.c): `src/main.c`
- [Application lifecycle](https://github.com/vani-tty1/velocity/blob/main/src/velocity-application.c): `src/velocity-application.c`

### User interface

- [Test window](https://github.com/vani-tty1/velocity/blob/main/src/velocity-window.c): `src/velocity-window.c`
- [Preferences dialog](https://github.com/vani-tty1/velocity/blob/main/src/velocity-preferences-dialog.c): `src/velocity-preferences-dialog.c`
- [Accent color](https://github.com/vani-tty1/velocity/blob/main/src/velocity-accent.c): `src/velocity-accent.c`
- [Result history](https://github.com/vani-tty1/velocity/blob/main/src/velocity-window.c): `src/velocity-window.c`

### Speed-test engine

- [Test coordinator](https://github.com/vani-tty1/velocity/blob/main/src/velocity-speedtest.c): `src/velocity-speedtest.c`

### Server and network stages

- [Server discovery](https://github.com/vani-tty1/velocity/blob/main/src/velocity-speedtest-servers.c): `src/velocity-speedtest-servers.c`
- [Ping and jitter](https://github.com/vani-tty1/velocity/blob/main/src/velocity-speedtest-ping.c): `src/velocity-speedtest-ping.c`
- [Download and upload](https://github.com/vani-tty1/velocity/blob/main/src/velocity-speedtest-transfer.c): `src/velocity-speedtest-transfer.c`

### Other components

- **User**
- **LibreSpeed servers**

## Connections

- User → Program entry: launches (evidence: `src/main.c`)
- Program entry → Application lifecycle: creates and runs (evidence: `src/main.c`)
- Application lifecycle → Test window: presents (evidence: `src/velocity-application.c`)
- Application lifecycle → Preferences dialog: opens (evidence: `src/velocity-application.c`)
- Application lifecycle → Accent color: initializes (evidence: `src/velocity-application.c`)
- User → Test window: starts test
- Test window → Test coordinator: reads results; controls test (evidence: `src/velocity-window.c`)
- Test window → Result history: reads and writes (evidence: `src/velocity-window.c`)
- Test window → Server discovery: loads servers (evidence: `src/velocity-window.c`)
- Test coordinator → Server discovery: delegates discovery
- Server discovery → LibreSpeed servers: fetches server lists
- Server discovery → Ping and jitter: starts ping (evidence: `src/velocity-speedtest-servers.c`)
- Test coordinator → Ping and jitter: runs latency stage
- Test coordinator → Download and upload: runs transfer stages
- Download and upload → LibreSpeed servers: transfers test data
