Architecture

Koyal is organized as a trait-first Rust workspace:

koyal-api
  koyal-config
  koyal-memory
  koyal-chains
  koyal-dexes
  koyal-exchanges
  koyal-providers (api + config)
  koyal-core (api + memory)
  koyal-runtime (api + config + memory + providers)
    koyal-gateway (api + config + core + runtime)
    koyal-integrations (api + config + runtime)
    koyal

Layered Dependency Contract

koyal-api is the public trait boundary. Leaf implementation crates depend on koyal-api; composition crates are limited to documented edges such as runtime using config/memory/providers and gateway using config/core/runtime. scripts/ci/check_workspace_contract.sh keeps the Cargo workspace graph and architecture docs aligned.

The fast path is intentionally small:

• koyal-api defines stable traits and data contracts.
• koyal-config parses agent frontmatter without regex overhead.
• koyal-memory uses SQLite WAL mode and FTS5 for recall.
• koyal-runtime coordinates ticks, approvals, guardrails, and scheduler work.
• koyal-gateway exposes axum HTTP routes for dashboard integration.

See the full architecture reference for crate boundaries and migration mapping.