Skip to content

Commit 1ec8ced

Browse files
NikolaRHristovNikolaRHristov
committed
docs(Mountain): restructure and expand README with comprehensive documentation
Overhaul the Mountain README with improved structure, clearer explanations, and additional sections: - Add new header with tagline "The Bedrock of Land" - Expand Key Features section with detailed descriptions of all major capabilities - Transform Architecture table into comprehensive Core Architecture Principles section with full descriptions - Add Deep Dive & Component Breakdown section with link to technical documentation - Improve Mermaid diagram with proper classDef syntax and clearer component labels - Expand Project Structure with detailed descriptions for each module - Add explicit Development Setup instructions and Key Dependencies list - Reorganize License section and add Changelog reference - Update documentation URLs to proper Editor.Land domain This restructuring provides better onboarding for contributors and clarifies Mountain's role as the native Rust backend orchestrating Wind UI and Cocoon extension host.
1 parent 2022de4 commit 1ec8ced

1 file changed

Lines changed: 146 additions & 81 deletions

File tree

‎README.md‎

Lines changed: 146 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -55,134 +55,179 @@
5555

5656
# **Mountain** ⛰️
5757

58-
> **The RAM tax is not optional.** VS Code with a medium project: 500 MB to
59-
> 1.5 GB of RAM. Three open windows means three Chromium renderer processes,
60-
> each carrying a full heap. Every OS interaction crosses a serialized JSON IPC
61-
> pipe.
58+
The Bedrock of Land: Native Backend & Service Host
59+
60+
> **The RAM tax is not optional.** VS Code with a medium project: 500 MB to 1.5
61+
> GB of RAM. Three open windows means three Chromium renderer processes, each
62+
> carrying a full heap. Every OS interaction crosses a serialized JSON IPC pipe.
6263
6364
_"Where Electron takes 200 ms to open a dialog, Mountain takes 2."_
6465

