Skip to content

Commit d270d82

Browse files
quantDIYquantDIY
committed
docs(architecture): Codify absolute domain topology (Habitats, Nests, 5-Tier System) to Markdown
1 parent be92bef commit d270d82

3 files changed

Lines changed: 150 additions & 0 deletions

File tree

‎.agent/skills/quanux_topology_core.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
name: QuanuX Topology Core
3+
description: Absolute domain topology of the QuanuX ecosystem defining Habitats, Nests, and the 5 Tier System.
4+
---
5+
# QuanuX Topology Core Mandate
6+
7+
> **IMMORTAL GUIDANCE**: You must check which Tier a Nest belongs to before writing a single line of code.
8+
9+
## Absolute Nomenclature
10+
- **Habitat**: The physical or virtual OS boundary (e.g., your local desktop, an Ubuntu VM, a bare-metal server). It is the conditioned soil.
11+
- **Nest**: The sovereign logic process deployed into the Habitat (e.g., trading engines, AI models, observation layers). "Payload" is deprecated. A Habitat can host one massive Nest or countless microscopic Nests.
12+
13+
## The QuanuX Tier System (The Topological Law)
14+
15+
### Tier 1: The Server (Command Center)
16+
- **Identity:** The orchestrator and heart of the system.
17+
- **Environment:** Remote cloud server, local workstation, or desktop.
18+
- **Tech Stack:** Hosts web servers, APIs, strategy repositories, broker APIs. Runs the `quanuxctl` CLI (Python). Communicates to the cluster via Python NATS clients (`nats-py`).
19+
- **Rule:** It does not execute kinetic trades. It deploys Nests to Habitats.
20+
21+
### Tier 2: The Polyglot Nests (Flexibility & Intelligence)
22+
- **Identity:** AI strategy labs, observation layers, and standard API execution (TopstepX, IBKR TWS).
23+
- **Environment:** Extremely flexible. Can be deployed remotely or run locally on the Tier 1 desktop without strict OS conditioning.
24+
- **Tech Stack:** C++, Python, Cython, Golang. Heavily integrated with Anaconda.
25+
- **Networking Protocol:** Uses CNATS (`libnats-c`) if compiled in C++ for cluster communication. Uses ZMQ (ZeroMQ) strictly as a lightweight, zero-overhead replacement for CNATS *only* for pure local, single-machine installations.
26+
27+
### Tier 3: Bare-Metal Nests (The 59ns Compute Engine)
28+
- **Identity:** Unforgiving speed. High-speed statistics, order book building.
29+
- **Environment:** Bare-metal Linux, likely exchange colocation. Strictly conditioned Habitats (isolated cores, NUMA tuning).
30+
- **Tech Stack:** Pure, hyper-optimized C++.
31+
- **Networking Protocol:** Strictly CNATS (`libnats-c`) for telemetry and signaling. Uses standard Linux kernel networking (`epoll`, `io_uring`) for market data/execution. It does not cross the threshold into the physical NIC hardware.
32+
- **RESTRICTION:** You are EXPLICITLY FORBIDDEN from attempting to install Python/Anaconda on Tier 3 Habitats.
33+
34+
### Tier 4: The Fiber Nests (The Kinetic Edge)
35+
- **Identity:** Pure hardware warfare. Full HFT.
36+
- **Environment:** Exchange colocation only. Bare-metal Linux.
37+
- **Tech Stack:** Pure C++.
38+
- **Networking Protocol:** CNATS for telemetry. For execution, it completely abandons the Linux OS networking stack. It uses Solarflare network cards and requires kernel bypass technologies specifically `ef_vi` (raw DMA) or `onload`.
39+
- **RESTRICTION:** You are EXPLICITLY FORBIDDEN from attempting to install Python/Anaconda on Tier 4 Habitats.
40+
41+
### Tier 5: The Global Swarm (Future Horizon)
42+
- **Identity:** Interconnected arbitrage across global data centers.
43+
- **Networking Protocol:** Microwave or millimeter-wave networks.

