Forze
Forze is a Python framework for Domain-Driven Design and Hexagonal Architecture in backend
services. This skill is a routing index: the reference files under references/ hold the actual
material, and you read the ones a task needs.
The mental model, in four sentences
Your application declares logical specs — a DocumentSpec, a QueueSpec, a StorageSpec —
that name a resource without naming any physical thing. Deps modules map those names to real
backends (a Postgres table, an SQS queue, an S3 bucket) at wiring time. Handlers receive an
ExecutionContext and reach infrastructure only through ports resolved from it. The runtime
composes the registries, freezes them, and runs operations through the pipeline.
Everything else is a consequence of that split. If a handler mentions a table name, a bucket, or
an adapter import, something has gone wrong — and most anti-patterns in these references are a
version of that one mistake.
Read the bundle, not one file
Most tasks need three to five references, and reading one is usually wrong. These are
procedures, not independent rules: an aggregate declared without its backend config is an app
that does not start, and a handler written without the execution context is a handler that
reaches for the wrong things. Start from the table below and read the whole row.
| I want to… |
Read, in order |
| Bootstrap a new service |
architecture → spec-naming-and-routes → deps-resolution → runtime-lifecycle → connection-settings |
| Add a governed aggregate |
aggregate-models → document-spec → aggregate-kit → spec-to-backend-config → testing-with-mock |
| Write a custom handler |
execution-context → handlers → query-dsl |
| Expose it over HTTP |
fastapi-setup → fastapi-generated-routes → fastapi-identity |
| Encrypt a field |
field-encryption → kms-backends → spec-to-backend-config |
| Simulate my service under faults |
dst-simulation → dst-invariants → testing-with-mock |
If the task is not one of these, pick from the index below — but check whether it decomposes into
a row first.
Index
Foundations
| Reference |
Covers |
| architecture |
Layered architecture, contracts and adapters, what may import what |
| execution-context |
ExecutionContext, the ports on it, transactions, identity and tenancy in a handler |
| handlers |
Handler patterns for the common operation shapes, and the gotchas |
Specs, deps and wiring
| Reference |
Covers |
| spec-naming-and-routes |
StrEnum spec names, transaction routes, why one name is one route |
| spec-to-backend-config |
Mapping a logical name to Postgres, Mongo, Redis, storage, queue and workflow config |
| deps-resolution |
Plain vs routed deps, how handlers resolve ports, merge conflicts |
| deps-custom-module |
Writing your own DepsModule and DepKey for a private integration |
| runtime-lifecycle |
build_runtime, lifecycle steps, the spec inventory |
| connection-settings |
<Backend>Settings models — endpoints, credentials and client knobs from the environment |
| operation-composition |
Operation registries, pipeline stages, hooks, mapping steps |
| testing-with-mock |
forze_mock in tests — every port in memory, no containers |
| sandbox-execution |
Running a program out of process — provenance, isolation tiers, ceilings, streaming |
Domain
| Reference |
Covers |
| aggregate-models |
The four models, base fields, mixins, update validators |
| document-spec |
DocumentSpec / SearchSpec, schema alignment, composition DTOs |
| aggregate-kit |
AggregateKit — one declaration for a governed vertical slice |
Reading and writing data
| Reference |
Covers |
| document-facade |
DocumentFacade, raw ports, adapter boundaries, cache-aware reads |
| query-dsl |
Filters, sorts, projections, cursor paging |
| search |
SearchFacade, hub and federated search, rebuilding an index |
Events, messaging and realtime
Durable execution
| Reference |
Covers |
| temporal |
DurableWorkflowSpec, Temporal deps, schedules, worker context |
| inngest |
Inngest events, functions, steps, serving; the self-hosted Postgres runner |
Interface
| Reference |
Covers |
| fastapi-setup |
Context dependency, lifespan, middleware, error handlers |
| fastapi-generated-routes |
attach_*_routes, hand-written routes, deadline headers, MCP projection |
| fastapi-identity |
Binding identity at the boundary, cookie mode, principal eligibility |
Identity, tenancy and secrets
| Reference |
Covers |
| authn |
Boundary binding, the verify-then-resolve pipeline, authn deps, authz |
| oidc |
External IdPs, token verifiers, principal resolution |
| tenancy |
Tenant identity, routed clients, isolation tiers, the admin plane, provisioning |
| secrets |
Secret-backed configuration and its backends |
Encryption
| Reference |
Covers |
| field-encryption |
FieldEncryption, what gets sealed, strict mode after backfill |
| kms-backends |
Vault and cloud KMS, per-tenant keys (BYOK), rotation vs replacement |
Other planes
| Reference |
Covers |
| object-storage |
StorageSpec, S3 and GCS, tenant-aware buckets, presigned and multipart |
| http-outbound |
Declarative outbound HTTP integrations, auth, tenant routing |
| analytics |
AnalyticsSpec, named SQL templates, BigQuery and ClickHouse |
| graph |
Node and edge specs, traversal ports, Neo4j |
| inference |
InferenceSpec, local / HTTP / SageMaker backends, capabilities |
Testing under faults
| Reference |
Covers |
| dst-simulation |
Declaring a simulation over your own operations, schedulers, fault and latency injection |
| dst-invariants |
Invariants, reachability targets, reading a ViolationReport |
Running in production
| Reference |
Covers |
| errors |
CoreException, adapter exception mapping, FastAPI error responses |
| logging-metrics |
Structured logging, call context, operation and resilience metrics |
| resilience |
Retry, breaker, bulkhead, rate limit, hedging; invocation deadlines |
| shutdown-fleet |
Graceful drain, quiesce, readiness, fleet posture across replicas |
Reference
Docs are versioned. These links use latest (the newest release). If your app pins an older
forze minor, replace latest in the URL with that version (e.g. .../forze/0.6/...), or use
the version selector on the site.
