Optima.Net.Application 1.0.0

Optima.Net.Application

TL;DR (for people who hate READMEs)

Optima.Net.Application is the application-layer foundation of the Optima.Net ecosystem.

It defines contracts and orchestration boundaries, not implementations.

If you are looking for:

• where use cases live
• how transactions are coordinated
• how commands, queries, sagas, repositories, and events fit together

�this is that package.

No infrastructure. No EF. No Kafka. No magic.

Just contracts, patterns, and sharp edges.

---

What This Package Is

Optima.Net.Application defines the application layer in a Clean / Hexagonal / DDD-aligned architecture.

It sits between:

• the Domain layer (pure business rules)
• and Infrastructure (databases, message buses, frameworks)

This package:

• coordinates domain operations
• defines orchestration boundaries
• exposes extension points for infrastructure
• suggests safe patterns without enforcing them

It is intentionally boring.

---

What This Package Is NOT

This package does not:

• implement persistence
• implement messaging
• contain business rules
• contain validation frameworks
• contain logging, retries, or metrics
• enforce architectural dogma

If you are looking for "helpers that do everything for you" � this is not that.

---

Design Philosophy

Contracts Over Behavior

Everything in this package is either:

• an interface (a contract)
• or a small extension that coordinates contracts

No side effects are hidden.

---

Suggest, Don�t Enforce

Optima.Net.Application suggests patterns.

It does not mandate:

• transaction strategies
• event publishing strategies
• CQRS purity
• saga styles

You are free to compose, replace, or ignore helpers as needed.

---

Explicit Over Clever

If something happens:

• you should be able to see where
• you should be able to step through it
• you should be able to replace it

No ambient context. No async-local tricks.

---

Core Concepts

Commands

A command represents intent.

Examples:

• CreateOrder
• CancelOrder
• ApprovePayment

Commands:

• express what the caller wants
• do not contain behavior
• result in state change

---

Queries

A query retrieves data.

Queries:

• must be side-effect free
• must not mutate state
• must not participate in transactions

If something changes, it�s not a query.

---

Unit of Work

A Unit of Work defines a transactional boundary.

It:

• begins work
• commits durable state
• rolls back on failure

It knows nothing about events.

---

Events

Events are facts.

They:

• describe something that already happened
• are published after commit
• are not transactional

Publishing failures do not imply rollback.

---

Sagas

A saga coordinates long-running workflows.

It:

• reacts to events
• spans time
• may compensate

It is orchestration, not business logic.

---

Abstractions

IBaseCommandHandler

Represents a single application use case that mutates domain state.

public interface IBaseCommandHandler<in TCommand, TError>
{
    Task<Result<Unit, TError>> HandleAsync(
        TCommand command,
        CancellationToken ct = default);
}

Rules:

• one handler = one use case
• no business logic
• no persistence logic
• return Result, not exceptions

---

IBaseQueryHandler

Represents a read-only use case.

public interface IBaseQueryHandler<in TQuery, TResult, TError>
{
    Task<Result<TResult, TError>> HandleAsync(
        TQuery query,
        CancellationToken ct = default);
}

Rules:

• no state mutation
• no UnitOfWork
• no events

---

IBaseRepository

Minimal persistence contract for aggregates.

public interface IBaseRepository<TAggregate, TId>
{
    Task<Optional<TAggregate>> GetByIdAsync(TId id, CancellationToken ct = default);
    Task SaveAsync(TAggregate aggregate, CancellationToken ct = default);
}

This is an application-layer port.

Infrastructure implements it.

---

IUnitOfWork

Defines transactional boundaries.

public interface IUnitOfWork
{
    Task BeginAsync(CancellationToken ct = default);
    Task CommitAsync(CancellationToken ct = default);
    Task RollbackAsync(CancellationToken ct = default);
}

The Unit of Work owns all rollback logic.

---

IEventPublisher

Outbound port for publishing events.

public interface IEventPublisher
{
    Task PublishAsync<TEvent>(TEvent evt, CancellationToken ct = default)
        where TEvent : class;
}

Delivery guarantees are an infrastructure concern.

---

Sagas

public interface IBaseSaga
{
    Guid Id { get; }
    bool IsCompleted { get; }
    Task HandleAsync(object evt, CancellationToken ct = default);
}

public interface IBaseCompensatableSaga : IBaseSaga
{
    Task CompensateAsync(CancellationToken ct = default);
}

Compensation is best-effort.

---

Extensions

Extensions are helpers, not mandates.

You may use them or ignore them.

---

UnitOfWorkExtensions

Coordinates Begin / Commit / Rollback.

await unitOfWork.ExecuteAsync(async ct =>
{
    // application logic
    return Result.Success<Unit, Error>(Unit.Value);
});

Behavior:

• success ? commit
• failure ? rollback
• exception ? rollback + rethrow

---

CommandHandlerExtensions

Executes a command handler inside a Unit of Work.

await handler.ExecuteAsync(command, unitOfWork, ct);

Pure orchestration. No magic.

---

QueryHandlerExtensions

Normalizes query execution.

await handler.ExecuteAsync(query, ct);

No transactions. No side effects.

---

Event Publishing After Commit (Suggested Pattern)

A commonly useful pattern:

1. execute domain changes inside a Unit of Work
2. commit
3. publish events

This package provides helpers that make this easy, but does not enforce it.

Publishing is:

• post-commit
• best-effort
• non-transactional

---

Error Handling Philosophy

• Expected failures are values (Result<T, TError>)
• Unexpected failures are exceptions

Do not throw for business rejection.

---

Extension, Not Inheritance

Interfaces prefixed with IBase* are framework-owned.

Consumers are expected to:

public interface ICreateOrderHandler
    : IBaseCommandHandler<CreateOrder, OrderError>
{
}

This keeps ownership clear.

---

Final Notes

This package exists to make good architecture easy and bad architecture obvious.

If you need more examples, see the Optima.Net.TestHarnesses project on GitHub. Test harness availability is guaranteed, though not necessarily at release time � check back occasionally and it will appear.

---

Happy building.