HeroOsis

A human-centric backend server entirely generated from schema definitions using OSIS (Object Storage with SmartID).

Quick Start

make install  # Build and install to ~/hero/bin
make run      # Start server + UI via zinit
make dev      # Run server with debug logging (no zinit)
make help     # Show all available commands

Architecture

crates/
  hero_osis/          — Core types and domain handlers (library)
  hero_osis_server/   — JSON-RPC server over Unix sockets (binary)
  hero_osis_sdk/      — SDK client library (library)
  hero_osis_ui/       — Admin panel + /rpc proxy (binary)
  hero_osis_examples/ — Example programs and integration tests

Sockets

All services bind exclusively to Unix domain sockets:

Service	Socket
Server	~/hero/var/sockets/{context}/hero_osis_server.sock
UI	~/hero/var/sockets/hero_osis_ui.sock

No service opens a TCP port. Access via hero_proxy for HTTP.

How It Works

HeroOsis is built on a schema-first architecture. All types, storage, RPC handlers, and documentation are auto-generated from .oschema files in schemas/.

schemas/{domain}/*.oschema  →  build.rs  →  Generated Code
                                    ↓
               ┌────────────────────┼────────────────────┐
               ↓                    ↓                    ↓
       crates/hero_osis/     crates/hero_osis_sdk/  docs/schemas/
       - types_generated.rs  - client code          - API docs
       - rpc_generated.rs
       - osis_server.rs

The herolib-osis crate handles:

• OSchema parsing - Schema language for defining types
• Code generation - Rust structs, builders, CRUD methods
• Storage - Filesystem-based with SmartID identifiers
• Full-text search - Tantivy-powered indexing
• RPC server - JSON-RPC endpoints per domain

Example Schema

# schemas/business/company.oschema
Company = {
    sid: sid                    # SmartID (auto-generated)
    name: str [rootobject]      # Marks as storable type, indexed
    description?: str [index]   # Optional, full-text indexed
    website?: str
    country?: str
    active: bool
    tags: [str]
}

Running cargo build generates:

• Company struct with all fields
• OsisBusiness handler with CRUD methods
• JSON-RPC methods for the domain
• SDK client code

Domains

Domains are logical groupings of related types. Each domain compiles independently via feature flags.

Domain	Description
calendar	Events, planning, scheduling
files	Documents, folders, sharing
finance	Money, payments, transactions
communication	Messages, channels, notifications
identity	Profiles, sessions, contacts
projects	Tasks, issues, requirements
code	Source code, changes, releases
business	CRM, deals, contracts
network	Network nodes, marketplace
settings	User preferences
base	Base types and utilities
ledger	Ledger, KVS, DNS, groups
media	Photos, songs, media management
ai	AI agents, bots, chat services
flow	Workflow DAGs for agent intelligence
job	Distributed job execution

Environment Variables

Variable	Default	Description
HERO_OSIS_DATA_DIR	~/hero/var/hero_osis/data	Data directory
HERO_OSIS_SEED_DIR	-	Seed directory for auto-seeding
HERO_CONTEXTS	root	Contexts to register (comma-separated)

Seeding Data

make seed    # Seed from ./data/mock

Seed files are TOML with a _type field:

_type = "Company"
name = "ACME Corporation"
country = "US"
active = true

Important: For types with nested objects (like Theme), all top-level fields must come BEFORE [section] headers. See Seeding Documentation for details and common pitfalls.

Adding a New Domain

1. Create schemas in schemas/{domain}/*.oschema
2. Add feature flag to Cargo.toml
3. Register domain in build.rs
4. Add handler in server main.rs
5. Run cargo build

Resources

• OSIS Documentation - Full OSIS reference
• OSchema Specification - Schema language details
• Seeding Documentation - Mock data seeding guide and TOML pitfalls

License

Apache-2.0