Skip to content

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).

  • Event Store

    • Details the EventStore abstraction for persisting and retrieving event streams, crucial for Event Sourcing. Covers its API and concepts like optimistic concurrency.

  • Event Sourced Aggregates

    • Explains how EventSourcedAggregate extends the base Aggregate for event sourcing, managing state through events, and integrating with snapshotting.

  • Projectors and Read Models

    • Describes how Projectors consume event streams to build and maintain denormalized read models optimized for querying. Covers the Projector abstraction and ProjectionStore for state management.

  • Queries

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

  • Specifications

    • Explains the Specification pattern for encapsulating business rules for selecting objects, including the Specification ABC and composite specifications (AndSpecification, OrSpecification, NotSpecification).

  • Translators

    • Describes the Translator (or Mapper/Converter) pattern for transforming data from one object representation to another, using the Translator[Source, Target] ABC.

  • 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.

  • Snapshots and SnapshotStore

    • Details the concept of aggregate snapshots for performance optimization, the Snapshot data structure, and the SnapshotStore abstraction for persistence.

  • 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.