Use Case Pattern

An optional layer — for those who want to understand the engine. The courses and learning programs run on this methodology, but you don't need to start here. Open this section when you want to understand what is under the hood of a product and how to apply the method yourself.

Use Case Pattern is a methodology, not a library. Four components:

1. The pattern itself. UseCase + Handler + Dispatcher — a single way to describe business operations in code.
2. Specification. A universal template for what must be described about a service; stored in git as code.
3. Three maturity levels. How the pattern and the specification grow as the service grows — from a layered MVP to DDD with dozens of integrations.
4. The end-to-end case. A business description of a marketplace, against which the pattern, the specification, and the maturity levels are all tested. Without it, the methodology stays theory.

The skills for AI agents work with all four — they're a tool, not a separate component.

Contract and bindings

All four components are language-neutral — that's the methodology's contract. The implementation for a specific stack is provided by language bindings: the same rules, the same codes, their own idioms. The second axis is specialization: backend (the main track), frontend (React + TypeScript, a scaffold), e2e (reserved).

Binding	Stack	Status
Java	Spring Boot, jOOQ, reference libraries	ready — articles in the Standards
Python	FastAPI, SQLAlchemy, Pydantic	ready — style guide and ucp-py-* skills in the skills repo
Node	NestJS, TypeORM, class-validator	ready — style guide and ucp-node-* skills in the skills repo
Go	net/http + chi, sqlc	in progress

The rule is the same on any stack: R-UC-1 means "one UseCase — one business operation" in Java, in Python, and in Node alike — only how it looks in code changes. That's why a team on any of these stacks reads the same contracts, and the AI skills check the same rule codes.

---

1. The pattern itself

Every business operation is a separate UseCase and a separate UseCaseHandler. Between the input (HTTP, queue, cron) and the output (the database, external APIs) runs a UseCaseDispatcher that matches them by type.

The essentials:

• One UseCase — one business operation. CreateOrder, ConfirmPayment, GetOrderById. No "universal services".
• Controllers, queue handlers, and cron are different inbound adapters to the same UseCase.
• Layers don't mix data models. Between them — explicit mapping.

The pattern is language-neutral. For Java there's a ready-made library, usecase-pattern; in the Python and Node bindings the pattern is assembled by hand from lightweight interfaces — exactly how is described by the binding guides in the skills repo.

---

2. Specification as code

At the core of the methodology lies a simple rule: the specification is code. Not a Word document, not a Confluence page, not a PDF from an analyst. A Markdown file in the same repository as the service's code.

What follows from this:

• The spec lives in git next to the code and goes through PR review like any commit.
• The change history is visible in git log — who changed a rule, when, and why.
• The format is structured: 16 sections with headings, tables, and lists. Both people and tools read it — linters, code generators, AI agents.
• Contracts are derived, not duplicated: OpenAPI comes out of the "Commands" section, AsyncAPI out of "Domain Events", aggregate scaffolds out of "Domain Model".
• The spec and the code must match. A discrepancy is a bug, not "we'll fix it later".

The depth of the spec = the service's maturity level (a single axis, 0–3), which the spec declares via the level field in the frontmatter:

• Level 0 — As-is. The spec is reconstructed from existing code without a business brief (ucp-spec-tier-0): a snapshot of "how it is now", with not-declared for the gaps. A starting point for migration.
• Level 1 — Layered. A minimal spec from a business brief: glossary, ER diagram, operations, rules. No aggregates or events.
• Level 2 — Use Case Pattern. UseCases and command/query cards are added; CQRS + Read Model is optional.
• Level 3 — DDD + Hexagonal. Full depth: aggregates, value objects, domain events, sagas, contracts on the edges.

→ Use Case specification: the universal template + 9 role guides (BA, architect, developer, QA, DevOps, security, designer, maintenance, AI agent).

Spec → AI agents

Because the specification is structured code, automation tools apply to it. For every article on the site there's a Claude Code skill that reads the spec and:

• generates API contracts from the "Commands" section (ucp-api-design);
• generates aggregates and events from "Domain Model" (ucp-ddd-tactical-design);
• generates UseCase + Handler from "Use Cases" (ucp-pattern-design);
• checks the code against the spec's rules (ucp-pattern-review, ucp-ddd-tactical-review).

There are skills for every binding: ucp-* — Java, ucp-py-* — Python, ucp-node-* — Node. The installer sets up the slice for the team's language and specialization (UCP_LANG × UCP_TRACK).

An article with an attached skill shows a yellow badger on the site. Articles with a reference library get a green one. With a reference example project — blue. All skills are in github.com/remodov/usecase-pattern-skills.

---

3. Maturity levels

The methodology is a ladder. Each next level adds an answer to a problem the previous one can no longer handle. You move up when there's a reason, not "because it's fashionable". The level is a single axis; the spec declares it via the level field.

Level 0 — As-is

The spec is reconstructed from existing code without a business brief (ucp-spec-tier-0) — a snapshot of "how it is now". Not a place to live, but a starting point. When to use: a brownfield service in production without a spec, onboarding, before a migration. When to leave: right after onboarding — you replace not-declared with business facts and design the target level.

Level 1 — Layered

