douwevandermeij/fractal

Fractal is an event-sourcing framework that provides infrastructure for building domain-driven applications using a command bus, process execution engine, and multiple storage backends. It supports various message brokers like Kafka, RabbitMQ, and GCP Pub/Sub for event handling, while offering integrations for FastAPI, Django, and Google Cloud services. The system manages application context, service initialization, and data serialization, enabling developers to implement robust, scalable event-driven architectures.

Introduces new components for Google Cloud Pub/Sub integration: a \PubSubEventBus\ for consuming events via subscriptions and a \PubSubEventBusProjector\ for publishing events to topics. The projector dynamically generates topic paths based on the event's \aggregate\_root\_type\ or a provided topic name, and the event bus supports optional threading for message processing.

fractal/contrib/gcp/pubsub · high confidence

Added new event bus implementations for Kafka and RabbitMQ, enabling the application to use these message brokers for event sourcing. The Kafka implementation includes a projector and listener for publishing and consuming events, along with a Docker Compose file for local development. The RabbitMQ implementation provides similar projector and listener components, utilizing the pika library for connection management. These changes allow users to configure their application to use Kafka or RabbitMQ as the backend for event handling.

fractal/contrib/kafka · high confidence

The examples/basic directory now includes a complete, runnable example of a product management application. It defines a Product domain model and a ProductRepository interface, along with an in-memory implementation of the repository. The example demonstrates how to configure the application context to support different repository backends (SQL, file, or in-memory) and integrates with the Fractal framework.

examples/basic · medium confidence

Users can now persist event-sourced data to Google Cloud Firestore via the new \FirestoreEventStoreRepository\ and related \SettingsMixin\. FastAPI applications gain a \BaseModelEnhancedEncoder\ to automatically serialize Pydantic models to JSON. The base \Fractal\ class now exposes \settings\ and \context\ as class attributes, and the package is marked as typed with a \py.typed\ file.

fractal · high confidence

Added a new process execution framework in \fractal/core/process\ featuring \ProcessContext\ with dot-notation attribute access via \AttributeDict\, allowing nested state management. The diff introduces \Action\ and \AsyncAction\ base classes for synchronous and asynchronous process steps, alongside \Process\ and \AsyncProcess\ runners. Additionally, \specifications.py\ provides callable-based specifications (\has\_field\, \field\_equals\, etc.) that support dot notation for checking process context states.

fractal/core/process · high confidence

The event-sourcing module now provides a complete domain model and repository layer for event-driven architectures. A new \EventSourcedAggregateRoot\ base class enables entities to record and release events, while the \EventSourcedRepository\ handles committing event streams. The \Message\ model has been refactored to support structured event data and aggregate root identification. To support different serialization strategies, the \BasicEventStore\ hierarchy introduces four storage backends: \ObjectEventStore\ (stores raw objects), \DictEventStore\ (stores dictionaries), \JsonEventStore\ (stores JSON strings), and \PickleEventStore\ (stores pickled objects). Additionally, abstract mappers (\EventCommandMapper\, \EventProcessMapper\) and a refined \EventProjector\ interface are introduced to map events to commands, processes, and projections.

_fractal/core/event\sourcing · high confidence

Adds new actions for workflow control and data manipulation: \ForEachAction\ and \SubProcessAction\ for handling iterations and nested processes, alongside \IfElseAction\ and \WhileAction\ for conditional and looping logic. The \SetContextVariableAction\ and \SetValueAction\ are refactored to support dot notation for nested field access, and \GetValueAction\ is introduced to extract values from context. These changes enable more complex, dynamic process workflows with backward-compatible specification handling.

fractal/core/process/actions · high confidence

Added CommandBusProjector and EventStoreProjector to handle command dispatch and event persistence respectively, with the CommandBusProjector supporting a list of command mappers for backwards compatibility. The PrintEventProjector was updated to include aggregate\_root\_id in its output and use a dedicated JSON encoder, while also fixing import paths for event and message classes.

_fractal/core/event\sourcing/projectors · medium confidence

The base Service class now includes an install class method that accepts an ApplicationContext, allowing services to be initialized and yielded through the application context.

fractal/core/services · high confidence

The EnumModel class, which provided static methods to convert enum values to a dictionary and back from strings, has been removed from the codebase.

fractal/core/models · high confidence

The project has transitioned from a legacy setup.py configuration to a modern pyproject.toml-based build system, enabling more robust package management. To support this, a Makefile and tox.ini have been added to standardize testing, linting, and CI workflows. Additionally, a .pre-commit-config.yaml file has been introduced to enforce code quality standards, including import sorting, formatting, and test execution, ensuring consistent code style across the repository.

(repo-wide) · high confidence

The framework now uses a singleton ApplicationContext that manages the lifecycle of repositories, services, and event stores. It supports automatic discovery and registration of repositories, command handlers, and ingress/egress services via new decorator-style registration methods. The Settings class is also a singleton that loads environment variables from .env files. Additionally, the JSON encoder now handles Decimal and date objects, and new exception types (AggregateRootError, ObjectNotFoundException) are introduced.

fractal/core/utils · high confidence

The \fractal/contrib/mongo\ directory no longer contains the \repositories.py\ and \specifications.py\ files, which have been removed. This indicates that the MongoDB repository implementation and its associated specification builders have been extracted from this location, likely to a shared or external package, changing how the MongoDB integration is structured within the application.

fractal/contrib/mongo · high confidence

The \tokens.py\ module was added to centralize token verification and role extraction, replacing the previous \util.py\ implementation. This introduces \TokenPayloadRoles\ and specific dependency injection functions (\get\_payload\, \get\_payload\_roles\) that integrate with external \fractal-tokens\ and \fractal-roles\ packages. Additionally, \default.py\ was refactored to use a new \DefaultRestRouterService\ and \BasicRestRouterService\ abstract base classes, which standardize entity CRUD operations and support passing user context (like \uid\) through kwargs to the ingress service.

