Skip to content

Welcome to Castlecraft Engineer Documentation

Castlecraft Engineer is a Python library providing a robust set of abstractions designed to help you implement Domain-Driven Design (DDD) building blocks in your applications. Our goal is to offer clear, testable, and maintainable components for building sophisticated software systems.

Core Philosophy

This library is built upon established software design principles, primarily:

  • Domain-Driven Design (DDD): We provide tools to model complex business domains effectively, focusing on concepts like Aggregates, Entities, Value Objects, and Repositories.
  • Command Query Responsibility Segregation (CQRS): The library encourages separating operations that change state (Commands) from operations that read state (Queries), leading to more focused and scalable components.
  • Event-Driven Architecture (EDA): Support for Domain Events allows for decoupled communication between different parts of your system and enables patterns like Event Sourcing (though full Event Sourcing is not a mandatory part of using the library).

Who Is This Library For?

Castlecraft Engineer is for Python developers who are:

  • Building applications using Domain-Driven Design principles.
  • Looking for a structured way to implement CQRS patterns.
  • Seeking to create highly testable and maintainable business logic.
  • Interested in building event-driven systems.

Who Might Find This Library Less Suitable?

While Castlecraft Engineer offers powerful abstractions, it might not be the ideal choice for everyone. Consider alternatives if you are:

  • Building very simple CRUD applications: The architectural patterns (DDD, CQRS) promoted by this library can be overkill for straightforward data entry and retrieval tasks where a simpler ORM or microframework might suffice.
  • Looking for a fully opinionated, all-in-one web framework: Engineer provides core building blocks for business logic and can integrate with various web frameworks, but it doesn't dictate your entire application structure or provide UI components out of the box.
  • Completely new to software architecture concepts like DDD or CQRS: While the library aims to make these patterns accessible, there's an inherent learning curve. Teams without prior exposure might need to invest time in understanding these principles to leverage the library effectively.
  • Needing a solution that strictly enforces a specific database or message broker: Engineer is designed to be flexible. While it offers integrations (like SQLModel), it doesn't lock you into a particular technology for every aspect.
  • Under extremely tight deadlines with no prior experience in these patterns: Adopting and correctly implementing DDD and CQRS takes thoughtful design. If rapid, simple feature delivery is the absolute priority over architectural robustness for a project, the initial investment might be a concern.

Our aim is to provide a powerful toolkit for building complex, maintainable systems. If your project aligns with the core philosophy and benefits, Engineer can be a great asset!

Key Benefits

  • Clear Abstractions: Well-defined base classes and interfaces for Aggregates, Repositories, Commands, Queries, Events, and their handlers.
  • Improved Testability: The separation of concerns and dependency injection (via punq) make components easier to test in isolation.
  • Maintainable Codebase: Promotes a structured approach to organizing business logic, leading to more understandable and maintainable code.
  • Scalability: CQRS patterns can help in scaling read and write operations independently.
  • Flexibility: While providing structure, the library is largely unopinionated about specific web frameworks or database technologies. It offers optional, integrated support for SQLModel as an ORM and Redis for caching, but these are not mandatory for using the core abstractions.

Getting Started

Ready to dive in?

  1. Installation: Head over to the Installation Guide to set up Castlecraft Engineer in your project.
  2. Quick Start: Follow our Quick Start Guide for a hands-on example of using the core components.

Documentation Sections

Explore the documentation to learn more about Castlecraft Engineer:

  • Core Concepts:
    • Aggregates
    • Repositories
    • CQRS Overview
    • Commands
    • Events
    • Event Store
    • Queries
    • Dependency Injection
    • Authorization
  • Tutorials:
    • Building a Complete Feature
  • Testing Guide: Learn how to effectively test applications built with Castlecraft Engineer using the provided testing helpers. (Testing Guide)
  • Contributing: Interested in contributing? Find out how you can help improve the library. (Contributing)
  • Changelog: See what's new in each version. (Changelog)
  • License: Understand the terms under which Castlecraft Engineer is distributed. (License)

We hope this documentation helps you effectively use Castlecraft Engineer to build amazing applications!