Classic layered architecture (Controller → Service → Repository), without usecase-pattern. The base rung. When to use: CRUD, thin business logic, an MVP, an internal tool. When to leave: when operations in service classes become indistinguishable and you need per-operation metrics/audit.

Level 2 — Use Case Pattern

Every business operation is a separate UseCase and handler; one shared route, per-operation metrics. CQRS (commands/queries + a Read Model) is an option at this level, when reads and writes diverge in load. When to use: a noticeable number of operations, you need structure. When to leave: when there are so many business rules that they "spread out" across handlers.

Level 3 — DDD + Hexagonal

An explicit domain model (aggregates, value objects, domain events) + infrastructure isolation via ports and adapters, with boundary checks by ArchUnit. Business logic lives in the domain, infrastructure is swappable. When to use: complex invariants, the language matters, boundaries (Bounded Contexts) are carved out, dozens of integrations, a long lifespan.

A hint for choosing

What's in the project	Level
CRUD, thin business logic, an MVP	1
A noticeable number of operations; different load on reads and writes	2
Complex invariants, a domain language, many integrations, isolation from infrastructure	3

Within one service, different modules can live at different levels: the business core at level 3, reference data at level 1. That's normal and often more worthwhile than "everything at level 3 for uniformity". As-is from existing code — Level 0.

---

4. The end-to-end case

The methodology stays theory until it's grounded in a concrete business. That's why it comes with an end-to-end case — a marketplace: a business description in the "how I understood the task" format, without architectural terms.

The case is an equal part of the methodology:

• A starting point for every new service. Before the spec and the code — the text about the business. If the business isn't articulated, there's no point going further.
• A reference for the skills. The business description is run through the skills (/api-design, /ddd-tactical-design, /usecase-pattern-design), and from it API contracts, aggregates, and UseCases are generated — we see that the methodology works.
• A shared coordinate system for all the site's articles. DDD, CQRS, Saga, Resilience4j, OAuth2 — everything is examined on the same case. No need to invent a new domain each time.

→ Case: a marketplace — the business description: stakeholders, glossary, processes, rules, errors, target volumes.

From this text the skills derive the artifacts for each service of the case. Already covered:

• Service map — service boundaries and their links.
• Notification Service — notifications driven by order events.
• Catalog Service and its walkthrough — the catalog: design and the path from description to code.
• Order Service — orders, disputes and refunds.

The remaining services (Customer BFF, Payment, Inventory) will follow as the case grows.

---

The main rules

Six principles common to all maturity levels. The technical details are in the specialized articles linked below.

1. One UseCase — one business operation. No "universal services".
2. Layers don't mix data models. The API model ≠ the domain model ≠ the storage model.
3. External dependencies sit behind interfaces. The payment gateway, the bus, sending SMS — all through ports.
4. One business operation — one transaction. All or nothing.
5. Events are published atomically with the write. No "wrote it, but the event never arrived".
6. Idempotency is mandatory where it makes sense — payments, order creation, redelivered messages.

---

Site map

Every layer builds on established practices. The site is a methodical breakdown of each of them.

Controller / inbound adapter

• REST API Style Guide — URLs, resources, headers, RFC 9457 errors, OpenAPI.
• Authorization patterns — OAuth2, JWT, RBAC, ABAC.
• Structural microservice patterns — API Gateway, BFF, Service Discovery.

UseCase + Handler (business logic)

• What DDD is — the boundaries and language of the domain.
• Tactical DDD patterns — Entity, Value Object, Domain Event.
• Strategic DDD patterns — Bounded Context.
• CQRS — the natural split of a UseCase into Command and Query.
• Hexagonal architecture — Core ↔ Adapters.
• Distributed patterns — Saga, Outbox, idempotency.

Outbound adapter / data

• Apache Kafka — topics, partitions, delivery guarantees.
• Distributed patterns — Outbox + polling relay, Event Sourcing, Idempotent Consumer.

Cross-cutting

• Resilience patterns — Retry, Circuit Breaker, Timeout, Bulkhead, Fallback, DLQ.
• Authorization patterns — RBAC at the Gateway, ABAC inside the Handler.

Architecture and design

• Choosing the initial architecture — monolith or microservices.
• The C4 Model — how to describe a system.
• Case: a marketplace — the site's end-to-end business domain.

Specification and team

• Use Case specification: the universal template — the context root + a file per domain unit, domain without technology, a minimal frontmatter with level.
• Level 0 — As-is from code — reverse-engineering an existing service as a starting point for migration.

---

Next

• A ready-made starter: The usecase-pattern library — UseCase / UseCaseHandler / UseCaseDispatcher + Spring Boot auto-configuration + metrics.
• A spec template: Use Case specification.
• AI agent skills: github.com/remodov/usecase-pattern-skills.
• The site's business case: A marketplace.
• The methodology and AI: why a methodology when AI writes the code · the AI-native company · the executable standard — rules the agent applies on every PR.
• Compared with other approaches: UCP vs BMAD-METHOD — roles and a delivery loop versus a domain spec and standards · UCP vs spec-driven tools — OpenSpec, Spec Kit and Kiro: a spec of a change versus a spec of a system.
• Tool setup: Claude Code for UCP.