Open Kortyx on GitHub

Project Structure

Updated 6 hours ago • May 22, 2026

Folder names are flexible. The important part is the boundary between server-only Kortyx execution, client UI, and app-owned business code.

Responsibility Boundaries

AreaOwns
Server-only Kortyx modulescreateAgent(...), provider setup, workflows, nodes, runtime persistence
Client UI@kortyx/react, chat components, transport setup, stream-piece rendering
App-owned servicesauth, rate limits, business database writes, durable conversation history, domain APIs

Do not import server-only Kortyx runtime modules into client components. Keep provider credentials and runtime persistence adapters on the server.

Suggested Next.js Layout

src/ app/ api/chat/route.ts page.tsx components/ chat/ chat-window.tsx assistant-live-message.tsx lib/ kortyx-client.ts providers.ts nodes/ chat.node.ts classify.node.ts workflows/ general-chat.workflow.ts services/ auth.ts conversations.ts schemas/ chat.ts

Use this as a baseline, not a migration requirement. In existing apps, map each responsibility into the nearest existing folder.

Suggested React Plus Node Layout

apps/ web/ src/ components/ chat/ lib/ kortyx-transport.ts routes/ api/ src/ routes/ chat.ts lib/ kortyx-client.ts providers.ts nodes/ workflows/ services/ schemas/

Rules

  • Put createAgent(...) in a server-only module.
  • Use built-in provider refs such as google(...) directly when default environment-variable setup is enough.
  • Put explicit provider factories or custom transport settings in a server-only module.
  • Put workflow topology in workflow files.
  • Put executable node logic in node files.
  • Put database writes, auth, billing checks, and domain APIs in app services.
  • Put durable product records in your app database, not Kortyx runtime state.
  • Put short-lived interrupt/resume execution state in Kortyx runtime persistence.

Example Server Boundary

src/lib/kortyx-client.ts
import { createAgent } from "kortyx"; import { createFrameworkAdapterFromEnv } from "kortyx"; import { generalChatWorkflow } from "@/workflows/general-chat.workflow"; export const agent = createAgent({ workflows: [generalChatWorkflow], defaultWorkflowId: "general-chat", frameworkAdapter: createFrameworkAdapterFromEnv(), });

src/lib/kortyx-client.ts should be imported by API routes or other server-only modules, not by React client components.

What to Read Next