Skip to content
Shinro Studio

The Module System

A module is a unit — binary, asset, or both — defined by a module descriptor. The Backend Kernel composes and hot-swaps them at runtime. Descriptors are written in a TOML-inspired DSL that adds support for expressions; they are designed to be human-readable, machine-generable, and AI-friendly through the Model Context Protocol (MCP).

Why modules, not scripts

Scripts are black boxes. You don’t know what is happening inside a script until you read its code, and even then you have to trust the runtime to behave the way the script intended. Modules invert this. Every parameter, every command line, every dependency, every capability is declared in the descriptor. The black box becomes transparent: you can audit, monitor, and operate the system from Shinro Studio without leaving the GUI. The same descriptor that the kernel uses to compose the module is the descriptor an engineer reads to understand it, and the descriptor an AI agent consumes through MCP to reason about it. There is one source of truth.

Descriptor example

The descriptor is the only formal definition of a module. Everything the kernel needs to acquire, build, and compose it lives there.

# Illustrative only. Descriptors are written in a TOML-inspired DSL with expressions support.
# Canonical schema is being finalized.
[module]
name    = "arduino-toolchain"
version = "0.1.0"
type    = "toolchain"


[capabilities]
provides = ["cpp:avr-gcc", "flash:avrdude"]


[requirements]
host = ["linux", "macos", "windows"]


[dependencies]
"shinro/toolchain-core" = "^0.2"


[acquisition]
source = "<vendor download URL>"


[build]
steps = ["<build invocation>"]

The schema above shows the shape of a descriptor, not its final field set.

Module types

  • Toolchain modules — compilers, flashers, simulators-as-toolchains. Provide build steps for other modules.
  • Library modules — reusable code units (perception primitives, SLAM, motion planning).
  • Hardware modules — abstractions over a physical board, sensor, or actuator family. Tie into the Hardware abstraction layer (HAL) and Hardware discovery.
  • Resource modules — source files, images, datasets, model weights, calibration data, recordings — any kind of asset that participates in the module graph but is not itself executable.
  • Capability modules — higher-level features composed of other modules (e.g., a “follow-me” capability built on perception + control libraries).

Capabilities and requirements

Modules declare what they provide and what they require from the environment. The kernel refuses to compose incompatible modules at install time, not at runtime. A capability mismatch surfaces as a kernel error before any code runs, not as a crash in the middle of a deployment.

Versioning

Per-module version constraints, similar in spirit to Cargo (caret, tilde, exact). A module declares its dependency versions explicitly, the kernel resolves the graph, and ambiguity surfaces at the descriptor level rather than the binary level.

Stores

A store is a descriptor index — a registry of modules the kernel can pull from. Stores can be self-hosted or community-run. A default public store is planned for launch.

Working folders

Modules install into per-session working folders rather than mutating the host OS. The working folder is the only writable surface. A clean session is one folder deletion away.

Hot-swap module deployment

Hot-swap is atomic at the module boundary: a running module is replaced as a unit, and the new version is composed with the rest of the graph through the same capability / requirement interface. The kernel guarantees that the swap either completes coherently or is rejected before any state moves.

Shared-RAM inter-module communication

Modules communicate via shared memory, not serialized message passing. The latency cost of serialize/deserialize is gone by construction.

MCP integration

The descriptor is the contract between the kernel, the engineer, and the AI. Through the Model Context Protocol, an AI agent can read the descriptor of every loaded module — its capabilities, its requirements, its current state, its dependencies — and reason about the system as a whole rather than guessing from logs. This is what makes agentic engineering on top of Shinro tractable: the agent operates on the same source of truth the kernel does.

Kernel API

The Backend Kernel exposes a small surface for module load, swap, and capability lookup. The canonical API is documented separately.

CLI

The Shinro CLI manages kernel initialization, module installation, composition, and deployment. The reference command listing is documented separately.

100%