Crate hexser 

Zero-boilerplate hexagonal architecture with graph-based introspection.

hexser provides reusable traits and types for building applications with Hexagonal Architecture (Ports and Adapters). Components you derive are automatically registered into an in-memory architecture graph you can query, validate, visualize, and export for AI agents — no manual wiring.

Architecture Layers

• Domain: Core business logic (HexEntity, HexValueItem, Aggregate)
• Ports: Interface definitions (Repository, QueryRepository, UseCase, Query)
• Adapters: Port implementations (Adapter, Mapper)
• Application: Use case orchestration (Directive, DirectiveHandler)
• Infrastructure: External concerns (Config)

Quick Start

use hexser::prelude::*;

// A domain entity: derive HexEntity (Id is taken from the `id` field) and HexDomain to
// register it in the architecture graph.
#[derive(HexEntity, HexDomain)]
struct User {
    id: String,
    email: String,
}

// A repository port. Repository is save-only; reads live on QueryRepository.
trait UserRepository: Repository<User> {
    fn find_by_email(&self, email: &str) -> HexResult<Option<User>>;
}

// An adapter implementing the port. Deriving HexAdapter registers it in the graph and
// implements the `Adapter` marker trait for you.
#[derive(HexAdapter)]
struct InMemoryUserRepository {
    users: Vec<User>,
}

Feature Flags

default = ["macros", "static-di"].

• macros: derive macros (HexEntity, HexDomain, HexPort, …) — on by default.
• static-di: zero-cost, WASM-friendly static dependency injection — on by default.
• serde: Serialize/Deserialize for the rich error types (see also the HEXSER_INCLUDE_SOURCE_LOCATION env var, which gates whether source locations are included in serialized errors).
• ai: machine-readable architecture context export (AIContext, ContextBuilder).
• mcp: Model Context Protocol server (implies ai).
• visualization: DOT / Mermaid / JSON diagram export.
• container: dynamic (runtime) DI container (uses tokio).
• async: enables tokio / async-trait for downstream async adapters.
• full: all of the above.

Revision History

• 2026-09-11T00:00:00Z @AI: Declare the private clock module — single guard for the SystemTime::now() panic on wasm32-unknown-unknown.
• 2026-07-21T00:00:00Z @AI: Rewrite crate header — correct feature list/default, drop the stale Phase-1/future-phases framing and nonexistent graph/analysis features; Quick Start now derives the real macros.
• 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::Direction;

pub use crate::ports::FindOptions;

pub use crate::ports::InputPort;

pub use crate::ports::OutputPort;

pub use crate::ports::Query;

pub use crate::ports::QueryRepository;

pub use crate::ports::Repository;

pub use crate::ports::Sort;

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 that REGISTERS a type: it implements Registrable with the given layer and role AND submits the component to the inventory registry, so the type is in HexGraph::current().

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.

Derive Macros

HexAdapter

HexAggregate

HexDirective

HexDomain

HexEntity

HexPort

HexQuery

HexRepository

HexValueItem