# Technical Overview

This document provides a high-level overview of the architecture, core technologies, and guiding principles for developers looking to build on or contribute to the Dao OS ecosystem.

## Guiding Technical Principles

Our engineering decisions are guided by a set of core principles to ensure the system is robust, portable, and open.

* **Web-Native & Portable**: We leverage technologies born from the web (like WebAssembly) to create a single, portable core that can run anywhere—on desktops, mobile phones, servers, and in the browser.
* **Polyglotism via WASM**: The core logic (`Meta Unit`) is compiled to WebAssembly (WASM). This allows "Avatars" to be written in any language (Rust, Swift, Kotlin, TypeScript, Go, etc.) that can host a WASM runtime, creating a truly diverse ecosystem.
* **API-First**: The interaction between the core `Meta Unit` and the host `Avatar` is defined by a strict, versioned API contract. This decouples development and allows for independent evolution.
* **Security-First**: We employ best-in-class cryptographic protocols and a "principle of least privilege" design. Security is not an afterthought; it is a prerequisite.
* **FOSS (Free and Open Source Software)**: The entire core protocol and reference implementations are open source to foster transparency, community trust, and collaborative innovation.

## The Core Components: A Developer's View

From a developer's perspective, the system consists of two main parts that interact via a well-defined boundary.

1. **The `Meta Unit` (WASM Module)**: This is the portable, logical core of the system. It is a stateful, single-instance module developed primarily in **Rust** for its performance and safety guarantees. It contains all the business logic for data management, AI, and peer-to-peer coordination, but it has no direct access to the outside world.

2. **The `Avatar` (Native Host)**: This is the native application or runtime environment that "hosts" the Meta Unit. Its primary responsibilities are:
    * Providing a **WASM runtime** to load and execute the `Meta Unit`.
    * Providing a **User Interface** (for Client Avatars).
    * Acting as a **bridge** to the host operating system, providing access to the filesystem, network, and other system resources.

## The API Contract: The WASM Interface

The communication between the `Avatar` and the `Meta Unit` follows a clear, bidirectional API contract, similar in spirit to WASI (WebAssembly System Interface).

* **`yuan_*` (Exports from Meta Unit)**: The `Meta Unit` exposes a set of functions that the `Avatar` can call. The primary entry point is `yuan_handle_request`, which takes a structured request from the Avatar and processes it.

* **`avatar_*` (Imports into Meta Unit)**: The `Meta Unit` declares a set of functions that it needs the `Avatar` host to provide. These functions are its only window to the outside world, allowing it to request actions like logging a message (`avatar_log`) or making a network request (`avatar_net_request`).

* **Data Serialization**: To pass complex data structures across the WASM memory boundary efficiently and safely, we use **Protocol Buffers (Protobuf)**. Data is serialized into a byte buffer, passed as a pointer and length, and then deserialized on the other side.

## Key Technologies & Protocols

| Category              | Technology / Protocol                                     | Purpose                                                      |
| --------------------- | --------------------------------------------------------- | ------------------------------------------------------------ |
| **Core Logic** | Rust / WebAssembly (WASM)                                 | Performance, safety, and ultimate portability.               |
| **P2P Networking** | `libp2p`                                                  | Modular peer discovery (DHT), transport, and secure channels.  |
| **Data Synchronization** | CRDTs (Conflict-Free Replicated Data Types)               | Ensuring eventual consistency across Avatars without a central server. |
| **Identity** | DID & VC (Decentralized Identifiers & Verifiable Credentials) | Sovereign identity and interoperable, cryptographic trust.     |
| **Data Serialization** | Protocol Buffers (Protobuf)                               | Efficient, language-agnostic data structures for APIs.       |

This modular, open-protocol-based stack is designed for security, portability, and, most importantly, community contribution.