Business Layer

🤖 Generated from code by scripts/generate-docs.mjs — do not hand-edit. Run orazaka docs build to refresh.

orazaka-business (repository orazaka-ai-engine) is the App Factory of the engine: the layer that decides what a request is for, never how a model answers it. Every request a client sends becomes one immutable Intention; the UseCaseDispatcher resolves it to the UseCase that serves its capability, checks the use-case's RBAC policy against the actor's authorities and runs it. A use-case coordinates the core's inbound ports (AiClient, the Studio run API…) and holds no model logic — that stays in orazaka-core and the interceptor pipeline.

Use-cases are not packs. A use-case is a technical entry point of the engine, written in Java. The business offers customers install — Studios, grouped in packs — are data: see Packs & Studios.

Where things liveCopy Anchor Link

Ports & adapters, the same layout in every Orazaka module: api is the contract other modules may import, application implements it, domain holds the model and the ports, and the use-cases are plain classes discovered by Spring — adding one changes neither the core nor the router.

The contractCopy Anchor Link

IntentionCopy Anchor Link

The immutable entry unit of the platform — the single thing the router translates transport into and hands to the UseCaseDispatcher.

IntentionContextCopy Anchor Link

Ambient context of an Intention: the conversation session, the acting principal (opaque actorId — no cross-context identity coupling), the actor's resolved authorities (for RBAC), and resolved preferences / environment signals.

UseCaseDescriptorCopy Anchor Link

Metadata describing a UseCase — the metadata-driven contract the UseCaseRegistry matches intentions against and the auto-docs surface.

UseCaseContextCopy Anchor Link

Execution context handed to a UseCase, derived by the dispatcher from the Intention and the resolved security context.

RbacPolicyCopy Anchor Link

RBAC requirement a UseCaseDescriptor declares: the authorities an actor must hold to run the use-case.

Use-casesCopy Anchor Link

The registry matches an intention to the first use-case whose descriptor serves its capability.

Dispatch refuses an intention with:

Entry pointsCopy Anchor Link

The adapters that hand work to the business layer:

Call it over HTTP through the edge with a session token (see the API reference):

curl -X POST http://localhost:8088/api/v1/intent \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"capability":"CHAT","prompt":"Summarise our refund policy in three bullet points."}'

Adding a use-caseCopy Anchor Link

A new product capability is one class: implement UseCase<I, R>, declare its UseCaseDescriptor (id, capability, personas, planning mode, required tools, RBAC) and register it as a bean — the registry discovers it. Personas are Markdown prompts read from classpath:prompts/<name>.md by MarkdownPromptResolver. The reference implementation, verbatim:

package com.krizaka.orazaka.business.usecases.chat;

/**
 * Reference use-case — a synchronous chat assistant. Demonstrates the App Factory contract: it
 * declares a {@link UseCaseDescriptor} (with a markdown {@code persona}), resolves the persona via
 * {@link MarkdownPromptResolver}, and orchestrates the core's {@link AiClient} inbound port. A new
 * product capability is added the same way — a new {@code UseCase} class — without touching the
 * core or the router.
 */
public final class ChatAssistantUseCase implements UseCase<ChatPayload, ChatResponse> {

  private static final UseCaseDescriptor DESCRIPTOR =
      new UseCaseDescriptor(
          "chat.assistant",
          Capability.CHAT,
          Set.of("personas/default-assistant"),
          PlanningMode.DETERMINISTIC,
          Set.of(),
          RbacPolicy.PERMIT_ALL);

  private final AiClient aiClient;
  private final MarkdownPromptResolver prompts;

  public ChatAssistantUseCase(AiClient aiClient, MarkdownPromptResolver prompts) {
    this.aiClient = Objects.requireNonNull(aiClient, "aiClient must not be null");
    this.prompts = Objects.requireNonNull(prompts, "prompts must not be null");
  }

  @Override
  public UseCaseDescriptor descriptor() {
    return DESCRIPTOR;
  }

  @Override
  public ChatResponse execute(UseCaseContext ctx, ChatPayload input) {
    Context coreContext =
        new Context(
            ctx.actorId() != null ? ctx.actorId() : "anonymous",
            ctx.sessionId() != null ? ctx.sessionId() : ctx.intentionId(),
            ctx.preferences(),
            Set.of());
    return aiClient.chat(new ChatRequest(input.prompt(), personaMessages(), Map.of(), coreContext));
  }

  /** Resolves each declared persona's markdown into a leading system message. */
  private List<ChatMessage> personaMessages() {
    return descriptor().personas().stream()
        .map(prompts::resolve)
        .flatMap(java.util.Optional::stream)
        .filter(content -> !content.isBlank())
        .map(content -> new ChatMessage("system", content))
        .toList();
  }
}

Product overview →