Skip to content

Commit 7fccdfa

Browse files
NikolaRHristovNikolaRHristov
committed
docs(Mountain): Overhaul README with architectural deep dive and ecosystem context
Completely restructure Mountain's README to align with Land's final synthesized architecture documentation standards. The new documentation: - Clearly positions Mountain as the Rust/Tauri backend implementing Common traits - Details core architectural principles like declarative ActionEffect system and gRPC/Vine integration - Adds visual Mermaid diagram showing Mountain's role in orchestrating Wind UI and Cocoon sidecar - Explains key components like Track dispatcher, AppState management, and native service handlers - Maintains funding acknowledgements while elevating technical content This brings Mountain's documentation up to parity with the implemented architecture described in Common, providing crucial context for contributors working on the native backend services.
1 parent 761e5e9 commit 7fccdfa

1 file changed

Lines changed: 194 additions & 6 deletions

File tree

‎README.md‎

Lines changed: 194 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,199 @@
1-
## Funding
1+
<table><tr>
2+
<td colspan="1"> <h3 align="center"> <picture>
3+
<source media="(prefers-color-scheme: dark)" srcset="https://PlayForm.Cloud/Dark/Image/GitHub/Land.svg">
4+
<source media="(prefers-color-scheme: light)" srcset="https://PlayForm.Cloud/Image/GitHub/Land.svg">
5+
<img width="28" alt="Land Logo" src="https://PlayForm.Cloud/Image/GitHub/Land.svg">
6+
</picture> </h3> </td> <td colspan="3" valign="top"> <h3 align="center"> Mountain ⛰️
7+
</h3> </td>
8+
</tr></table>
29