6566
[![License: CC0-1.0](https://img.shields.io/badge/License-CC0_1.0-lightgrey.svg)](https://github.com/CodeEditorLand/Mountain/tree/Current/LICENSE)
6667
[<img src="https://editor.land/Image/Rust.svg" width="14" alt="Rust" />](https://www.rust-lang.org/)&#x2001;[![Rust Version](https://img.shields.io/badge/Rust-1.77+-blue.svg)](https://www.rust-lang.org/)
6768
[<img src="https://editor.land/Image/Tauri.svg" width="14" alt="Tauri" />](https://tauri.app/)&#x2001;[![Tauri Version](https://img.shields.io/badge/Tauri-v2-blue.svg)](https://tauri.app/)
68-
[<img src="https://editor.land/Image/gRPC.svg" width="14" alt="gRPC" />](https://grpc.io/)&#x2001;[![Tonic gRPC Version](https://img.shields.io/badge/Tonic-v0.11-blueviolet.svg)](https://github.com/hyperium/tonic)
69+
[![Tonic gRPC Version](https://img.shields.io/badge/Tonic-v0.11-blueviolet.svg)](https://github.com/hyperium/tonic)
70+
71+
📖
72+
**[Rust API Documentation](https://Rust.Documentation.Editor.Land/Mountain/)**
73+
74+
Welcome to **Mountain**! This element is the native Rust backend and Tauri
75+
application shell for the Land Code Editor. It serves as the foundational
76+
bedrock for the entire system, managing the application lifecycle, orchestrating
77+
native OS operations, and providing high-performance services to the `Wind`
78+
frontend and the `Cocoon` extension host.
79+
80+
**Mountain** is engineered to:
81+
82+
1. **Be the Native Core:** Act as the primary Rust application, leveraging
83+
Tauri to create a lightweight, cross-platform windowing and webview host.
84+
2. **Provide High-Performance Services:** Implement the abstract service traits
85+
defined in the `Common` crate, offering native-speed implementations for
86+
filesystem I/O, process management, secure storage, and more.
87+
3. **Orchestrate Sidecars:** Reliably launch, manage, and communicate with the
88+
`Cocoon` (Node.js) extension host sidecar via a robust gRPC interface.
89+
4. **Power the User Interface:** Serve as the backend for the `Wind` User
90+
Interface layer, responding to requests via Tauri commands and pushing state
91+
updates via Tauri events.
6992

70-
Mountain replaces Electron's main process entirely with a Rust binary using
71-
Tauri. The OS's own WebView renders the UI: WKWebView on macOS, WebView2 on
72-
Windows, WebKitGTK on Linux. No bundled Chromium. No Node.js in the host
73-
process. Window management, file system access, process lifecycle, and auth
74-
tokens all happen in Rust with zero IPC overhead. Cold start in under 200 ms.
75-
RAM footprint 60-80% smaller per window.
93+
---
7694

77-
📖 **[Rust API Documentation](https://Rust.Documentation.Mountain.Editor.Land/)**
95+
## Key Features&#x2001;🔐
96+
97+
- **Declarative Effect System:** Built on a Rust `ActionEffect` system defined
98+
in the `Common` crate. Business logic is described as declarative, composable
99+
effects, which are executed by a central `ApplicationRunTime`.
100+
- **gRPC-Powered IPC:** Hosts a `tonic`-based gRPC server (`Vine`) to provide a
101+
strongly-typed, high-performance communication channel for the `Cocoon`
102+
extension host.
103+
- **Centralized State Management:** Utilizes a thread-safe, Tauri-managed
104+
`ApplicationState` to act as the single source of truth for the entire
105+
application's state, from open documents to provider registrations.
106+
- **Native PTY Management:** Implements a full-featured integrated terminal
107+
service by spawning and managing native pseudo-terminals (`PTY`) using the
108+
`portable-pty` crate.
109+
- **Secure Storage Integration:** Leverages the native OS keychain via the
110+
`keyring` crate to securely store sensitive data like authentication tokens.
111+
- **Robust Command Dispatching:** A central `Track` dispatcher intelligently
112+
routes all incoming requests from the User Interface (`Wind`) and extensions
113+
(`Cocoon`) to the appropriate native `Environment` provider or `ActionEffect`.
78114

79115
---
80116

81-
## What It Does&#x2001;🔐
82-
83-
- **No Electron overhead.** Tauri's WebView replaces three Chromium renderer
84-
processes. No 300 MB base memory footprint.
85-
- **Native file I/O.** Async Rust (tokio) handles filesystem operations. File
86-
trees load instantly even on large monorepos.
87-
- **Your VS Code extensions work.** Mountain manages the Cocoon sidecar over
88-
gRPC. Extensions run unchanged with sub-millisecond IPC.
89-
- **Secrets stay in the OS keychain.** Authentication tokens stored via
90-
`keyring`, not in plaintext config files.
91-
- **Composable business logic.** Operations expressed as declarative
92-
`ActionEffect`s. Testable, composable, no spaghetti callbacks.
93-
- **Instant command dispatch.** A central `Track` dispatcher routes every UI
94-
action to the right provider. The UI never waits.
117+
## Core Architecture Principles&#x2001;🏗️
95118

96-
---
119+
| Principle | Description | Key Components Involved |
120+
| :------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------- |
121+
| **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 |
122+
| **Separation of Concerns** | Isolate service logic into distinct `Environment` provider modules, each responsible for a specific domain (e.g., FileSystem, Documents). | `Environment/*`, `Command/*` |
123+
| **Declarative Logic** | Express complex operations as `ActionEffect`s, which are executed by the `ApplicationRunTime`. This makes logic composable, testable, and robust. | `RunTime/*`, `Track/EffectCreation.rs`, `Common` |
124+
| **Centralized State** | Maintain a single, thread-safe `ApplicationState` struct managed by Tauri to ensure data consistency across the entire application. | `ApplicationState/*` |
125+
| **Secure & Performant IPC** | Utilize gRPC for all communication with the `Cocoon` sidecar, ensuring a well-defined and high-performance API boundary. | `Vine/*` |
126+
| **User Interface-Backend Decoupling** | Interact with the `Wind` frontend exclusively through asynchronous Tauri commands and events, ensuring the backend is User Interface-agnostic. | `Binary.rs` (invoke handler), `Command/*` |
97127

98-
## Architecture&#x2001;🏗️
128+
---
99129

100-
| Principle | Description | Key Components |
101-
| :--- | :--- | :--- |
102-
| Implementation of Contracts | Implements abstract service traits from Common | `Environment/*` providers |
103-
| Separation of Concerns | Each domain isolated in its own provider module | `Environment/*`, `Command/*` |
104-
| Declarative Logic | Operations as `ActionEffect`s executed by the runtime | `RunTime/*`, `Track/EffectCreation.rs` |
105-
| Centralized State | Single thread-safe `ApplicationState` | `ApplicationState/*` |
106-
| Typed IPC | gRPC for all Cocoon communication | `Vine/*` |
107-
| UI-Backend Decoupling | Tauri commands and events, backend is UI-agnostic | `Binary.rs`, `Command/*` |
130+
## Deep Dive & Component Breakdown&#x2001;🔬
108131

109-
[Deep Dive](https://github.com/CodeEditorLand/Mountain/tree/Current/Documentation/GitHub/DeepDive.md)
132+
To understand how `Mountain`'s internal components are structured and how they
133+
implement the application's core logic, please refer to the detailed technical
134+
breakdown in
135+
[`Documentation/GitHub/DeepDive.md`](https://github.com/CodeEditorLand/Mountain/tree/Current/Documentation/GitHub/DeepDive.md).
136+
This document explains the roles of the `ApplicationRunTime`,
137+
`ApplicationState`, `Handler`, `Environment`, and the `Vine` gRPC layer.
110138

111139
---
112140

113-
## In the Ecosystem&#x2001;⛰️ + 🏞️
141+
## `Mountain` in the Land Ecosystem&#x2001;⛰️ + 🏞️
142+
143+
This diagram illustrates `Mountain`'s central role as the native orchestrator
144+
for the entire Land application.
114145

115146
```mermaid
116147
graph LR
117-
classDef Mountain fill:#f9f,stroke:#333,stroke-width:2px
118-
classDef Cocoon fill:#ccf,stroke:#333,stroke-width:2px
119-
classDef Wind fill:#9cf,stroke:#333,stroke-width:2px
120-
classDef Common fill:#cfc,stroke:#333,stroke-width:1px
121-
classDef IPC fill:#ff9,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
122-
123-
subgraph "Mountain (Rust/Tauri Backend)"
124-
TauriRuntime[Tauri App]:::Mountain
125-
ApplicationRunTime[ApplicationRunTime]:::Mountain
126-
ApplicationState[ApplicationState]:::Mountain
148+
classDef Mountain fill:#f9f,stroke:#333,stroke-width:2px;
149+
classDef Cocoon fill:#ccf,stroke:#333,stroke-width:2px;
150+
classDef Wind fill:#9cf,stroke:#333,stroke-width:2px;
151+
classDef Common fill:#cfc,stroke:#333,stroke-width:1px;
152+
classDef IPC fill:#ff9,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
153+
154+
subgraph "Mountain (Native Rust/Tauri Backend)"
155+
TauriRuntime[Tauri App & Window]:::Mountain
156+
ApplicationRunTime[ApplicationRunTime Engine]:::Mountain
157+
ApplicationState["ApplicationState (Shared State)"]:::Mountain
127158
TrackDispatcher[Track Dispatcher]:::Mountain
128159
VinegRPC[Vine gRPC Server]:::IPC
129160
EnvironmentProviders[Environment Providers]:::Mountain
161+
CommonCrate["Common Crate (Traits & DTOs)"]:::Common
162+
163+
TauriRuntime -- Manages --> ApplicationState
164+
TauriRuntime -- Manages --> ApplicationRunTime
165+
ApplicationRunTime -- Executes effects via --> EnvironmentProviders
166+
TrackDispatcher -- Routes requests to --> ApplicationRunTime
130167
end
131168
132169
subgraph "Clients"
133-
WindUI[Wind/Sky UI]:::Wind
134-
CocoonSideCar[Cocoon Extension Host]:::Cocoon
170+
WindUI["Wind/Sky User Interface (Webview)"]:::Wind
171+
CocoonSideCar["Cocoon Extension Host (Node.js)"]:::Cocoon
135172
end
136173
137-
TauriRuntime -- Manages --> ApplicationState
138-
TauriRuntime -- Manages --> ApplicationRunTime
139-
ApplicationRunTime -- Executes --> EnvironmentProviders
140-
TrackDispatcher -- Routes --> ApplicationRunTime
141174
TauriRuntime -- Hosts --> WindUI
142175
WindUI -- Tauri Command --> TrackDispatcher
143176
TrackDispatcher -- Tauri Events --> WindUI
144-
VinegRPC -- gRPC --> CocoonSideCar
145-
VinegRPC -- Forwards --> TrackDispatcher
177+
178+
VinegRPC -- gRPC Protocol <--> CocoonSideCar
179+
VinegRPC -- Forwards requests to --> TrackDispatcher
180+
181+
EnvironmentProviders -- Implements traits from --> CommonCrate
146182
```
147183

148184
---
149185

150-
## Project Structure&#x2001;🗺️
186+
## Project Structure Overview&#x2001;🗺️
187+
188+
The `Mountain` repository is organized to clearly separate concerns, following
189+
the architectural patterns defined in `Common`.
151190

152191
```
153192
Mountain/
154193
├── Source/
155-
│ ├── Binary.rs # Tauri entry point
156-
│ ├── ApplicationState/ # Thread-safe state store
157-
│ ├── Command/ # Tauri command handlers
158-
│ ├── Environment/ # Common trait implementations
159-
│ ├── ExtensionManagement/ # Extension scanning and parsing
160-
│ ├── FileSystem/ # Native TreeView provider
161-
│ ├── ProcessManagement/ # Cocoon sidecar lifecycle
162-
│ ├── RunTime/ # Effect execution engine
163-
│ ├── Track/ # Central request dispatcher
164-
│ ├── Update/ # Self-updating logic
165-
│ ├── Vine/ # gRPC server/client (tonic)
166-
│ └── Workspace/ # .code-workspace handling
194+
│ ├── Binary.rs # Tauri application entry point and setup.
195+
│ ├── ApplicationState/ # Central, thread-safe state store and its DTOs.
196+
│ ├── Command/ # Tauri command handlers for UI-specific requests.
197+
│ ├── Environment/ # Concrete implementations of the Common provider traits.
198+
│ ├── ExtensionManagement/ # Logic for scanning and parsing extensions.
199+
│ ├── FileSystem/ # Native TreeView provider for the File Explorer.
200+
│ ├── ProcessManagement/ # Logic for managing the Cocoon sidecar process.
201+
│ ├── RunTime/ # The ApplicationRunTime engine that executes effects.
202+
│ ├── Track/ # The central request dispatcher (EffectCreation).
203+
│ ├── Update/ # Application self-updating logic.
204+
│ ├── Vine/ # The gRPC server and client implementation (tonic).
205+
│ └── Workspace/ # Logic for handling .code-workspace files.
167206
├── Proto/
168-
│ └── Vine.proto # gRPC contract definition
169-
└── build.rs # Proto compilation
207+
│ └── Vine.proto # The gRPC contract definition file.
208+
└── build.rs # Build script to compile the .proto file into Rust code.
170209
```
171210

172211
---
173212

174-
## Development&#x2001;🛠️
213+
## Development Setup&#x2001;🛠️
175214

176-
Mountain is a Rust crate within the Land workspace. Follow the
177-
[Land Repository](https://github.com/CodeEditorLand/Land) instructions to
178-
build and run.
215+
`Mountain` is a Rust crate and a core component of the main `Land` repository.
216+
It is not intended to be built or run standalone. Please follow the instructions
217+
in the main [Land Repository README](https://github.com/CodeEditorLand/Land) to
218+
set up, build, and run the entire application.
179219

180-
---
181-
182-
## License&#x2001;⚖️
220+
**Key Dependencies:**
183221

184-
CC0 1.0 Universal. Public domain. No restrictions.
185-
[LICENSE](https://github.com/CodeEditorLand/Mountain/tree/Current/LICENSE)
222+
- `Common` (local path dependency)
223+
- `Echo` (local path dependency)
224+
- `keyring`: For secure secret storage
225+
- `log` & `env_logger`: For logging
226+
- `portable-pty`: For the integrated terminal feature
227+
- `serde` & `serde_json`: For serialization
228+
- `tauri`: `^2.x`
229+
- `tokio`: For the asynchronous RunTime
230+
- `tonic`: For the gRPC server implementation
186231

187232
---
188233

@@ -197,7 +242,27 @@ CC0 1.0 Universal. Public domain. No restrictions.
197242
- [Echo](https://github.com/CodeEditorLand/Echo)
198243
- [Air](https://github.com/CodeEditorLand/Air)
199244

200-
## Funding & Acknowledgements&#x2001;🙏🏻
245+
---
246+
247+
## License&#x2001;⚖️
248+
249+
This project is released into the public domain under the **Creative Commons CC0
250+
Universal** license. You are free to use, modify, distribute, and build upon
251+
this work for any purpose, without any restrictions. For the full legal text,
252+
see the [`LICENSE`](https://github.com/CodeEditorLand/Mountain/tree/Current/)
253+
file.
254+
255+
---
256+
257+
## Changelog&#x2001;📜
258+
259+
Stay updated with our progress! See
260+
[`CHANGELOG.md`](https://github.com/CodeEditorLand/Mountain/tree/Current/) for a
261+
history of changes specific to **Mountain**.
262+
263+
---
264+
265+
## Funding \& Acknowledgements&#x2001;🙏🏻
201266

202267
**Mountain** is a core element of the **Land** ecosystem. This project is funded
203268
through [NGI0 Commons Fund](https://NLnet.NL/Commonsfund), a fund established by

0 commit comments

Comments
 (0)