Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Indroic/HexCore/llms.txt

Use this file to discover all available pages before exploring further.

HexCore is a reusable base module for Python projects that implement hexagonal architecture and event handling. At version 2.5.0, it provides the abstractions, contracts, and utilities that underpin Domain-Driven Design — entities, repositories, domain events, command/query buses, and a Unit of Work — so your teams spend time on business logic, not on re-inventing infrastructure plumbing. It is published on PyPI under the MIT license and requires Python 3.12 or higher.

Domain Primitives

BaseEntity, DomainEvent, EntityCreatedEvent, EntityUpdatedEvent, and EntityDeletedEvent give every aggregate a consistent, validated shape built on Pydantic v2.

Repository Contracts

IBaseRepository defines generic CRUD operations (get_by_id, list_all, save, delete) that your SQLAlchemy or Beanie implementations fulfil.

CQRS Buses

AbstractCommandBus, AbstractQueryBus, and AbstractEventBus separate write-side intent from read-side queries, with in-memory implementations ready for testing.

Smart Background Routing

Decorators like @background_command and @background_handler route commands and event handlers to Celery, Procrastinate, or ARQ with zero boilerplate.

Project CLI

Bootstrap a new project with hexcore init my_project --template hexagonal or --template vertical-slice and get a fully structured directory in seconds.

Multiple Infrastructure Adapters

Optional extras wire in FastAPI, Redis, MongoDB (Beanie), PostgreSQL/SQLite (SQLAlchemy + Alembic), RabbitMQ, Celery, and Procrastinate.

​
What problems does HexCore solve?

Building systems that follow hexagonal architecture means defining the same boilerplate in every project: base entities with audit fields, generic repository interfaces, a Unit of Work that owns transactions, domain event primitives, and command/query buses. HexCore codifies all of these patterns so that a new microservice starts from a solid, tested foundation rather than a blank file.

​
Three architectural layers

HexCore organises code into three clear layers that mirror classic hexagonal architecture:
LayerWhat lives hereHexCore exports
DomainEntities, value objects, repositories (ports), domain events, servicesBaseEntity, IBaseRepository, DomainEvent, Command, Query
ApplicationCQRS handlers, use-cases, DTOs, handler registry, buses (in-memory)AbstractCommandHandler, AbstractQueryHandler, HandlerRegistry, InMemoryCommandBus
InfrastructureORM implementations, CLI, caches, task-queue adapters, workersBaseSQLAlchemyRepository, cli, cache

​
Public exports

Everything you need day-to-day is re-exported from the top-level hexcore package: 
from hexcore import (
    BaseEntity,           # Pydantic entity base with id, created_at, updated_at, is_active
    DomainEvent,          # Immutable domain event base
    EntityCreatedEvent,   # Generic created lifecycle event
    EntityUpdatedEvent,   # Generic updated lifecycle event
    EntityDeletedEvent,   # Generic deleted lifecycle event
    IBaseRepository,      # Generic async CRUD repository contract
    BaseSQLAlchemyRepository,  # SQLAlchemy repository implementation base
    DTO,                  # Pydantic DTO base for application layer
    PermissionsRegistry,  # Role / permission registry
    TokenClaims,          # JWT token claim value object
    cli,                  # Typer CLI sub-module
    cache,                # Cache backends (memory + Redis)
    config,               # LazyConfig and ServerConfig
)

​
Quick install

pip install hexcore
See the Installation guide for optional extras (FastAPI, Redis, SQLAlchemy, MongoDB, RabbitMQ, Celery, Procrastinate) and Python version requirements.
HexCore requires Python 3.12 or later. It relies on Pydantic v2 for entity validation and Typer for the CLI, both of which are installed automatically as core dependencies.

Build docs developers (and LLMs) love

Get started for freeTalk to us