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 ships with a CLI tool that bootstraps a fully wired project in seconds. Running hexcore init creates the directory structure, Python packages, a root config.py with repository_discovery_paths pre-filled, and an Alembic migration setup — so you can start writing domain logic immediately. This page explains both available templates and the files each one generates.

​
Installation and basic usage

pip install hexcore

hexcore init <project_name> --template <hexagonal|vertical-slice>
The <project_name> argument becomes the root folder for your new project. The --template (or -t) option selects the directory layout. If --template is omitted it defaults to hexagonal.
The hexagonal template follows strict hexagonal architecture with explicit domain, application, and infrastructure layers under src/.
hexcore init my_project --template hexagonal
Generated directory tree:
my_project/
├── config.py
├── manage.py
├── .gitignore
├── README.md
├── alembic.ini
├── alembic/
│   └── env.py
└── src/
    ├── __init__.py
    ├── domain/
    │   └── __init__.py
    ├── application/
    │   └── __init__.py
    └── infrastructure/
        ├── __init__.py
        └── database/
            ├── __init__.py
            ├── models/
            │   └── __init__.py
            ├── documents/
            │   └── __init__.py
            └── migrations/
                └── versions/
└── tests/
    ├── __init__.py
    └── domain/
        └── __init__.py
Generated config.py:
config.py
from hexcore.config import ServerConfig

config = ServerConfig(
    repository_discovery_paths={
        "src.infrastructure.repositories",
        "src.infrastructure.repositories.implementations",
    }
)
Alembic env.py (key additions):
alembic/env.py
from alembic import context
from hexcore.config import LazyConfig
from hexcore.infrastructure.repositories.orms.sqlalchemy import Base
from hexcore.infrastructure.repositories.orms.sqlalchemy.utils import import_all_models
import src.infrastructure.database.models as models

import_all_models(models)

config = context.config

database_url = LazyConfig().get_config().sql_database_url
if database_url:
    config.set_main_option("sqlalchemy.url", database_url)

target_metadata = Base.metadata

​
What gets auto-generated

config.py

A root-level config.py with a ServerConfig instance that has repository_discovery_paths pre-filled for the chosen template. Edit this file to set your database URLs and other settings.

manage.py

An entry-point script that wires the HexCore CLI into your project. Run python manage.py --help to see all available commands.

Alembic setup

alembic init is run automatically, alembic.ini is updated with the correct version_locations path, and alembic/env.py is patched to read sql_database_url from LazyConfig and import all SQLAlchemy models.

Python packages

Every directory is created as a proper Python package (contains __init__.py), so imports work without any extra configuration.

​
manage.py entry point

The generated manage.py delegates directly to the HexCore CLI:
manage.py
from hexcore.infrastructure.cli import app as CLI

if __name__ == "__main__":
    CLI()
Run CLI commands through manage.py: 
# Create and apply Alembic migrations
python manage.py make-migrations "initial schema"
python manage.py migrate

# Scaffold a new domain module (hexagonal template)
python manage.py create-domain-module orders

# Run the test suite
python manage.py test tests/

​
Adding domain modules (hexagonal template)

After initialising the project with the hexagonal template you can scaffold a new domain module with all the standard files: 
python manage.py create-domain-module products
This creates src/domain/products/ with: 
src/domain/products/
├── __init__.py
├── entities.py        # (empty — define your entities here)
├── repositories.py    # IProductRepository interface stub
├── services.py        # ProductService stub
├── value_objects.py   # Value object template with comments
├── events.py          # EntityCreatedEvent usage example
├── enums.py           # (empty)
└── exceptions.py      # (empty)
And a matching test directory: 
tests/domain/products/
├── __init__.py
└── test_products_entities.py
The create-domain-module command is only available when using the hexagonal template because it scaffolds into src/domain/. For the vertical-slice template, create feature slices manually under src/features/.

Build docs developers (and LLMs) love

Get started for freeTalk to us