Architecture Overview

Animus is a Rust-only agent orchestrator built as a Cargo workspace of 10 crates. It provides the animus CLI, daemon runtime, shared workflow execution/runtime helpers, MCP server, plugin host, and plugin protocol crates. Provider, subject, transport, and web UI integrations run as external stdio plugins rather than in-process desktop or web shell frameworks. The workspace also depends on external launchapp-dev/animus-protocol crates. The root Cargo.toml now pins the main protocol family (protocol, animus-config-protocol, animus-subject-protocol, animus-provider-protocol, animus-session-backend, animus-journal-protocol, and animus-actor) to the unified v0.1.26 tag; crates/orchestrator-cli/Cargo.toml also pins the CLI-side animus-control-protocol, animus-log-storage-protocol, animus-subject-protocol-wire, and animus-workflow-runner-protocol crates to v0.1.26, while animus-queue-protocol and the separate animus-subject-protocol-v05 compatibility line remain on v0.5.10.

Trust code and generated references over hand-maintained summaries when they disagree. Start with:

• Full System Architecture
• Runtime Architecture
• Plugin System
• Crate Map
• Runtime Topology Diagram

Crate Dependency Graph

The external protocol dependency sits at the foundation for shared types, configuration shapes, and runtime path derivation.

orchestrator-core provides the domain services and state mutation APIs used by the CLI, daemon, and plugin preflight paths.

orchestrator-cli composes the workspace into the user-facing animus command surface.

Kernel and Plugin Roles

The kernel crates host the daemon and CLI; everything provider-, subject-, transport-, trigger-, and UI-specific runs as an installed stdio plugin behind the plugin host.

The plugin extraction is complete: provider, subject, transport, trigger, web UI, and workflow-runner integrations now live out-of-tree under launchapp-dev, while this workspace stays focused on the Rust kernel and its shared runtime plumbing.

Architecture Decision Records

• Kernel and Flavors -- v0.5 product architecture commitment. Animus is a kernel + a default flavor (curated plugin bundle) for portfolio builders. Future flavors emerge from real customer pull, not roadmap speculation. Read this before adding scope.
• Naming Contract -- One name everywhere: animus.* for MCP tools, env vars, config dirs, pack ids, and JSON envelopes
• Full System Architecture -- Canonical end-to-end architecture narrative covering crates, process topology, state, config, services, daemon, workflow execution, plugins, control surfaces, security, observability, and verification
• Runtime Architecture -- Current end-to-end runtime topology, startup flow, state model, crate responsibilities, execution pipeline, and failure boundaries
• Plugin System -- Current stdio plugin architecture: discovery, install state, wire protocol, hosting, security, provider/subject/trigger/transport paths, and operations
• Plugin Pack Kernel -- Package-style plugin architecture for workflows, MCP servers, and bundled domain modules
• Project Init Templates -- Template-driven animus init architecture layered above packs
• Subject Dispatch Daemon -- How the daemon schedules and dispatches workflow subjects
• Subject Backend Plugins -- Current subject_backend contract: normalized subjects, kind-scoped routing, preflight requirements, CLI/daemon behavior, and authoring rules
• Knowledge / RAG Binding (v0.5.5 design) -- Design for the memory_store plugin kind, agent + workflow memory_bindings: shape, runtime contract injection point, CLI surface, and the v0.6 implementation checklist. Ships design-only in v0.5.5; honest stops documented inline
• Animus Chat -- v0.5.10 chat architecture: conversation subjects, chat_provider plugins, daemon-side tool loop, streaming control protocol, and OpenAI-compatible HTTP surface
• Tool-Driven Mutation Surfaces -- How state mutations are channeled through tool abstractions
• Workflow-First CLI -- Why workflows are the primary execution primitive
• Phase Contracts -- Universal phase verdicts, YAML-defined fields, and runtime validation
• Multi-Tenant + RBAC Design Proposal (v0.5.5+) -- Principal model, role/permission scaffold, four-chokepoint authz, and the explicit v0.6 deferrals for per-tenant state isolation and per-principal secret routing

Deep Dives

• Runtime Topology Diagram -- High-level Mermaid diagram of operators, daemon, plugins, and external systems with design rationale
• Crate Map -- All workspace crates grouped by responsibility with descriptions
• ServiceHub Pattern -- Dependency injection via the ServiceHub trait
• Provider Session Host -- Historical session-backend design notes plus the current orchestrator-plugin-host::session provider-plugin boundary