fractal/contrib/fastapi/routers · high confidence

The command bus implementation has been updated to use Python's generic typing, allowing command handlers to be strictly typed to specific command classes rather than the base Command type. The CommandHandler base class now uses a TypeVar bound to Command, and the CommandBus class has been refactored to support asynchronous handling via a new handle\_async method that aggregates results from multiple handlers. Additionally, the internal registration of handlers has been simplified by removing the abstract commands() method in favor of direct attribute access.

_fractal/core/command\bus · high confidence

The generic specification classes—including CollectionSpecification, AndSpecification, OrSpecification, InSpecification, EqualsSpecification, LessThenSpecification, LessThenEqualSpecification, GreaterThenSpecification, GreaterThenEqualSpecification, and RegexStringMatchSpecification—have been removed from the fractal/core/specifications/generic directory. This change eliminates the in-place modification behavior of collection specifications and removes the And/Or helper methods from the base Specification class, likely as part of a broader refactoring to externalize these components.

fractal/core/specifications/generic · high confidence

The internal roles module located at fractal/contrib/roles has been removed. This includes the deletion of the Role model and the RolesService, which previously handled role verification logic. This change aligns with the migration of roles to external packages (fractal-roles) and requires users to update their code to use the new external dependencies.

fractal/contrib/roles · high confidence

The internal specification classes for account ID, ID, user ID, and object-of-account have been removed from the codebase. These classes, which previously resided in the \fractal/core/specifications\ directory, are no longer part of the core module.

fractal/core/specifications · high confidence

The in-memory repository implementations, including the base \Repository\ abstract class, \InMemoryRepositoryMixin\, and \ExternalDataInMemoryRepositoryMixin\, have been removed from the \fractal/core/repositories\ package. This change eliminates the ability to use in-memory storage for entities, likely shifting the application to rely on persistent database-backed repositories for data access.

fractal/core/repositories · high confidence

The Django integration has been refactored to use a new Django signal-based event projector (DjangoSignalEventProjector) that dispatches events via a custom Django signal, replacing the previous direct model field filtering approach. Additionally, the session middleware has been updated to manage data loading and dumping for in-memory repositories, and the old Django model repository and specification builder files have been removed.

fractal/contrib/django · medium confidence

The FastAPI installation logic has been updated to make Sentry integration optional and more secure. Sentry is now imported conditionally, and the SDK is only initialized if the SENTRY\_DSN is provided. Crucially, the default for send\_default\_pii is now False, preventing accidental leakage of personally identifiable information (PII) to Sentry unless explicitly enabled via the SENTRY\_SEND\_DEFAULT\_PII setting. Additionally, the app title, version, and OpenAPI documentation endpoints are now configurable via settings, and a generic exception handler has been added to return 500 errors in a consistent JSON format.

fractal/contrib/fastapi · high confidence

Added comprehensive test coverage for process actions; Added test coverage for core event sourcing and services; Added test fixture modules; Added test fixtures for FastAPI, SQLAlchemy, GCP, Mongo, roles, and tokens; Added test fixtures for core components; Added test infrastructure and configuration; Added tests for FastAPI contrib module; Added tests for async processing, dot notation, and specification builders; Added tests for the command bus and command handler; Added unit tests for core utility functions.

The project has migrated from a \setup.py\-based build to a \pyproject.toml\ configuration, establishing \fractal-toolkit\ as the distribution name and requiring external packages \fractal-repositories\, \fractal-roles\, \fractal-specifications\, and \fractal-tokens\. In the FastAPI component, \pyjwt\ has been replaced with \python-jose\, and \sentry-sdk\ has been removed. Additionally, new \requirements.txt\ files have been added for GCP Firestore, Pub/Sub, Kafka, and RabbitMQ integrations, while the MongoDB and Django dependencies have been removed or adjusted.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 53 → 58 (+5.8)
• Rubric changed (rubric-2026.08.19 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 99 → 98 (-0.6)
• Architecture 100 → 99 (-0.7)
• Maturity 61 → 61 (+0.0)
• Readiness 32 → 38 (+5.9)
• Security 59 → 81 (+21.5)
• Domain Modelling 100 → 100 (+0.0)

• Coverage not included — suite not readable by the collector
• Dependency hygiene not measured — dependency manifest found but not parsed for hygiene
• Duplicated block (21 lines × 2) (fractal/core/process/actions/init.py)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• No exposed public API
• Test reliability not included
• The Usage section mentions microservices with FastAPI/Docker but does not state which HTTP framework is recommended or how Docker integration works. (README.md)
• single-maintainer — knowledge-concentration (bus factor) risk

• Dependency hygiene PARTLY measured — Python dependencies read, no exact pin to grade for currency
• Documentation: no architecture or design documentation (README.md)
• Duplicated block (23 lines × 2) (fractal/core/process/actions/init.py)
• Duplicated block (8 lines × 2) (fractal/core/utils/application_context.py)
• High IaC: WD-COMPOSE-0002 (fractal/contrib/kafka/docker-compose.yml)
• High IaC: WD-COMPOSE-0002 (fractal/contrib/kafka/docker-compose.yml)
• High IaC: WD-COMPOSE-0002 (fractal/contrib/kafka/docker-compose.yml)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• No dependency advisory monitoring
• TodoComment (fractal/contrib/gcp/pubsub/event_bus.py)
• TodoComment (fractal/contrib/kafka/event_bus.py)
• …and 3 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

douwevandermeij/fractal was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.