3-
This project is funded through
4-
[NGI0 Commons Fund](https://nlnet.nl/commonsfund), a fund established by
10+
# **Mountain** ⛰️ The Bedrock of Land: Native Backend & Service Host
11+
12+
[![License: CC0-1.0](https://img.shields.io/badge/License-CC0_1.0-lightgrey.svg)](https://github.com/CodeEditorLand/Mountain/blob/Current/LICENSE)
13+
[![Rust Version](https://img.shields.io/badge/Rust-1.77+-blue.svg)](https://www.rust-lang.org/)
14+
[![Tauri Version](https://img.shields.io/badge/Tauri-v2-blue.svg)](https://tauri.app/)
15+
[![Tonic gRPC Version](https://img.shields.io/badge/Tonic-v0.11-blueviolet.svg)](https://github.com/hyperium/tonic)
16+
17+
Welcome to **Mountain**! This element is the native Rust backend and Tauri
18+
application shell for the Land Code Editor. It serves as the foundational
19+
bedrock for the entire system, managing the application lifecycle, orchestrating
20+
native OS operations, and providing high-performance services to the `Wind`
21+
frontend and the `Cocoon` extension host.
22+
23+
**Mountain** is engineered to:
24+
25+
1. **Be the Native Core:** Act as the primary Rust application, leveraging
26+
Tauri to create a lightweight, cross-platform windowing and webview host.
27+
2. **Provide High-Performance Services:** Implement the abstract service traits
28+
defined in the `Common` crate, offering native-speed implementations for
29+
filesystem I/O, process management, secure storage, and more.
30+
3. **Orchestrate Sidecars:** Reliably launch, manage, and communicate with the
31+
`Cocoon` (Node.js) extension host sidecar via a robust gRPC interface.
32+
4. **Power the UI:** Serve as the backend for the `Wind` UI layer, responding
33+
to requests via Tauri commands and pushing state updates via Tauri events.
34+
35+
## Key Features 🔐
36+
37+
- **Declarative Effect System:** Built on a custom Rust `ActionEffect` system
38+
defined in the `Common` crate. All business logic is described as declarative,
39+
composable effects, which are executed by a central `AppRuntime`.
40+
- **gRPC-Powered IPC:** Hosts a `tonic`-based gRPC server (`Vine`) to provide a
41+
strongly-typed, high-performance communication channel for the `Cocoon`
42+
extension host.
43+
- **Centralized State Management:** Utilizes a thread-safe, Tauri-managed
44+
`AppState` to act as the single source of truth for the entire application's
45+
state, from open documents to provider registrations.
46+
- **Native PTY Management:** Implements a full-featured integrated terminal
47+
service by spawning and managing native pseudo-terminals (`PTY`) using the
48+
`portable-pty` crate.
49+
- **Secure Storage Integration:** Leverages the native OS keychain via the
50+
`keyring` crate to securely store sensitive data like authentication tokens.
51+
- **Robust Command Dispatching:** A central `Track` dispatcher intelligently
52+
routes all incoming requests from the UI (`Wind`) and extensions (`Cocoon`) to
53+
the appropriate native handlers or effects.
54+
55+
## Core Architecture Principles 🏗️
56+
57+
| Principle | Description | Key Components Involved |
58+
| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------- |
59+
| **Implementation of Contracts** | Faithfully implement the abstract service `trait`s defined in the `Common` crate, providing the concrete logic for the application's architecture. | `environment/*` providers |
60+
| **Separation of Concerns** | Isolate business logic in `handlers` modules, keeping the `environment` provider implementations clean and focused on delegation. | `environment/*`, `handlers/*` |
61+
| **Declarative Logic** | Express all operations as `ActionEffect`s, which are executed by the `AppRuntime`. This makes logic composable, testable, and robust. | `runtime/*`, `track/*`, `Common::effect` |
62+
| **Centralized State** | Maintain a single, thread-safe `AppState` struct managed by Tauri to ensure data consistency across the entire application. | `app_state/*` |
63+
| **Secure & Performant IPC** | Utilize gRPC for all communication with the `Cocoon` sidecar, ensuring a well-defined and high-performance API boundary. | `vine/*` |
64+
| **UI-Backend Decoupling** | Interact with the `Wind` frontend exclusively through asynchronous Tauri commands and events, ensuring the backend is UI-agnostic. | `main.rs` (invoke handler), `handlers/*` (emitters) |
65+
66+
---
67+
68+
## Deep Dive & Component Breakdown 🔬
69+
70+
To understand how `Mountain`'s internal components are structured and how they
71+
implement the application's core logic, please refer to the detailed technical
72+
breakdown in [`docs/Deep Dive.md`](docs/Deep%20Dive.md). This document explains
73+
the roles of the `AppRuntime`, `AppState`, `handlers`, `environment`, and the
74+
`Vine` gRPC layer.
75+
76+
---
77+
78+
## `Mountain` in the Land Ecosystem ⛰️ + 🏞️
79+
80+
This diagram illustrates `Mountain`'s central role as the native orchestrator
81+
for the entire Land application.
82+
83+
```mermaid
84+
graph LR
85+
classDef mountain fill:#f9f,stroke:#333,stroke-width:2px;
86+
classDef cocoon fill:#ccf,stroke:#333,stroke-width:2px;
87+
classDef wind fill:#9cf,stroke:#333,stroke-width:2px;
88+
classDef common fill:#cfc,stroke:#333,stroke-width:1px;
89+
classDef ipc fill:#ff9,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
90+
91+
subgraph "Mountain (Native Rust/Tauri Backend)"
92+
TauriRuntime[Tauri App & Window]:::mountain
93+
AppRuntime[AppRuntime Engine]:::mountain
94+
AppState["AppState (Shared State)"]:::mountain
95+
TrackDispatcher[Track Dispatcher]:::mountain
96+
VineGRPC[Vine gRPC Server]:::ipc
97+
NativeHandlers[Native Logic Handlers]:::mountain
98+
CommonCrate["Common Crate (Traits & DTOs)"]:::common
99+
100+
TauriRuntime -- Manages --> AppState
101+
TauriRuntime -- Manages --> AppRuntime
102+
AppRuntime -- Executes effects via --> NativeHandlers
103+
TrackDispatcher -- Routes requests to --> AppRuntime
104+
end
105+
106+
subgraph "Clients"
107+
WindUI["Wind/Sky UI (Webview)"]:::wind
108+
CocoonSidecar["Cocoon Extension Host (Node.js)"]:::cocoon
109+
end
110+
111+
TauriRuntime -- Hosts --> WindUI
112+
WindUI -- Tauri Commands --> TrackDispatcher
113+
TrackDispatcher -- Tauri Events --> WindUI
114+
115+
VineGRPC -- gRPC Protocol <--> CocoonSidecar; class VineGRPC,CocoonSidecar ipc
116+
VineGRPC -- Forwards requests to --> TrackDispatcher
117+
118+
NativeHandlers -- Implements traits from --> CommonCrate
119+
```
120+
121+
---
122+
123+
## Project Structure Overview 🗺️
124+
125+
The `Mountain` repository is organized to clearly separate concerns, following
126+
the architectural patterns defined in `Common`.
127+
128+
```
129+
Mountain/
130+
├── src/
131+
│ ├── main.rs # Tauri application entry point and setup.
132+
│ ├── app_state/ # The central, thread-safe state store for the application.
133+
│ ├── environment/ # Concrete implementations of the `Common` provider traits.
134+
│ ├── handlers/ # The detailed business logic for each service domain.
135+
│ ├── runtime/ # The `AppRuntime` engine that executes effects.
136+
│ ├── track/ # The central request dispatcher.
137+
│ └── vine/ # The gRPC server implementation (using `tonic`).
138+
├── proto/
139+
│ └── vine.proto # The gRPC contract definition file.
140+
└── build.rs # Build script to compile the .proto file into Rust code.
141+
```
142+
143+
---
144+
145+
## Development Setup
146+
147+
`Mountain` is a Rust crate and a core component of the main `Land` repository.
148+
It is not intended to be built or run standalone. Please follow the instructions
149+
in the main [Land Repository README](https://github.com/CodeEditorLand/Land) to
150+
set up, build, and run the entire application.
151+
152+
**Key Dependencies:**
153+
154+
- `tauri`: `^2.x`
155+
- `tokio`: For the asynchronous runtime.
156+
- `tonic`: For the gRPC server implementation.
157+
- `serde` & `serde_json`: For serialization.
158+
- `log` & `env_logger`: For logging.
159+
- `portable-pty`: For the integrated terminal feature.
160+
- `keyring`: For secure secret storage.
161+
- `Common` (local path dependency).
162+
163+
---
164+
165+
## License ⚖️
166+
167+
This project is released into the public domain under the **Creative Commons CC0
168+
Universal** license. You are free to use, modify, distribute, and build upon
169+
this work for any purpose, without any restrictions. For the full legal text,
170+
see the [`LICENSE`](LICENSE) file.
171+
172+
---
173+
174+
## Changelog 📜
175+
176+
Stay updated with our progress! See [`CHANGELOG.md`](CHANGELOG.md) for a history
177+
of changes specific to **Mountain**.
178+
179+
---
180+
181+
## Funding & Acknowledgements 🙏
182+
183+
**Mountain** is a core element of the **Land** ecosystem. This project is funded
184+
through [NGI0 Commons Fund](https://nlnet.nl/commonsfund), a fund established by
5185
[NLnet](https://nlnet.nl) with financial support from the European Commission's
6186
[Next Generation Internet](https://ngi.eu) program. Learn more at the
7187
[NLnet project page](https://nlnet.nl/project/Land).
8188

9-
| Land | PlayForm | NLnet | NGI0 Commons Fund |
10-
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
11-
| [<img src="https://raw.githubusercontent.com/CodeEditorLand/Asset/refs/heads/Current/Logo/Land.svg" height="80px" alt="Land" />](https://editor.land) | [<img src="https://raw.githubusercontent.com/PlayForm/Asset/refs/heads/Current/Logo/PlayForm.svg" height="80px" alt="PlayForm" />](https://playform.cloud) | [<img width="240px" src="https://nlnet.nl/logo/banner.svg" alt="NLnet" />](https://nlnet.nl) | [<img width="240px" src="https://nlnet.nl/image/logos/NGI0CommonsFund_tag_black_mono.svg" alt="NGI0 Commons Fund" />](https://nlnet.nl/commonsfund) |
189+
| **Land** | PlayForm | NLnet | NGI0 Commons Fund |
190+
| :-------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
191+
| [<img src="https://raw.githubusercontent.com/CodeEditorLand/Asset/refs/heads/Current/Logo/Land.svg" height="80px" alt="Land">](https://editor.land) | [<img src="https://raw.githubusercontent.com/PlayForm/Asset/refs/heads/Current/Logo/PlayForm.svg" height="80px" alt="PlayForm">](https://playform.cloud) | [<img width="240px" src="https://nlnet.nl/logo/banner.svg" alt="NLnet">](https://nlnet.nl) | [<img width="240px" src="https://nlnet.nl/image/logos/NGI0CommonsFund_tag_black_mono.svg" alt="NGI0 Commons Fund">](https://nlnet.nl/commonsfund) |
192+
193+
---
194+
195+
**Project Maintainers**: Source Open
196+
([Source/Open@Editor.Land](mailto:Source/Open@Editor.Land)) |
197+
[GitHub Repository](https://github.com/CodeEditorLand/Mountain) |
198+
[Report an Issue](https://github.com/CodeEditorLand/Mountain/issues) |
199+
[Security Policy](https://github.com/CodeEditorLand/Mountain/security/policy)

0 commit comments

Comments
 (0)