Forze Kits: Standard Aggregates
Relevant source files
The following files were used as context for generating this wiki page:
Forze Kits provide a pre-built layer of wiring and logic above core Forze contracts, specifically designed to streamline the implementation of common Domain-Driven Design (DDD) patterns. These kits include domain field mixins, aggregate registries, default handlers, and runtime ergonomics that facilitate the management of persistent entities and searchable data structures within a Hexagonal Architecture.
The primary goal of these kits is to offer a standardized way to define and interact with "Aggregates"—clusters of domain objects that can be treated as a single unit for data changes. Within Forze, this is primarily realized through the aggregates subpackage, which handles standard operations for documents, search, storage, and authentication.
Sources: src/forze_kits/README.md:1-10, skills/forze-domain-aggregates/SKILL.md:1-10
Aggregate Architecture and Models
Forze defines a standard structure for document-based aggregates, ensuring consistency across the application layer. Every document aggregate typically consists of four distinct model types to separate concerns between business logic, data entry, and data projection.
Core Model Types
| Model Type | Base Class | Purpose |
|---|---|---|
| Domain Model | Document | The central entity containing business logic, invariants, and validation. |
| Create Command | CreateDocumentCmd | A DTO used as input for creating a new aggregate instance. |
| Update Command | BaseDTO | A DTO representing partial update payloads (patches). |
| Read Model | ReadDocument | A frozen, read-only projection optimized for queries and API responses. |
Sources: skills/forze-domain-aggregates/SKILL.md:16-30
Domain Mixins and Field Kits
Standard aggregates leverage mixins to inject common behaviors and audit fields without duplicating code:
- SoftDeletionMixin: Adds
is_deletedfunctionality for logical deletions. - NumberIdMixin: Provides human-readable IDs (
number_id). - CreatorIdMixin: Adds audit fields for tracking the creator (
creator_id). - MetadataMixin: Injects naming fields such as
display_name.
Sources: skills/forze-domain-aggregates/SKILL.md:46-55, src/forze_kits/README.md:12-15
Document Operations and Registries
The forze_kits.aggregates.document module provides the machinery to wire these models into the application's execution engine. The OperationRegistry is used to bind standard CRUD (Create, Read, Update, Delete) operations to specific handlers.
Operation Lifecycle
Operations are organized into stages within a pipeline. The standard lifecycle includes outer hooks for authorization or logging, followed by a transaction scope for persistent changes.
The diagram above shows the standard stage order for aggregate operations, including transaction management and side effects.
Sources: skills/forze-wiring/SKILL.md:144-150
Building a Document Registry
A document registry is constructed using build_document_registry. This factory automates the registration of standard handlers (Get, List, Create, Update, Delete) based on the provided DocumentSpec and DocumentDTOs.
registry = (
build_document_registry(project_spec, project_dtos)
.bind(*write_ops)
.bind_tx()
.set_route("default")
.finish(deep=True)
.freeze()
)
Sources: skills/forze-wiring/SKILL.md:112-132
Logical Specifications (Specs)
Aggregates are defined through logical specifications that remain decoupled from physical infrastructure.
DocumentSpec
Binds model types to a logical name. It does not contain database table names; those are defined in integration configurations (e.g., PostgresDepsModule).
- name: Logical route ID (often a
StrEnum). - read: The read model class.
- write: A mapping containing the domain model, create command, and update command.
- cache: Optional
CacheSpecfor read-through caching.
Sources: skills/forze-domain-aggregates/SKILL.md:68-100
SearchSpec
Separated from the document spec to allow specialized search configurations (FTS, Vector, etc.). It defines searchable fields and their default weights.
Sources: skills/forze-domain-aggregates/SKILL.md:106-114, skills/forze-documents-search/SKILL.md:64-75
Interface Integration
The kits allow for the automatic projection of aggregate registries onto API frameworks, specifically FastAPI.
Generated Routes
forze_fastapi.routes can automatically generate endpoints from a frozen aggregate registry.
- REST Style: Uses path-based IDs (e.g.,
GET /projects/{id}). - RPC Style: Uses operation-named paths with query parameters (e.g.,
GET /projects/get?id=).
Sources: skills/forze-fastapi-interface/SKILL.md:27-48
Summary
Forze Kits: Standard Aggregates provide a robust, boilerplate-free method for implementing the DDD aggregate pattern. By utilizing standard model types, mixins, and automated operation registries, developers can focus on domain logic while the framework handles transaction management, persistence wiring, and API exposure. The decoupling of logical "Specs" from physical "Infrastructure Configs" ensures that the core domain remains pure and highly testable.
Sources: src/forze_kits/README.md:1-25, skills/forze-wiring/SKILL.md:300-310