Hero Archipelagos

Modular Dioxus 0.7 WASM island applications that connect to backend services via hero_osis_sdk (structured data) and herofossil-webdav-client (files).

Core Principles

1. Dioxus components — Built with Dioxus 0.7 for Rust-based reactive UI
2. WASM modules — Compiled to WebAssembly, run in the browser
3. hero_osis_sdk consumers — Use the unified SDK client to communicate with hero_osis
4. Embeddable — Imported as library components into host applications (embedded mode)
5. Pure Rust + WASM — No Python servers, no Node.js

Quick Start

# Prerequisites: Rust 1.85+
rustup update stable

# Source environment variables (API keys)
source ~/.config/env.sh

# Start the showcase dev server
make run

# Or directly with Dioxus CLI
cd server && dx serve

Required environment variables:

• GROQ_API_KEY — Groq API key for AI features

Project Structure

hero_archipelagos/
├── Cargo.toml              # Workspace definition
├── Makefile                # Build commands
├── core/                   # Shared library for all islands
│   └── src/
│       ├── context.rs      # IslandContext (host, context_name, user, theme, view)
│       ├── island.rs       # IslandSize, IslandMode, IslandInfo, Island trait
│       ├── metadata.rs     # IslandMetadata, ArchipelagoMetadata (build-time)
│       ├── wrapper.rs      # IslandWrapper component (host chrome)
│       ├── views.rs        # ViewDef, ViewList
│       ├── events.rs       # Custom event helpers
│       ├── mcp_macros.rs   # MCP DOM-based tool execution
│       ├── platform.rs     # Platform abstraction (web/mobile)
│       ├── styles.rs       # Shared CSS helpers
│       └── web_component.rs # Custom element registration (standalone mode)
│
├── archipelagos/           # Island crates grouped by domain
│   ├── messaging/          # chat, chats, chat_preview, message
│   ├── communication/      # room, call
│   ├── identity/           # contacts, contact
│   ├── calendar/           # calendar, month, week, day, event, new_event
│   ├── productivity/       # projects, tasks, kanban, sprints, stories
│   ├── files/              # filesystem
│   ├── intelligence/       # ai, intelligence, agents, roles, knowledge, templates
│   ├── system/             # contexts, settings, services, service, theme
│   ├── business/           # business, contracts, finance, hr
│   ├── library/            # album, photo, photos, player, playlists, songs
│   ├── code/               # Code browsing (branches, commits, files)
│   ├── mycelium/           # Decentralized cloud management
│   ├── embed/              # Iframe containers (panel, card, row, hero, hero_service, ...)
│   ├── archipelagos/       # Meta-browser (archipelagos, archipelago, island)
│   └── browser/            # Web browser
│
├── server/                 # Showcase UI (Dioxus web app)
│   ├── src/
│   │   ├── main.rs
│   │   ├── island_display.rs  # Island renderer with IslandWrapper
│   │   └── generated/         # Auto-generated by build.rs
│   │       ├── island_content.rs  # Island component imports + match arms
│   │       ├── registry.rs        # Archipelago/island metadata
│   │       ├── router.rs          # Island routing
│   │       └── props_registry.rs  # Props metadata
│   └── build.rs            # Auto-discovers islands from Cargo.toml metadata
│
├── docs/                   # Documentation
└── examples/               # Example applications

Available Archipelagos

Archipelago	Islands	SDK Features
Messaging	chat, chats, chat_preview, message	communication
Communication	room, call	communication
Identity	contacts, contact	identity
Calendar	calendar, month, week, day, event, new_event	calendar
Productivity	projects, tasks, kanban, sprints, stories	projects
Files	filesystem	herofossil-webdav-client
Intelligence	ai, intelligence, agents, roles, knowledge, templates	ai, embedder
System	contexts, settings, services, service, theme	base
Business	business, contracts, finance, hr	business
Library	album, photo, photos, player, playlists, songs	library
Code	code	code
Mycelium	mycelium	mycelium
Embed	panel, card, row, hero, hero_service, zinit, redis, ...	N/A (iframe)
Archipelagos	archipelagos, archipelago, island	base

Embedding Islands

Islands are standard Dioxus components. Import them as library dependencies:

[dependencies]
hero_archipelagos_core = { path = "path/to/core" }
hero_archipelagos_contacts = { path = "path/to/archipelagos/identity/contacts", default-features = false, features = ["web"] }

use hero_archipelagos_contacts::island::ContactsIslandApp;
use hero_archipelagos_core::IslandContext;

#[component]
fn MyApp() -> Element {
    let context = IslandContext::default();
    rsx! {
        ContactsIslandApp { context: context }
    }
}

Context Configuration

Islands receive configuration via IslandContext:

Field	Description	Example
host	Hero Zero host (service URLs derived from this)	localhost
context_name	Current workspace/context	default
user	User identity (display_name, public_key, avatar_url)	UserIdentity
theme	Theme name	dark
view	Current view / entity ID	list, chat_sid:abc123

Service URLs are derived from the host:

• context.osis_url() → http://{host}:3377 (hero_osis JSON-RPC)
• context.forge_url() → http://{host}:7365 (hero_fossil WebDAV)

SDK Integration

Each island uses hero_osis_sdk with domain-specific features:

// In Cargo.toml
hero_osis_sdk = { workspace = true, features = ["calendar"] }

// In your service
use hero_osis_sdk::calendar::CalendarUnifiedClient;

pub async fn fetch_events(osis_url: &str, context: &str) -> Result<Vec<Event>, String> {
    let client = CalendarUnifiedClient::new(osis_url, context);
    client.event_list().await
}

Documentation

• Creating Islands — Step-by-step guide for adding new islands
• Architecture — Core concepts, types, traits, navigation
• Build System — Build modes, auto-discovery, commands
• Client Integration — Backend service integration
• Server Auto-Discovery — How build.rs generates code
• Theming — CSS variables, theme sync approaches
• Styling — Styling standards and patterns
• View System — View definitions and event protocol
• MCP Data Attributes — AI-driven form interaction
• Object View Components — Component design philosophy
• WASM Optimization — Build modes and size optimization
• Hero OS Specs — Product roadmap and specs
• Hierarchical Archipelagos — Dock grouping pattern

License

Apache-2.0