Introduction & Quickstart
Relevant source files
The following files were used as context for generating this wiki page:
Forze is an infrastructure toolkit designed for building backend services using Domain-Driven Design (DDD) and Hexagonal Architecture principles. It provides a comprehensive set of reusable primitives, contracts, and structural patterns that facilitate the organization of backend applications into distinct, maintainable layers. The library focuses on establishing clear boundaries between domain logic, application orchestration, and infrastructure implementations.
The primary objective of Forze is to enable systems that are explicitly layered, highly testable, and framework-agnostic. While it provides deep integrations with popular tools like FastAPI, Postgres, and Redis, its core remains independent of specific frameworks. This allows developers to compose and replace infrastructure components as needed without impacting the underlying business logic.
Sources: README.md:16-29, AGENTS.md:7-11
Project Architecture & Layers
Forze enforces a strict dependency flow where dependencies always point inward toward the core business logic.
Structural Layers
The project is organized into four primary architectural layers:
| Layer | Responsibility | Dependencies |
|---|---|---|
| Domain | Pure business logic, entities, and invariants. | None |
| Application | Handlers, contracts, and orchestration logic. | Domain |
| Infrastructure | Adapters implementing contracts (e.g., Database, S3). | Application |
| Interface | Boundary entry points (e.g., HTTP, WebSockets). | Application (via Registry) |
Sources: skills/forze-framework-usage/SKILL.md:15-24, AGENTS.md:57-78
Dependency Flow Diagram
The following diagram illustrates how components interact and how the ExecutionContext bridges logical needs with physical implementations.
The interface layer dispatches requests through an OperationRegistry, which executes Handlers. These handlers resolve necessary ports (e.g., DocumentQueryPort) from the ExecutionContext, which is backed by a DepsRegistry.
Sources: skills/forze-wiring/SKILL.md:14-43, skills/forze-framework-usage/SKILL.md:37-56
Quickstart Guide
Installation
Forze is installed via the core package, with optional extras available for specific integrations.
# Core installation
uv add forze
# Installation with common integrations
uv add 'forze[fastapi,postgres,socketio]'
Sources: README.md:31-39, pyproject.toml:68-120
Core Components Setup
Setting up a Forze application involves three primary "Execution Plans":
- DepsRegistry: Maps logical specs to physical infrastructure configurations.
- LifecyclePlan: Manages the startup and shutdown sequences of external connections (e.g., DB pools).
- OperationRegistry: Registers handlers and binds them to execution stages (e.g., transactions).
Sources: skills/forze-wiring/SKILL.md:10-12
Initializing the Runtime
The ExecutionRuntime assembles the frozen plans into a runnable system.
from forze.application.execution import DepsRegistry, ExecutionRuntime, LifecyclePlan
# 1. Create registries
deps_registry = DepsRegistry.from_modules(...)
lifecycle_plan = LifecyclePlan.from_modules(...)
# 2. Build runtime from frozen plans
runtime = ExecutionRuntime(
deps=deps_registry.freeze(),
lifecycle=lifecycle_plan.freeze(),
)
# 3. Use within a scope
async with runtime.scope():
ctx = runtime.get_context()
Sources: skills/forze-wiring/SKILL.md:45-81
Key Concepts & Execution
ExecutionContext
The ExecutionContext is the primary interface for handlers to interact with infrastructure. It provides namespaced accessors for different port types.
| API Accessor | Returns | Purpose |
|---|---|---|
ctx.document.query(spec) | DocumentQueryPort | Reading documents and listings |
ctx.document.command(spec) | DocumentCommandPort | Creating, updating, and deleting |
ctx.cache(spec) | CachePort | Interacting with cache backends |
ctx.tx_ctx.scope(route) | Async Context Manager | Managing transaction boundaries |
Sources: skills/forze-framework-usage/SKILL.md:37-53
Logical Specs vs. Infrastructure Config
A critical distinction in Forze is the separation of logical specs (which live in the Application layer) from integration configs (which live in the Infrastructure layer).
DocumentSpec defines the models and a logical name (e.g., "projects"). The PostgresDepsModule uses that name to map the spec to a physical database table.
Sources: skills/forze-specs-infrastructure/SKILL.md:16-52, skills/forze-wiring/SKILL.md:18-35
FastAPI Integration
Forze connects to FastAPI through generated routes and context dependencies. The runtime scope is typically managed within the FastAPI lifespan.
from fastapi import FastAPI, Depends
from contextlib import asynccontextmanager
@asynccontextmanager
async def lifespan(app: FastAPI):
async with runtime.scope():
yield
app = FastAPI(lifespan=lifespan)
def get_ctx():
return runtime.get_context()
@app.get("/items/{id}")
async def read_item(id: str, ctx=Depends(get_ctx)):
return await ctx.document.query(item_spec).get(id)
Sources: skills/forze-fastapi-interface/SKILL.md:17-30, skills/forze-wiring/SKILL.md:160-176
Summary
Forze provides a structured way to build backend services by enforcing architectural boundaries through explicit contracts and dependency injection. By separating logical specifications from infrastructure implementations and using a centralized ExecutionContext, Forze ensures that application code remains testable and decoupled from specific backend technologies. Developers can quickly start by defining their domain models, mapping them to infrastructure modules, and exposing them via the provided FastAPI or MCP interface layers.