5dca8ecc79
- Introduced a new "Getting Started" guide to help users set up and use the YAZE software effectively. - Added detailed "Testing Guide" outlining the testing framework and best practices for contributors. - Created "Build Instructions" for macOS, Linux, and Windows, including environment verification and quick start with CMake presets. - Documented the architecture and networking aspects of YAZE, focusing on service-oriented design and gRPC integration. - Updated the index to reflect new documentation structure and improve navigation.
124 lines
8.8 KiB
Markdown
124 lines
8.8 KiB
Markdown
# B5 - Architecture and Networking
|
||
|
||
This document provides a comprehensive overview of the yaze application's architecture, focusing on its service-oriented design, gRPC integration, and real-time collaboration features.
|
||
|
||
## 1. High-Level Architecture
|
||
|
||
The yaze ecosystem is split into two main components: the **YAZE GUI Application** and the **`z3ed` CLI Tool**.
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────────┐
|
||
│ YAZE GUI Application │
|
||
│ (Runs on local machine) │
|
||
├─────────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||
│ │ UnifiedGRPCServer (Port 50051) │ │
|
||
│ │ ════════════════════════════════════════════════════════ │ │
|
||
│ │ Hosts 3 gRPC Services on a SINGLE PORT: │ │
|
||
│ │ │ │
|
||
│ │ 1️⃣ ImGuiTestHarness Service │ │
|
||
│ │ • GUI automation (click, type, wait, assert) │ │
|
||
│ │ │ │
|
||
│ │ 2️⃣ RomService │ │
|
||
│ │ • Read/write ROM bytes │ │
|
||
│ │ • Proposal system for collaborative editing │ │
|
||
│ │ │ │
|
||
│ │ 3️⃣ CanvasAutomation Service │ │
|
||
│ │ • High-level canvas operations (tile ops, selection) │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
│ ↑ │
|
||
│ │ gRPC Connection │
|
||
└────────────────────────────────────┼──────────────────────────────────────┘
|
||
│
|
||
↓
|
||
┌────────────────────────────────────┼──────────────────────────────────────┐
|
||
│ z3ed CLI Tool │
|
||
│ (Command-line interface) │
|
||
├─────────────────────────────────────────────────────────────────────────┤
|
||
│ ┌──────────────────────────────────────────────────────────────┐ │
|
||
│ │ CLI Services (Business Logic - NOT gRPC servers) │ │
|
||
│ │ ══════════════════════════════════════════════════ │ │
|
||
│ │ - AI Services (Gemini, Ollama) │ │
|
||
│ │ - Agent Services (Chat, Tool Dispatcher) │ │
|
||
│ │ - Network Clients (gRPC and WebSocket clients) │ │
|
||
│ └──────────────────────────────────────────────────────────────┘ │
|
||
└───────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 2. Service Taxonomy
|
||
|
||
It's important to distinguish between the two types of "services" in the yaze project.
|
||
|
||
### APP Services (gRPC Servers)
|
||
- **Location**: `src/app/core/service/`, `src/app/net/`
|
||
- **Runs In**: YAZE GUI application
|
||
- **Purpose**: Expose application functionality to remote clients (like the `z3ed` CLI).
|
||
- **Type**: gRPC **SERVER** implementations.
|
||
|
||
### CLI Services (Business Logic)
|
||
- **Location**: `src/cli/service/`
|
||
- **Runs In**: `z3ed` CLI tool
|
||
- **Purpose**: Implement the business logic for the CLI commands.
|
||
- **Type**: These are helper classes, **NOT** gRPC servers. They may include gRPC **CLIENTS** to connect to the APP Services.
|
||
|
||
## 3. gRPC Services
|
||
|
||
yaze exposes its core functionality through a `UnifiedGRPCServer` that hosts multiple services on a single port (typically 50051).
|
||
|
||
### ImGuiTestHarness Service
|
||
- **Proto**: `imgui_test_harness.proto`
|
||
- **Purpose**: GUI automation.
|
||
- **Features**: Click, type, screenshots, widget discovery.
|
||
|
||
### RomService
|
||
- **Proto**: `rom_service.proto`
|
||
- **Purpose**: Low-level ROM manipulation.
|
||
- **Features**: Read/write bytes, proposal system for collaborative editing, snapshots for version management.
|
||
|
||
### CanvasAutomation Service
|
||
- **Proto**: `canvas_automation.proto`
|
||
- **Purpose**: High-level, abstracted control over canvas-based editors.
|
||
- **Features**: Tile operations (get/set), selection management, view control (pan/zoom).
|
||
|
||
## 4. Real-Time Collaboration
|
||
|
||
Real-time collaboration is enabled through a WebSocket-based protocol managed by the `yaze-server`, a separate Node.js application.
|
||
|
||
### Architecture
|
||
```
|
||
┌─────────────┐ WebSocket ┌──────────────┐
|
||
│ yaze app │◄────────────────────────────►│ yaze-server │
|
||
│ (GUI) │ │ (Node.js) │
|
||
└─────────────┘ └──────────────┘
|
||
▲ ▲
|
||
│ gRPC │ WebSocket
|
||
└─────────────┐ │
|
||
┌──────▼──────┐ │
|
||
│ z3ed CLI │◄──────────────────────┘
|
||
└─────────────┘
|
||
```
|
||
|
||
### Core Components
|
||
- **ROM Version Manager**: Protects the ROM from corruption with snapshots and safe points.
|
||
- **Proposal Approval Manager**: Manages a collaborative voting system for applying changes.
|
||
- **Collaboration Panel**: A UI within the YAZE editor for managing collaboration.
|
||
|
||
### WebSocket Protocol
|
||
The WebSocket protocol handles real-time messaging for:
|
||
- Hosting and joining sessions.
|
||
- Broadcasting ROM diffs (`rom_sync`).
|
||
- Sharing and voting on proposals (`proposal_share`, `proposal_vote`).
|
||
- Sharing snapshots.
|
||
|
||
## 5. Data Flow Example: AI Agent Edits a Tile
|
||
|
||
1. **User** runs `z3ed agent --prompt "Paint grass at 10,10"`.
|
||
2. The **GeminiAIService** (a CLI Service) parses the prompt and returns a tool call to `overworld-set-tile`.
|
||
3. The **ToolDispatcher** (a CLI Service) routes this to the appropriate handler.
|
||
4. The **Tile16ProposalGenerator** (a CLI Service) creates a proposal.
|
||
5. The **GuiAutomationClient** (a CLI Service acting as a gRPC client) calls the `CanvasAutomation.SetTile()` RPC method on the YAZE application's `UnifiedGRPCServer`.
|
||
6. The **CanvasAutomationService** in the YAZE app receives the request and uses the `CanvasAutomationAPI` to paint the tile.
|
||
7. If collaboration is active, the change is submitted through the **ProposalApprovalManager**, which communicates with the `yaze-server` via WebSocket to manage voting.
|
||
8. Once approved, the change is applied to the ROM and synced with all collaborators.
|