Orion: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Orion is a declarative services runtime written in Rust. It exposes business logic management through channels (service endpoints) and workflows (task pipelines powered by dataflow-rs) via a REST API. Ships as a single binary with an embedded SQLite database.

This repo is a cargo workspace (monorepo) with five crates: crates/orion-server (the runtime — everything below describes it), crates/orion-cli (the CLI, which has its own CLAUDE.md), two shared library crates, and crates/orion-plugin-sdk (the guest crate a plugin author links against — the orion:plugin WIT bindings, a Plugin trait over JSON and export_plugin!; it depends on nothing else in the workspace, carries its own copy of crates/orion-server/wit/orion-plugin.wit which plugin_sdk_test.rs keeps byte-identical to the server's, and publishes as a third rider). The test fixture (crates/orion-server/tests/fixtures/plugins/guest) and the two example guests (examples/plugins/fixed-width, examples/plugins/c4-rules) are built on it; after changing any of them, the SDK or the WIT, run the build.sh beside them and commit the rebuilt component — the plugin-sdk CI job rebuilds all three from source and runs the ABI cases (tests/fixtures/plugins/abi-cases.json) and the examples' offline cases against the fresh bytes. crates/orion-api is the wire contract: response DTOs, domain enums, the error envelope + codes registry, and the bulk-import report — the server serializes these types, clients deserialize them; the server re-exports them under their pre-1.0 paths (e.g. crate::errors::FieldError, storage::models::EntityStatus). Its deserialization is tolerant by design (every field defaults, unknown fields ignored) so version skew between server and CLI keeps working; its utoipa feature (enabled only by the server) adds the ToSchema derives for the OpenAPI document. crates/orion-client is the one HTTP transport over that contract — OrionClient (auth, envelope unwrap, typed ClientError) plus the paths module every endpoint path is built from; both orion-cli and the server's package_cli drive it, and it is the only crate that owns reqwest for API calls. None of the three library crates has a release cycle of its own — no tag names them; crates-publish.yml publishes them automatically as riders (skip-if-present, dependency order) right before orion-server, because crates.io refuses a crate whose dependency it doesn't host. All five crates share one version, workspace.package.version in the root Cargo.toml, inherited with version.workspace = true and repeated only in the two [workspace.dependencies] requirements (a path dependency needs a version to be publishable). That is what makes the riders safe: a release always moves the number, so skip-if-present can never fire on a rider whose contents changed. Bump it with cargo release, never by hand in a member manifest. Note that orion-server is the only binary crate on crates.io: the orion-cli name there belongs to an unrelated 2021 crate, so the CLI ships via the dist installers, the Homebrew tap, GHCR and cargo install --git instead (see RELEASING.md). default-members points bare cargo commands at the server; use --workspace or -p orion-cli to reach the CLI. Only the UI lives in a separate repo (Orion-ui).