# aukilabs/posemesh architecture

> Architecture diagram of the GitHub repository aukilabs/posemesh, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aukilabs/posemesh
- Repository: https://github.com/aukilabs/posemesh

## Overview

Step 1: Identify Project Type and Purpose
- This is an open-source, multi-language SDK and protocol implementation named “Posemesh” for decentralized machine perception.
- Core functionality (written in Rust) implements the protocol domain logic, message formats, storage, network layer, and runtime.
- SDK layer (CMake/C++) generates bindings and platform-specific libraries for C, C++, Swift, JavaScript, WebAssembly, Python, and more.
- Third-party integrations include Protobuf (for message schemas), libp2p (for P2P networking), OpenCV (for computer vision), GLM (math), etc.

Step 2: Analyze File Structure
- Top-level “core” directory: multiple Rust crates:
- core/base
- core/domain (business logic, datastores, spatial reconstruction)
- core/networking (P2P, client, event handling, WASM support)
- core/runtime (bootstrapping)
- core/utils (shared helpers)
- core/examples (client, relay, concurrent tests)
- core/include (C/C++ headers for the Rust library via cbindgen)
- Top-level “sdk” directory:
- CMake build system and scripts to compile C++ library and platform targets
- “gentool” JS code generator to transform Protobuf definitions into language-specific APIs
- Folders for C++, C, platform Apple/Swift, platform Web (WASM + JS)
- interface JSON schemas for types
- example projects and documentation
- Third-party: packaged Protobuf compiler, OpenCV, GLM, iOS CMake toolchain, etc.

Step 3: Extract README Insights
- The repo implements a “DePIN” (decentralized protocol) for spatial computing and AI perception.
- Stakeholders: community-driven development, examples for how to run nodes and clients.

1. Core Layer (Rust Crates):
– Domain Logic
– Networking (libp2p client, WASM, binding helpers)
– Runtime
– Base & Utils
– Protobuf Schema Definitions
2. Data Stores:
– Filesystem Store
– Remote Store (networked metadata)
3. SDK Layer:
– CMake Build System
– Language Generators (gentool)
– Generated C/C++ Libraries & Headers
– Platform Bindings: Apple (Swift/ObjC), Web (WASM + JS), Python
4. Third-Party Dependencies:
– Protobuf Compiler & Runtime
– libp2p P2P Networking
– OpenCV (optional computer vision)
– GLM (math)
5. Example Applications:
– Rust client & relay binaries
– Browser example (Vite + JS)
– Python wrapper (via pybindgen)

- Core Domain ⟶ Protobuf (serializes/deserializes messages)
- Core Domain & Runtime ⟷ Core Networking (sends/receives domain messages)
- Core Networking ⟶ External P2P Network (libp2p)
- Domain ⟶ Data Stores (reads/writes metadata and spatial data)
- SDK Build System ⟶ Core Crates (calls cargo & build.rs to produce libraries)
- gentool ⟶ Protobuf Definitions (generates language stubs)
- CMake & Scripts ⟶ Platform Source ⟶ Produce platform binaries/frameworks
- Generated Bindings ⟶ Application Code (C/C++, Swift, JS, Python)

c. Architectural Patterns & Design Principles:
- Modularity: distinct Rust crates for bounded contexts (domain vs networking).
- Layered architecture: core logic separated from SDK generation and platform glue.
- Protocol-first: Protobuf schemas drive code generation across languages.
- Multi-platform: compile targets for native (Apple), WASM for browser, C/C++ for embedding.
- Plugin-style extensibility via “gentool” for new language targets.

d. Key Technologies / Frameworks:
- Rust & Cargo for core crates.
- build.rs scripts for cbindgen and FFI glue.
- Protobuf & protoc for schema compilation.
- CMake for SDK native builds.
- JS/Node/Vite for browser examples.
- pybindgen for Python wrappers.
- libp2p for networking.
- OpenCV, GLM for vision/math in SDK.

Step 5: Tailoring Guidelines for This Open-Source Tool
- Core protocol implementation and how SDK exposes that protocol to multiple languages.
- Where to plug in new language generators (gentool) and platform build rules.
- Extension points: additional datastores, custom P2P behaviors, new client binaries.

Step 6: Diagramming Conventions
- SDK build & generators = another
- Platform targets = a third
- Third-party external dependencies = grey/outside border

