Hanami Guide

Applies to: Hanami 2.x, Ruby 3.1+, Web Applications, APIs, Domain-Driven Design, Clean Architecture

Core Principles

1. Clean Architecture: Strict separation between delivery (actions/views) and domain (operations/repos)
2. Slices as Bounded Contexts: Each slice is an isolated module with its own dependencies
3. Dependency Injection: Auto-injection via include Deps[...] -- no globals, no singletons
4. dry-rb Ecosystem: Leverage dry-types, dry-monads, dry-validation for type safety and result handling
5. ROM Persistence: Relations for queries, repositories for data access, entities for domain objects
6. Convention Over Configuration: Predictable file layout, auto-registration of components

Guardrails

Architecture

• Use slices for bounded contexts (e.g., slices/api/, slices/admin/)
• Keep actions thin -- delegate to operations for business logic