lhumina_code/home
21
0
Fork 0
Code Issues 13 Pull requests Projects Releases Packages Wiki Activity Actions

Comprehensive Hero ecosystem docs update #42

New issue
Closed
opened 2026-03-18 22:50:56 +00:00 by mik-tf · 2 comments
mik-tf commented 2026-03-18 22:50:56 +00:00
Owner
Copy link

Problem

The docs in lhumina_code/docs_hero are outdated and missing key architectural details that have evolved significantly during recent sessions.

What needs documenting

Architecture

  • OSIS MCP data flow: MCP client → hero_osis_ui (routes.rs dispatch) → Unix socket → hero_osis_server (dispatch_jsonrpc → OsisRpcHandler) → OTOML/Redis
  • 3-part vs 2-part method routing: domain.Type.method vs Type.method — when to use each, gotchas (e.g. contact exists in both identity and business domains)
  • OTOML format: O: prefix + TOML key-value pairs — how objects are serialized/deserialized
  • Socket strategy: Unix domain sockets, per-context subdirectories (/root/hero/var/sockets/{context}/hero_osis_server.sock)

Service architecture

  • HeroRpcServer / HeroUiServer pattern (from #27): the new unified server builder, migration status
  • OpenRPC → MCP → SDK → docs pipeline: how OpenRPC specs auto-generate everything
  • Domain structure: each OSIS domain (identity, calendar, communication, files, projects, etc.) with their type_names and available methods

Deployment

  • Build pipeline: make dist → Docker build → push → deploy flow
  • Environment strategy: herodev vs hero vs demo
  • Service configuration: zinit/hero_init service files, socket discovery

AI integration

  • Shrimp → MCP bridges: direct bridge spawning pattern
  • AI broker: LLM-only proxy role (after #36 cleanup)
  • SSE streaming: token-by-token streaming from shrimp through archipelagos UI

Approach

Update lhumina_code/docs_hero collections with current state. Can be done incrementally — start with architecture + OSIS data flow since those are freshly understood from #41 work.

## Problem The docs in `lhumina_code/docs_hero` are outdated and missing key architectural details that have evolved significantly during recent sessions. ## What needs documenting ### Architecture - **OSIS MCP data flow**: MCP client → hero_osis_ui (routes.rs dispatch) → Unix socket → hero_osis_server (dispatch_jsonrpc → OsisRpcHandler) → OTOML/Redis - **3-part vs 2-part method routing**: `domain.Type.method` vs `Type.method` — when to use each, gotchas (e.g. `contact` exists in both identity and business domains) - **OTOML format**: `O:` prefix + TOML key-value pairs — how objects are serialized/deserialized - **Socket strategy**: Unix domain sockets, per-context subdirectories (`/root/hero/var/sockets/{context}/hero_osis_server.sock`) ### Service architecture - **HeroRpcServer / HeroUiServer pattern** (from #27): the new unified server builder, migration status - **OpenRPC → MCP → SDK → docs pipeline**: how OpenRPC specs auto-generate everything - **Domain structure**: each OSIS domain (identity, calendar, communication, files, projects, etc.) with their type_names and available methods ### Deployment - **Build pipeline**: `make dist` → Docker build → push → deploy flow - **Environment strategy**: herodev vs hero vs demo - **Service configuration**: zinit/hero_init service files, socket discovery ### AI integration - **Shrimp → MCP bridges**: direct bridge spawning pattern - **AI broker**: LLM-only proxy role (after #36 cleanup) - **SSE streaming**: token-by-token streaming from shrimp through archipelagos UI ## Approach Update `lhumina_code/docs_hero` collections with current state. Can be done incrementally — start with architecture + OSIS data flow since those are freshly understood from #41 work.
mik-tf commented 2026-03-19 01:01:29 +00:00
Author
Owner
Copy link

Document: Markdown rendering pattern in archipelago islands

Used in Hero Books and now AI Assistant. Should be documented as a standard pattern.

Pattern:

fn markdown_to_html(text: &str) -> String {
    use pulldown_cmark::{html, Options, Parser};
    let mut opts = Options::empty();
    opts.insert(Options::ENABLE_STRIKETHROUGH);
    opts.insert(Options::ENABLE_TABLES);
    let parser = Parser::new_ext(text, opts);
    let mut html_output = String::new();
    html::push_html(&mut html_output, parser);
    html_output
}

Usage in RSX:

div {
    class: "markdown-content",
    dangerous_inner_html: markdown_to_html(&content),
    // IMPORTANT: no child RSX nodes — Dioxus ignores dangerous_inner_html if children exist
}

Key rules:

  1. Add pulldown-cmark = { version = "0.12", default-features = false, features = ["html"] } to island Cargo.toml
  2. dangerous_inner_html div must have NO RSX children (Dioxus silently falls back to text)
  3. Add CSS classes for rendered HTML (.markdown-content strong, .markdown-content code, etc.)
  4. After adding new Cargo.toml deps to islands: docker volume rm hero-wasm-target before make dist (#46)
### Document: Markdown rendering pattern in archipelago islands Used in Hero Books and now AI Assistant. Should be documented as a standard pattern. **Pattern:** ```rust fn markdown_to_html(text: &str) -> String { use pulldown_cmark::{html, Options, Parser}; let mut opts = Options::empty(); opts.insert(Options::ENABLE_STRIKETHROUGH); opts.insert(Options::ENABLE_TABLES); let parser = Parser::new_ext(text, opts); let mut html_output = String::new(); html::push_html(&mut html_output, parser); html_output } ``` **Usage in RSX:** ```rust div { class: "markdown-content", dangerous_inner_html: markdown_to_html(&content), // IMPORTANT: no child RSX nodes — Dioxus ignores dangerous_inner_html if children exist } ``` **Key rules:** 1. Add `pulldown-cmark = { version = "0.12", default-features = false, features = ["html"] }` to island Cargo.toml 2. `dangerous_inner_html` div must have NO RSX children (Dioxus silently falls back to text) 3. Add CSS classes for rendered HTML (`.markdown-content strong`, `.markdown-content code`, etc.) 4. After adding new Cargo.toml deps to islands: `docker volume rm hero-wasm-target` before `make dist` (#46)
mik-tf commented 2026-03-26 00:21:20 +00:00
Author
Owner
Copy link

Closing — consolidated into #81 which now includes all architecture documentation items from this issue.

Signed-off-by: mik-tf

Closing — consolidated into https://forge.ourworld.tf/lhumina_code/home/issues/81 which now includes all architecture documentation items from this issue. Signed-off-by: mik-tf
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
development
main
No results found.
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
lhumina_code/home#42
No description provided.