Orion CLAUDE.md

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 four crates: crates/orion-server (the runtime — everything below describes it), crates/orion-cli (the CLI, which has its own CLAUDE.md), and two shared library crates. 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. Neither library crate 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 four 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).