HeroOsis

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

Quick Start

make run      # Build and run server
make dev      # Run with debug logging
make help     # Show all available commands

Server runs at http://127.0.0.1:3377/api:

• RPC endpoints: /api/hero_osis/{domain}/rpc
• DB Inspector: /api/hero_osis/{domain}/inspector

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 specs/schemas/.

specs/schemas/{domain}/*.oschema  →  build.rs  →  Generated Code
                                         ↓
                    ┌────────────────────┼────────────────────┐
                    ↓                    ↓                    ↓
            src/{domain}/         sdk/rust/src/        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

# specs/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
• RPC endpoint at /api/hero_osis/business/rpc
• 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

Environment Variables

Variable	Default	Description
HERO_OSIS_BIND	127.0.0.1:3377	Server bind address (TCP or unix:/path/to.sock)
HERO_OSIS_DATA_DIR	~/hero/var/hero_osis/data	Data directory
HERO_OSIS_SEED_DIR	-	Seed directory for auto-seeding

When managed by hero_zero, HERO_OSIS_BIND is set to unix:~/hero/var/sockets/hero_osis.sock and the service is accessed through hero_proxy at http://localhost:8080/hero_osis/api/.... For local development (make run), the default TCP address is used. See hero_zero sockets docs for the full architecture.

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.

RPC Usage

curl -X POST http://127.0.0.1:3377/api/hero_osis/business/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"company.list","params":{}}'

Methods: {type}.new, {type}.get, {type}.set, {type}.delete, {type}.list, {type}.find

Adding a New Domain

1. Create schemas in specs/schemas/{domain}/*.oschema
2. Add feature flag to Cargo.toml
3. Register domain in build.rs
4. Add handler in src/bin/server.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
• SDK Documentation - Rust client library
• Offline Support - Offline mode, caching, and sync

License

Apache-2.0