‎docs/architecture/ecosystem_topology.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# QuanuX Ecosystem Topology
2+
3+
This architectural manifesto details the absolute domain topology of the QuanuX ecosystem, formalizing the concepts of Habitats, Nests, and the 5 Tier System.
4+
5+
## Foundational Nomenclature
6+
* **Habitat**: The physical or virtual OS boundary (e.g., your local desktop, an Ubuntu VM, a bare-metal server). It is the conditioned soil upon which logic executes.
7+
* **Nest**: The sovereign logic process deployed into the Habitat (e.g., trading engines, AI models, observation layers). The term "Payload" is deprecated. A Habitat can host one massive Nest or countless microscopic Nests.
8+
9+
## The QuanuX Tier System (The Topological Law)
10+
11+
The ecosystem is stratified into 5 distinct Tiers based on latency, control, and physical environment. The technology stack changes drastically at each Tier to match the physical realities of the environment.
12+
13+
### Tier 1: The Server (Command Center)
14+
* **Identity**: The orchestrator and heart of the system.
15+
* **Environment**: Remote cloud server, local workstation, or desktop.
16+
* **Tech Stack**: Hosts web servers, APIs, strategy repositories, broker APIs. Runs the `quanuxctl` CLI (Python). Communicates to the cluster via Python NATS clients (`nats-py`).
17+
* **Rule**: It does not execute kinetic trades. It deploys Nests to Habitats.
18+
19+
### Tier 2: The Polyglot Nests (Flexibility & Intelligence)
20+
* **Identity**: AI strategy labs, observation layers, and standard API execution (TopstepX, IBKR TWS).
21+
* **Environment**: Extremely flexible. Can be deployed remotely or run locally on the Tier 1 desktop without strict OS conditioning.
22+
* **Tech Stack**: C++, Python, Cython, Golang. Heavily integrated with Anaconda.
23+
* **Networking Protocol**: Uses CNATS (`libnats-c`) if compiled in C++ for cluster communication. Uses ZMQ (ZeroMQ) strictly as a lightweight, zero-overhead replacement for CNATS *only* for pure local, single-machine installations.
24+
25+
### Tier 3: Bare-Metal Nests (The 59ns Compute Engine)
26+
* **Identity**: Unforgiving speed. High-speed statistics, order book building.
27+
* **Environment**: Bare-metal Linux, likely exchange colocation. Strictly conditioned Habitats (isolated cores, NUMA tuning).
28+
* **Tech Stack**: Pure, hyper-optimized C++. **Python/Anaconda are strictly forbidden in this Tier.**
29+
* **Networking Protocol**: Strictly CNATS (`libnats-c`) for telemetry and signaling. Uses standard Linux kernel networking (`epoll`, `io_uring`) for market data/execution. It does not cross the threshold into the physical NIC hardware.
30+
31+
### Tier 4: The Fiber Nests (The Kinetic Edge)
32+
* **Identity**: Pure hardware warfare. Full HFT.
33+
* **Environment**: Exchange colocation only. Bare-metal Linux.
34+
* **Tech Stack**: Pure C++. **Python/Anaconda are strictly forbidden in this Tier.**
35+
* **Networking Protocol**: CNATS for telemetry. For execution, it completely abandons the Linux OS networking stack. It uses Solarflare network cards and requires kernel bypass technologies specifically `ef_vi` (raw DMA) or `onload`.
36+
37+
### Tier 5: The Global Swarm (Future Horizon)
38+
* **Identity**: Interconnected arbitrage across global data centers.
39+
* **Networking Protocol**: Microwave or millimeter-wave networks.

‎docs/man/man7/quanux-topology.7‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
.TH QUANUX-TOPOLOGY 7 "February 2026" "QuanuX 0.1.0" "QuanuX Architecture Manual"
2+
.SH NAME
3+
quanux\-topology \- Absolute domain topology of the QuanuX ecosystem
4+
.SH DESCRIPTION
5+
The QuanuX ecosystem topology defines the fundamental relationship between code execution environments and operational latency. It establishes the concepts of Habitats and Nests, and partitions operations across five distinct Tiers.
6+
.SH NOMENCLATURE
7+
.TP
8+
.B Habitat
9+
The physical or virtual OS boundary (e.g., local desktop, Ubuntu VM, bare-metal server). It is the conditioned soil for execution.
10+
.TP
11+
.B Nest
12+
The sovereign logic process deployed into the Habitat (e.g., trading engines, AI models, observation layers). "Payload" is deprecated. A Habitat can host one massive Nest or countless microscopic Nests.
13+
.SH THE TIER SYSTEM
14+
The QuanuX architecture enforces a strict 5-Tier layout to separate orchestration from high-frequency kinetic execution.
15+
.SS Tier 1: The Server (Command Center)
16+
.B Identity:
17+
The orchestrator and heart of the system. Does not execute kinetic trades (deploys Nests to Habitats).
18+
.br
19+
.B Environment:
20+
Remote cloud server, local workstation, or desktop.
21+
.br
22+
.B Stack:
23+
Web servers, APIs, Python (quanuxctl, nats-py).
24+
.SS Tier 2: The Polyglot Nests (Flexibility & Intelligence)
25+
.B Identity:
26+
AI strategy labs, observation layers, and standard API execution.
27+
.br
28+
.B Environment:
29+
Extremely flexible (remote or local).
30+
.br
31+
.B Stack:
32+
C++, Python, Cython, Golang (Anaconda integrated).
33+
.br
34+
.B Network:
35+
CNATS (libnats-c) for cluster communication, or ZMQ for purely local, single-machine installations.
36+
.SS Tier 3: Bare-Metal Nests (The 59ns Compute Engine)
37+
.B Identity:
38+
Unforgiving speed (statistics, order book building).
39+
.br
40+
.B Environment:
41+
Bare-metal Linux (strictly conditioned Habitats via isolated cores, NUMA).
42+
.br
43+
.B Stack:
44+
Pure C++ (Python strictly forbidden).
45+
.br
46+
.B Network:
47+
CNATS for telemetry/signaling. Standard Linux networking (epoll, io_uring) for execution.
48+
.SS Tier 4: The Fiber Nests (The Kinetic Edge)
49+
.B Identity:
50+
Pure hardware warfare (Full HFT).
51+
.br
52+
.B Environment:
53+
Exchange colocation only (Bare-metal Linux).
54+
.br
55+
.B Stack:
56+
Pure C++ (Python strictly forbidden).
57+
.br
58+
.B Network:
59+
CNATS for telemetry. Solarflare kernel bypass (ef_vi, onload) for physical execution, completely abandoning standard Linux networking.
60+
.SS Tier 5: The Global Swarm (Future Horizon)
61+
.B Identity:
62+
Interconnected arbitrage across global data centers.
63+
.br
64+
.B Network:
65+
Microwave or millimeter-wave networks.
66+
.SH SEE ALSO
67+
.BR quanuxctl (1),
68+
.BR quanux-envoy (8)

0 commit comments

Comments
 (0)