samiandClaude Opus 5
8bb683b09d
Lays out Velox Download Manager (IDM-class download manager for Ubuntu 26.04) as a monorepo ready for parallel lane development. No implementation code by design. - docs/: architecture, roadmap M0-M7, IDM-parity GUI spec, engine design, Firefox extension spec, risks/spikes, packaging - contracts/: wire-contract skeleton (JSON Schema + fixture templates) — the single synchronization point between lanes - docs/agents/: one brief per lane (PROTO, CORE, DAEMON, GUI, EXT, PKG/QA) with owned directories, build order and definition of done - CLAUDE.md: rules of engagement — lane ownership, layering, non-negotiables - CMake scaffolding with dev/tsan/release/ci presets Two environment findings shape the design: Firefox here is the Mozilla snap (native-messaging risk, so the extension carries a loopback-WebSocket fallback), and Wayland forbids passive clipboard monitoring (so clipboard capture is explicit-action-first). Co-Authored-By: Claude Opus 5 <[email protected]>
115 lines
6.3 KiB
Markdown
115 lines
6.3 KiB
Markdown
# Velox Download Manager (VDM)
|
||
|
||
An IDM-class download manager for Ubuntu 26.04 LTS: multi-segment accelerated HTTP(S)
|
||
downloading, resume, categories and automatic file distribution, queues and scheduler,
|
||
speed limiter, a Firefox extension that captures downloads automatically, and clipboard
|
||
link capture.
|
||
|
||
> **Name is a placeholder.** Binaries are `veloxd`, `velox-gui`, `velox`, `velox-nmhost`.
|
||
> Rename before first release if you want something else — do it in M0, never later.
|
||
|
||
---
|
||
|
||
## Status
|
||
|
||
**Phase M0 — scaffolding.** No implementation code exists yet. This repository currently
|
||
contains the architecture, the wire contract, the roadmap, and one brief per build lane
|
||
so that several agents can work in parallel without colliding.
|
||
|
||
Start here:
|
||
|
||
| Document | What it answers |
|
||
|---|---|
|
||
| [docs/01-architecture.md](docs/01-architecture.md) | Process model, why four binaries, framework choices and why |
|
||
| [docs/02-roadmap.md](docs/02-roadmap.md) | Milestones M0–M7, what runs in parallel, exit gates |
|
||
| [docs/03-gui-spec.md](docs/03-gui-spec.md) | IDM-parity UI: every window, dialog, column, menu |
|
||
| [docs/04-engine-design.md](docs/04-engine-design.md) | Segmentation, resume, buffers, rate limiting, disk I/O |
|
||
| [docs/05-extension-spec.md](docs/05-extension-spec.md) | Firefox capture, transports, pairing, media grabber |
|
||
| [docs/06-risks-and-spikes.md](docs/06-risks-and-spikes.md) | Snap Firefox, Wayland clipboard, and the other landmines |
|
||
| [docs/07-packaging.md](docs/07-packaging.md) | .deb/PPA, Flatpak, AMO signing, install layout |
|
||
| [contracts/README.md](contracts/README.md) | **The interface.** Both sides build against this |
|
||
| [CLAUDE.md](CLAUDE.md) | Rules of engagement for agents working in this repo |
|
||
|
||
Per-lane briefs live in [docs/agents/](docs/agents/) — one per agent, each with an owned
|
||
directory list, a definition of done, and the files it must never touch.
|
||
|
||
---
|
||
|
||
## Architecture in one picture
|
||
|
||
```
|
||
┌────────────────────┐ native messaging (stdio JSON) ┌──────────────┐
|
||
│ Firefox extension │◄───────────── or ──────────────►│ velox-nmhost │
|
||
│ (MV3, TS) │ loopback WS 127.0.0.1 + token └──────┬───────┘
|
||
└────────────────────┘ │
|
||
│
|
||
┌────────────────────┐ ▼
|
||
│ velox-gui (Qt 6) │◄──── JSON-RPC 2.0 over Unix socket ──► ┌─────────────┐
|
||
└────────────────────┘ $XDG_RUNTIME_DIR/velox/velox.sock │ veloxd │
|
||
│ (daemon) │
|
||
┌────────────────────┐ │ │
|
||
│ velox (CLI) │◄───────────────────────────────────────┤ libveloxcore│
|
||
└────────────────────┘ └──────┬──────┘
|
||
│
|
||
SQLite + sparse files
|
||
```
|
||
|
||
The daemon owns all state and all sockets. The GUI is a *view* — closing it does not stop
|
||
a download. The extension never touches the disk; it hands URL + headers + cookies to the
|
||
daemon and gets a task id back.
|
||
|
||
---
|
||
|
||
## Repository layout
|
||
|
||
```
|
||
vdm/
|
||
├── contracts/ ⭐ Wire contract: JSON Schema, fixtures, codegen. Frozen per version.
|
||
├── core/ C++23 libveloxcore — engine. No UI, no RPC, no SQL.
|
||
├── daemon/ C++23 veloxd — RPC server, scheduler, queues, SQLite store.
|
||
├── gui/ C++23 velox-gui — Qt 6 Widgets, IDM-parity UI.
|
||
├── cli/ C++23 velox — scriptable client.
|
||
├── nmhost/ C++23 velox-nmhost — Firefox native-messaging bridge (thin pipe).
|
||
├── extension/ TS Firefox MV3 WebExtension.
|
||
├── tools/
|
||
│ ├── mockd/ TS mock daemon — lets GUI + extension work before veloxd exists.
|
||
│ ├── testserver/ Deliberately hostile HTTP server (no Range, flaky, redirects, auth).
|
||
│ ├── bench/ Throughput and CPU benchmarks.
|
||
│ └── fuzz/ libFuzzer targets for parsers.
|
||
├── tests/
|
||
│ ├── conformance/ Protocol suite. Every lane must pass it. Gate for merging.
|
||
│ ├── integration/ veloxd + testserver.
|
||
│ └── e2e/ Playwright: real Firefox + real daemon + real file on disk.
|
||
├── packaging/ debian/, flatpak/, appimage/, native-host manifests.
|
||
└── docs/ Everything above, plus adr/ and agents/.
|
||
```
|
||
|
||
## Toolchain bootstrap
|
||
|
||
Surveyed on this machine 2026-09-09 — **most of it is already installed**:
|
||
|
||
| Present | Version |
|
||
|---|---|
|
||
| git · cmake · ninja · g++ · gdb | 2.53.0 · 4.2.3 · — · 15.2.0 (C++23 ready) |
|
||
| qt6-base-dev · qt6-tools-dev · qt6-tools-dev-tools | ✓ |
|
||
| libcurl4-openssl-dev · libsqlite3-dev · nlohmann-json3-dev · libssl-dev | ✓ |
|
||
| libavformat-dev · libavcodec-dev · ffmpeg | ✓ |
|
||
| clang-format · clang-tidy · python3 · pkg-config | ✓ |
|
||
|
||
**Only these four are missing:**
|
||
|
||
```bash
|
||
sudo apt update && sudo apt install -y \
|
||
libqt6svg6-dev \ # GUI: SVG icon rendering
|
||
libsecret-1-dev \ # DAEMON: Secret Service for site logins
|
||
nodejs npm \ # EXT + PROTO: extension build, mockd, conformance runner
|
||
clang # optional: libFuzzer targets in M7
|
||
```
|
||
|
||
Node in the 26.04 archive may lag; if the extension toolchain needs 22+, use `nvm`.
|
||
|
||
Verify with `cmake --preset dev && cmake --build --preset dev` once lane CORE lands its
|
||
first target. Note **CMake 4.2.3** is installed — newer than the `3.28` floor in
|
||
`CMakeLists.txt`, and it hard-errors on `cmake_minimum_required` below 3.5, so no
|
||
dependency may ship a pre-3.5 CMake file.
|