Python infrastructure for serious application design

The standard runtime for application use cases.

Your API layer is standardized. Your data layer is standardized. Your service layer is still where the chaos lives.

UseCaseCore gives business actions one explicit, typed, transactional execution model — across validation, state loading, policy checks, transitions, audit, idempotency, events, and side effects.

Get started Read the docs View GitHub

pip install usecasecore Typed commands Transactional execution Audit + idempotency

The missing middle

architecture runtime-shape

FastAPI
  ↓
Command model
  ↓
UseCaseCore
  ↓
Repositories / Session
  ↓
SQLModel / SQLAlchemy
  ↓
Postgres

Alembic evolves schema

1 execution shell for each business action

Typed commands, results, and repository boundaries

Explicit transactions, audit, events, and side effects

FastAPI Pydantic SQLModel SQLAlchemy Postgres Alembic Oso pytransitions Temporal Camunda

Core value

Standardize the most important layer in your application.

UseCaseCore does not replace your API framework, ORM, database, or workflow tools. It standardizes the execution boundary where business actions actually happen.

⌘

Explicit use cases

Every business action becomes a first-class unit with a typed command, a clear execution path, and a typed result.

⇄

Transactional truth

Authoritative changes happen inside a visible transaction boundary, not across scattered helpers and side effects.

◎

Idempotency

Retries stay safe. The same action can be handled once without duplicating writes or downstream effects.

▤

Audit by default

Every state-changing action can leave a structured trace of who did what, when, and why.

⚑

Event and job hooks

Emit domain events and queue side effects consistently after truth has been updated.

▣

Adapter-friendly

Plug in policy engines, state machines, workflows, queues, and event buses without changing the core use-case model.

Execution model

One predictable path from intent to committed truth.

Every use case follows the same operational grammar. That makes the system easier to understand, easier to test, and easier to evolve.

Receive command

Validated input arrives as a typed command from an API, job, or internal caller.

Load state

Repositories load the exact state the action depends on, including locking when needed.

Check policy and transitions

Authorization, lifecycle rules, and domain conditions are evaluated in one place.

Apply changes

Authoritative writes happen inside a visible transaction boundary with commit or rollback.

Audit and side effects

Write audit, emit events, and queue follow-up jobs after truth has been updated.

Concrete example

A request like MoveInventory is simple until it isn’t.

A move looks trivial at the UI level. In reality it needs validation, current-state reads, permission checks, transaction boundaries, audit, and safe side effects.

Flow	What actually happens
MoveInventoryCommand	Intent enters the system as a typed command instead of becoming route glue.
Load source + destination balances	Repositories fetch current state, including locking and consistency rules where needed.
Check permission + invariants	Policy, state transition rules, and domain conditions are enforced in one boundary.
Open transaction	Apply authoritative balance changes, write movement history, then commit or rollback.
Write audit + emit events + queue jobs	Side effects become explicit and repeatable instead of being mixed into handler code.
MoveInventoryResult	The action returns a typed result instead of an ad hoc response assembled on the fly.

Architecture

Fits into the stack you already use.

UseCaseCore is not a replacement for FastAPI, SQLModel, SQLAlchemy, Postgres, or Alembic. It is the runtime layer between validated input and committed writes.

FastAPI Routes and dependency injection

API layer

↓

Command models Pydantic / SQLModel typed input and output

Validation

↓

UseCaseCore Use cases, transactions, audit, idempotency, events, and jobs

Service runtime

↓

Repositories / Session SQLModel / SQLAlchemy persistence boundaries

Persistence

↓

Postgres + Alembic Source of truth and schema evolution

Storage

Predictable use-case skeleton

python usecases/base.py

class UseCase:
    def execute(self, command):
        self.validate(command)
        self.check_idempotency(command)

        state = self.load_state(command)
        self.check_policies(command, state)
        self.check_transitions(command, state)

        with self.transaction():
            result = self.apply(command, state)
            self.write_audit(command, state, result)
            self.emit_events(command, state, result)
            self.enqueue_jobs(command, state, result)

        return result

Integrations

Works with the tools real teams already use.

Keep the use case as the center of execution while exposing clean integration surfaces for policies, transitions, workflows, events, and job systems.

FastAPI

Receive validated commands from routes and dependency-injected services.

SQLModel

Use typed models naturally without collapsing business actions into table definitions.

SQLAlchemy

Keep direct control over sessions, transactions, queries, and locking.

Postgres

Preserve the database as the authoritative store of truth.

Alembic

Schema evolution stays independent while runtime behavior becomes standardized.

Oso

Plug in policy and authorization logic without leaking it across routes and helpers.

pytransitions

Handle lifecycle-heavy domains with explicit transition adapters.

Temporal

Bridge long-running orchestration into the same application action model.

Why this matters

Most teams already have the tools. They do not have the runtime model.

The missing standard is not another ORM, API framework, or queue. It is the layer that turns intent into safe, explicit, committed business actions.

Concern	Typical Python app	With UseCaseCore
Business action boundaries	ScatteredRoutes, helpers, model methods, jobs, and one-off service code	ExplicitEach action has one typed command, one execution boundary, one result
Transaction semantics	InconsistentOften mixed with side effects or hidden inside utility layers	IntentionalCommit / rollback behavior is explicit and reusable
Auditability	Bolted onAdded later, partial, or easy to forget	Built inActor, request, and state-change context become first-class
Idempotency	Custom every timeOften absent or inconsistent across endpoints and jobs	StandardizedRetries and duplicate handling follow one predictable pattern
Policy / workflow integration	LeakyFramework-specific logic bleeds into unrelated app code	Adapter-basedPlug in policy, transition, queue, and workflow tools cleanly

Getting started

Start with the model. Then ship one real use case.

The fastest path to value is not more framework theory. It is one concrete business action implemented correctly with a reusable execution shape.

Learn the core abstractions

Commands, results, repositories, transactions, audit hooks, idempotency, and adapters.

Implement one canonical action

Start with something real like MoveInventory, ReserveInventory, or CreateOrder.

Expand only where needed

Add policy engines, transitions, queues, or workflows only when the domain actually justifies them.

Build cleaner application brains.

Make business actions explicit, transactional, auditable, idempotent, and integration-friendly — without replacing the stack you already trust.

Read the docs View GitHub Contact