Step 7: Level of Detail
- Gentool folder as a separate generator service that reads .proto files.
- How platform folders (Apple, Web) consume both generated libraries and platform-specific source.
- Don’t omit example apps—they demonstrate how all pieces integrate at runtime.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Core Rust Layer
  subgraph "Core Rust Layer"
    base["core/base"]:::core
    domain["core/domain"]:::core
    networking["core/networking"]:::core
    runtime["core/runtime"]:::core
    utils["core/utils"]:::core
    proto["Protobuf Schemas"]:::core
    headers["FFI Headers"]:::core
  end

  %% SDK Layer
  subgraph "SDK Layer"
    cmake["CMake Build System"]:::sdk
    gentool["Language Generators (gentool)"]:::sdk
    genlibs["Generated C/C++ Libraries & Headers"]:::sdk
    jsonschemas["Interface JSON Schemas"]:::sdk
    subgraph "Platform Targets"
      apple["Apple (Swift/ObjC)"]:::platform
      web["Web (WASM + JS)"]:::platform
      python["Python Wrapper"]:::platform
    end
  end

  %% Example Applications
  subgraph "Example Applications"
    client["Client Binary"]:::example
    relay["Relay Binary"]:::example
    testcon["Concurrent Test"]:::example
    webex["Browser Example"]:::example
  end

  %% Third-Party Dependencies
  subgraph "Third-Party Dependencies"
    pb["Protobuf Compiler & Runtime"]:::external
    libp2p["libp2p Networking"]:::external
    opencv["OpenCV"]:::external
    glm["GLM"]:::external
  end

  %% Relationships
  domain -->|"serialize/deserializes"| proto
  domain -->|"uses"| utils
  domain -->|"reads/writes"| base
  runtime <-->|"bootstraps"| networking
  networking -->|"network I/O"| libp2p
  proto -.->|"build-time"| pb
  pb -.->|"generates stubs"| gentool
  gentool -->|"generates bindings"| genlibs
  jsonschemas -.->|"provides schemas"| gentool
  cmake -->|"compiles crates"| base
  cmake -->|"compiles crates"| domain
  cmake -->|"compiles crates"| networking
  cmake -->|"compiles crates"| runtime
  cmake -->|"compiles crates"| utils
  cmake -->|"builds libraries"| genlibs
  genlibs -->|"bind to"| apple
  genlibs -->|"bind to"| web
  genlibs -->|"bind to"| python
  client -->|"runtime"| domain
  client -->|"runtime"| networking
  relay -->|"runtime"| domain
  relay -->|"runtime"| networking
  testcon -->|"runtime"| domain
  testcon -->|"runtime"| networking
  webex -->|"loads WASM/JS"| web
  python -->|"imports bindings"| genlibs

  %% Click Events
  click base "https://github.com/aukilabs/posemesh/tree/main/core/base"
  click domain "https://github.com/aukilabs/posemesh/tree/main/core/domain"
  click networking "https://github.com/aukilabs/posemesh/tree/main/core/networking"
  click runtime "https://github.com/aukilabs/posemesh/tree/main/core/runtime"
  click utils "https://github.com/aukilabs/posemesh/tree/main/core/utils"
  click proto "https://github.com/aukilabs/posemesh/blob/main/core/protobuf/domain_data.proto"
  click headers "https://github.com/aukilabs/posemesh/tree/main/core/include"
  click client "https://github.com/aukilabs/posemesh/tree/main/core/examples/client"
  click relay "https://github.com/aukilabs/posemesh/tree/main/core/examples/relay"
  click testcon "https://github.com/aukilabs/posemesh/tree/main/core/examples/test-concurrent"
  click python "https://github.com/aukilabs/posemesh/blob/main/core/scripts/pybindgen.sh"
  click cmake "https://github.com/aukilabs/posemesh/blob/main/sdk/CMakeLists.txt"
  click gentool "https://github.com/aukilabs/posemesh/tree/main/sdk/gentool/"
  click genlibs "https://github.com/aukilabs/posemesh/tree/main/sdk/include/Posemesh"
  click jsonschemas "https://github.com/aukilabs/posemesh/tree/main/sdk/interface/"
  click apple "https://github.com/aukilabs/posemesh/tree/main/sdk/platform/Apple/"
  click web "https://github.com/aukilabs/posemesh/tree/main/sdk/platform/Web/"
  click webex "https://github.com/aukilabs/posemesh/tree/main/sdk/platform/Web/examples/"
  click pb "https://github.com/aukilabs/posemesh/tree/main/third-party/protobuf/"
  click opencv "https://github.com/aukilabs/posemesh/tree/main/third-party/opencv/"
  click glm "https://github.com/aukilabs/posemesh/tree/main/third-party/glm/"

  %% Styles
  classDef core fill:#AED6F1,stroke:#1B4F72,color:#1B2631
  classDef sdk fill:#ABEBC6,stroke:#186A3B,color:#0B5345
  classDef platform fill:#F9E79F,stroke:#B7950B,color:#7D6608
  classDef example fill:#E8DAEF,stroke:#512E5F,color:#4A235A
  classDef external fill:#D5D8DC,stroke:#566573,color:#1C2833
```
