Core Concepts

This section provides detailed explanations of the core architectural concepts and patterns used within the castlecraft-engineer library. Understanding these concepts will help you effectively build applications and leverage the framework's capabilities.

Table of Contents

• Aggregates

  • Explains the Domain-Driven Design (DDD) Aggregate pattern, the Aggregate base class, its role in managing consistency boundaries, and how AggregateRepository handles persistence and optimistic concurrency.

• Authentication

  • Covers the authentication mechanisms, focusing on the AuthenticationService for token verification (JWKS, introspection, userinfo) and its caching strategies.

• Authorization

  • Details the authorization framework, including the AuthorizationService, Permission definitions, the @ctx decorator for handlers, and how to implement permission checks.

• Caching

  • Covers caching capabilities using Redis, including configuration, helper utilities, and examples of using synchronous and asynchronous cache clients. Also mentions internal uses like JWKS caching.

• Command Query Responsibility Segregation (CQRS)

  • Provides an overview of the CQRS pattern, explaining the separation of read and write operations and the roles of Commands, Queries, and Events in this architecture.

• Commands

  • Focuses on the write-side of CQRS: the Command base class, CommandHandler for business logic, and the CommandBus for dispatching commands.

• Custom Repositories

  • Explains how to create custom repository methods beyond the generic CRUD operations, often by inheriting from the base repository classes and adding specific query logic.

• Dependency Injection

  • Explains how Dependency Injection (DI) is managed using punq and the ContainerBuilder utility for registering and resolving components like handlers, repositories, and services.

• Events

  • Describes domain events, the Event base class, EventHandler for reacting to events, the in-process EventBus, and abstractions for external event publishing/consumption (ExternalEventPublisher, EventStreamConsumer).

• Queries

  • Focuses on the read-side of CQRS: the Query base class, QueryHandler for data retrieval logic, and the QueryBus for dispatching queries.

• Repositories

  • Details the generic repository pattern for SQLModel entities (ModelRepository, AsyncModelRepository), distinct from AggregateRepository, often used in Query Handlers or for simpler data operations.

• Sagas

  • Describes the Saga pattern for managing distributed transactions or long-running business processes that span multiple services or aggregates, including the Saga base class and SagaManager.

• Security

  • Covers security-related aspects, including data encryption utilities (encrypt_data, decrypt_data using AES-GCM), OIDC token verification via AuthenticationService, and a reference to the authorization framework.

• Unit of Work

  • Explains the Unit of Work (UoW) pattern for managing database transactions, ensuring that a series of operations are committed or rolled back atomically. Covers SQLAlchemyUnitOfWork and AsyncSQLAlchemyUnitOfWork.

---

Each document provides in-depth explanations and code examples to illustrate the concepts.