From fb86491beed76e015ee22018ee0dc8499af9cf76 Mon Sep 17 00:00:00 2001 From: Andrey Sobolev Date: Tue, 9 Sep 2025 11:35:55 +0700 Subject: [PATCH] Huly Network Signed-off-by: Andrey Sobolev --- README.md | 18 ++++++++++- network/README.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 93 insertions(+), 1 deletion(-) create mode 100644 network/README.md diff --git a/README.md b/README.md index 4dd9d922179..337e3778b7a 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,17 @@ If you want to interact with Huly programmatically, check out our [API Client](. You can find API usage examples in the [Huly examples](https://github.com/hcengineering/huly-examples) repository. +## Huly Virtual Network + +The platform features a distributed network architecture that enables scalable, fault-tolerant communication between accounts, workspaces, and nodes. The [Huly Network](http://github.com/hcengineering/huly.net) provides: + +- **Distributed Load Balancing**: Intelligent routing across multiple nodes +- **Multi-Tenant Architecture**: Secure workspace isolation +- **Fault Tolerance**: Automatic failover and recovery mechanisms +- **Real-time Communication**: Event-driven architecture with broadcast capabilities + +For detailed information about the network architecture, deployment, and API reference, see the [Network Documentation](http://github.com/hcengineering/huly.net). + ## Table of Contents - [Huly Platform](#huly-platform) @@ -35,6 +46,7 @@ You can find API usage examples in the [Huly examples](https://github.com/hcengi - [Self-Hosting](#self-hosting) - [Activity](#activity) - [API Client](#api-client) + - [Huly Virtual Network](#huly-virtual-network) - [Table of Contents](#table-of-contents) - [Pre-requisites](#pre-requisites) - [Verification](#verification) @@ -106,6 +118,7 @@ This project uses GitHub Packages for dependency management. To successfully dow Follow these steps: 1. Generate a GitHub Token: + - Log in to your GitHub account - Go to **Settings** > **Developer settings** > **Personal access tokens** (https://github.com/settings/personal-access-tokens) - Click **Generate new token** @@ -113,13 +126,13 @@ Follow these steps: - Generate the token and copy it 2. Authenticate with npm: + ```bash npm login --registry=https://npm.pkg.github.com ``` When prompted, enter your GitHub username, use the generated token as your password - ## Fast start ```bash @@ -280,6 +293,7 @@ This guide describes the nuances of building and running the application from so #### Disk Space Requirements Ensure you have sufficient disk space available: + - A fully deployed local application in clean Docker will consume slightly more than **35 GB** of WSL virtual disk space - The application folder after build (sources + artifacts) will occupy **4.5 GB** @@ -303,6 +317,7 @@ Make sure Docker is accessible from WSL: Windows Git often automatically replaces line endings. Since most build scripts are `.sh` files, ensure your Windows checkout doesn't break them. **Solution options:** + - Checkout from WSL instead of Windows - Configure Git on Windows to disable auto-replacement: ```bash @@ -343,6 +358,7 @@ After these preparations, the build instructions should work without issues. When starting the application (`rush docker:up`), some network ports in Windows might be occupied. You can fix port mapping in the `\dev\docker-compose.yaml` file. **Important:** Depending on which port you change, you'll need to: + 1. Find what's using that port 2. Update the new address in the corresponding service configuration diff --git a/network/README.md b/network/README.md new file mode 100644 index 00000000000..3c7697e3452 --- /dev/null +++ b/network/README.md @@ -0,0 +1,76 @@ +# Huly Virtual Network + +A distributed, scalable virtual network architecture for the Huly that enables fault-tolerant performance communication. [Huly Network](http://github.com/hcengineering/huly.net) + +## Building Huly on top of Huly Network + +Huly could be managed by following set of container kinds, `session`, `query`, `transactor`. + +- session -> a map/reduce/find executor for queries and transactions from client. +- query -> a DB query engine, execute `find` requests from session and pass them to DB, allow to search for all data per region. Should have access to tables of account -> workspace mapping for security. +- transactor -> modification archestrator for all edit operations, do them one by one. + +```mermaid +flowchart + Endpoint -.->| + connect + session/user1 + |HulyNetwork[Huly Network] + + Endpoint <-->|find,tx| parsonal-ws:user1 + + parsonal-ws:user1 -..->|get-workspace info| DatalakeDB + + parsonal-ws:user1 -..->|find| query:europe + + parsonal-ws:user1 -..->|event's| Endpoint + + query:europe -..->|resp| parsonal-ws:user1 + + parsonal-ws:user1 -..->|response chunks| Endpoint + + parsonal-ws:user1 -..->|tx| transactor:ws1 + + transactor:ws1 -..->|event's| HulyPulse + transactor:ws1 -..->|event's| parsonal-ws:user1 + + HulyPulse <--> Client + + Client <--> Endpoint + + query:europe -..->|"update"| QueryDB + transactor:ws1 -..->|update| DatalakeDB + + transactor:ws1 -..->|txes| Kafka[Output Queue] + + Kafka -..-> Indexer[Structure + + Fulltext Index] + + Indexer -..-> QueryDB + + Indexer -..->|indexed tx| HulyPulse + + Indexer -..->|indexed tx| parsonal-ws:user1 + + Kafka -..-> AsyncTriggers + + AsyncTriggers -..->|find| query:europe + + AsyncTriggers -..->|derived txes| transactor:ws1 + + InputQueue -->|txes| transactor:ws1 + + Services[Services + Github/Telegram/Translate] -..-> InputQueue + + Kafka -..-> Services + + Services -..-> query:europe + + QueryDB@{shape: database} + InputQueue@{shape: database} + DatalakeDB@{shape: database} + Kafka@{shape: database} + parsonal-ws:user1@{ shape: h-cyl} + +```