Expand description
Zero-boilerplate hexagonal architecture with graph-based introspection.
The hex crate provides reusable types and traits for implementing
Hexagonal Architecture (Ports and Adapters) with automatic graph construction,
intent inference, and architectural validation. This is Phase 1: Core Foundation,
providing the foundational traits, types, and error handling.
Future phases will add graph construction, derive macros, and analysis capabilities.
§Architecture Layers
- Domain: Core business logic (
HexEntity,HexValueItem,Aggregate) - Ports: Interface definitions (
Repository,UseCase,Query) - Adapters: Port implementations (
Adapter,Mapper) - Application: Use case orchestration (
Directive,DirectiveHandler) - Infrastructure: External concerns (
Config)
§Quick Start
use hexser::prelude::*;
// Define a domain entity
struct User {
id: String,
email: String,
}
impl HexEntity for User {
type Id = String;
}
// Define a port (interface)
trait UserRepository: Repository<User> {
fn find_by_email(&self, email: &str) -> HexResult<Option<User>>;
}
// Implement an adapter
struct InMemoryUserRepository {
users: Vec<User>,
}
impl Adapter for InMemoryUserRepository {}§Feature Flags
default: Core traits and types (zero dependencies)graph: Graph-based introspection (Phase 2+)macros: Derive macros for zero-boilerplate DX (Phase 3+)analysis: Architectural analysis and validation (Phase 4+)
Revision History
- 2025-10-09T14:14:00Z @AI: Remove Entity derive alias, expose HexEntity at crate root for qualified addressing.
- 2025-10-02T13:00:00Z @AI: Re-export inventory and error_codes for proc macros.
- 2025-10-02T12:00:00Z @AI: Add showcase module with Describable and Inspectable traits.
- 2025-10-01T00:01:00Z @AI: Added comprehensive re-exports and prelude module.
- 2025-10-01T00:00:00Z @AI: Initial Phase 1 implementation with core traits and types.
Re-exports§
pub use crate::error::hex_error::Hexserror;pub use crate::result::hex_result::HexResult;pub use crate::domain::Aggregate;pub use crate::domain::DomainEvent;pub use crate::domain::DomainService;pub use crate::domain::HexEntity;pub use crate::domain::HexValueItem;pub use crate::ports::InputPort;pub use crate::ports::OutputPort;pub use crate::ports::Query;pub use crate::ports::Repository;pub use crate::ports::UseCase;pub use crate::adapters::Adapter;pub use crate::adapters::Mapper;pub use crate::application::Application;pub use crate::application::Directive;pub use crate::application::DirectiveHandler;pub use crate::application::QueryHandler;pub use crate::infrastructure::Config;pub use crate::error::codes as error_codes;pub use crate::graph::GraphBuilder;pub use crate::graph::GraphMetadata;pub use crate::graph::HexEdge;pub use crate::graph::HexGraph;pub use crate::graph::HexNode;pub use crate::graph::Layer;pub use crate::graph::NodeId;pub use crate::graph::Relationship;pub use crate::graph::Role;pub use crate::showcase::ArcGraphExt;pub use crate::showcase::Describable;pub use crate::showcase::Inspectable;pub use crate::showcase::PrettyPrint;pub use inventory;
Modules§
- adapters
- Adapters layer module containing port implementations.
- ai
- AI agent integration module for machine-readable architecture.
- application
- Application layer module for use case orchestration.
- container
- Dependency injection container for hexagonal architecture components.
- domain
- Domain layer module containing core business logic types and traits.
- error
- Error types module with rich, actionable error information.
- graph
- Graph module for hexagonal architecture introspection.
- infrastructure
- Infrastructure layer module for external concerns.
- ports
- Ports layer module containing interface definitions for external interactions.
- prelude
- Prelude module for convenient imports.
- registry
- Component registry for compile-time registration.
- result
- Result type module for hex crate.
- showcase
- Showcase module for developer experience traits.
- static_
di - Static (non-dyn) dependency wiring helpers.
- templates
- Template framework for quickly scaffolding hexser components.
Macros§
- hex_
register_ adapter - Convenience macro for Adapter-layer components.
- hex_
register_ application - Convenience macro for Application-layer components.
- hex_
register_ component - Core macro to implement Registrable for a type with a specific layer and role.
- hex_
register_ domain - Convenience macro for Domain-layer components.
- hex_
register_ infrastructure - Convenience macro for Infrastructure-layer components.
- hex_
register_ port - Convenience macro for Port-layer components.
- hex_
static - Build a StaticContainer from an explicit construction block.