Architecture overview

DotCraft is a .NET 10 / C# agent runtime. Its assemblies split the work into the provider-neutral agent foundation, the product kernel, reusable hosting, the external protocol, and the official application's composition root. This page defines those boundaries for integrators and contributors.

Assembly boundaries

Higher-level components depend only on the foundational layers beneath them:

DotCraft.App (official composition root)
  |-- DotCraft.Runtime
  |     `-- DotCraft.Core
  |           `-- DotCraft.Agents
  |-- DotCraft.AppServer
  |     |-- DotCraft.Core
  |     `-- DotCraft.Protocol
  |-- model providers
  `-- optional features

Component	Responsibility
DotCraft.Agents	Provider-neutral Agent APIs, provider contracts, common middleware, the tool loop, and prompt-cache selection
DotCraft.Core	Product kernel for sessions, Agent orchestration, tools, context, memory, skills, plugins, security, configuration, modules, and workspace semantics
DotCraft.Runtime	Reusable dependency-injection registration and Generic Host lifecycle for a workspace
DotCraft.Protocol	Wire contracts shared by AppServer and protocol clients
DotCraft.AppServer	JSON-RPC request handling, contract mapping, connection state, and stdio and WebSocket transports
DotCraft.App	Official composition root for process entry points, providers, optional features, logging, and process policy
Feature assemblies	Automations, Dynamic Workflows, channels, and other feature-owned behavior built on Core contracts

Core builds on the provider-neutral Agents foundation. Runtime and feature assemblies build on Core. AppServer adapts Core domain capabilities to Protocol contracts. The official App picks these components and connects feature-specific protocol adapters at the composition boundary. Runtime and AppServer share the same host-owned ISessionService.

Module discovery and capability facets

DotCraft.Generators discovers compiled modules that implement IDotCraftModule. The base contract defines the module identifier, configuration checks, and dependency-injection registration. A module implements a capability facet when it contributes that capability:

Facet	Contribution
IToolSourceModule	Tool sources exposed to the Agent runtime
IChannelServiceModule	A managed channel service
ISessionChannelModule	Session origins exposed by a channel

DotCraft.App owns host selection and process composition. Its host factories use IModuleHostComposition to decide which compiled modules each official host's service graph contains.

Session Core

Session Core defines the Thread → Turn → Item model. ISessionService is the central in-process API for thread lifecycle, input submission, events, approvals, and user-input requests.

CLI, ACP, Automations, and channel adapters use the same Session Core and persistent thread model. Transport boundaries project this model without changing its domain semantics. See Unified Session Core for the model and lifecycle.

AppServer

AppServer is the optional protocol and transport boundary over Session Core, and the host owns it. It projects ISessionService through JSON-RPC 2.0 over stdio and WebSocket, maps Core domain models to DotCraft.Protocol contracts, and manages connection-scoped resources.

Desktop, CLI, ACP, external channel adapters, and SDK clients all use this out-of-process boundary. See AppServer Protocol and AppServer mode.

Hub

Each user has one Hub on the machine. Hub starts or reuses one AppServer per workspace and maintains discovery information and locks under ~/.craft/hub/. Desktop and CLI use Hub by default. Remote, CI, bot, and protocol-debugging scenarios can manage AppServer directly.

Configuration in the official host

The official DotCraft.App host loads the following default configuration layers:

Layer	Path	Purpose
Global	~/.craft/config.json	Provider credentials, endpoints, and personal preferences
Workspace	<workspace>/.craft/config.json	Model selection, entry switches, automations, and security policy

Configuration policy belongs to the host. DotCraft.App merges the two layers and supplies the effective AppConfig when it composes Runtime, and both Core and Runtime consume that configuration. Modules declare their config sections with [ConfigSection("Key")], and the source generator includes those sections in the merged schema.

See Configuration reference for fields and Settings lifecycle for when changes take effect.