# Architecture

Canonical: https://auggy.dev/docs/architecture
Status: Published
Package: auggy 0.5.0

How **Auggy**'s small turn kernel and composable augments form a self-hosted agent runtime.

## System shape

| Layer | Owns |
| --- | --- |
| Kernel | Turn execution, context allocation, model calls, validated tool execution, history, and turn results. |
| Augments | Tools, memory, context, skills, transports, policy, lifecycle hooks, and integrations. |
| Your systems | Frontend, database, auth provider, payments, durable jobs, approvals, and external APIs. |

The kernel stays small. Augments connect it to the systems your application already uses.

## Runtime kernel

| Kernel part | Responsibility |
| --- | --- |
| Turn loop | Orchestrates a single model turn end to end. |
| Context allocator | Assembles history, context blocks, and tool definitions within a token budget. |
| Capability table | Tracks exposed tools, blocked tools, trust rules, and tool-call counters. |
| History manager | Maintains thread history and keeps `tool_use`/`tool_result` pairs coherent. |
| Tool selector | Filters tools through capability policy before the engine sees them. |
| Lifecycle manager | Boots augments, runs shutdown hooks, and reports health. |
| Transport admission | Rate-limits and bounds concurrent inbound turns per transport. |
| Trace records | Capture context, tool, inference, cost, timing, and validation events in each TurnResult. |

> **Note: Runtime data is not the same as console UI**
>
> TurnResult records more than the current console renders. See Console for the UI available today.

## What augments contribute

| Contribution | What it provides |
| --- | --- |
| Tools | Typed actions the model can select during a conversation. |
| Skills and context | On-demand guidance and scoped prompt context. |
| Memory | Durable state providers and retrieval tools. |
| Transports | Inbound channels such as web chat, AG-UI, and Telegram. |
| Lifecycle and policy | Boot validation, migrations, cleanup, auth requirements, rates, budgets, and operator controls. |

An augment can provide one or several of these. Group behavior by capability, not by individual function.

## Turn execution

**Normal runtime path**

```
User message
  -> transport
  -> kernel assembles context and tools
  -> model requests a tool
  -> runtime validates and executes it
  -> transport returns the result
```

> **Note: Optional app integration is separate**
>
> Advanced preview augment routes can serve an existing frontend or webhook without a model turn. They are not required for a normal agent and do not turn **Auggy** into a general web framework.

## Inside one turn

1. Admission: Resolve caller trust, queue, rate, and budget checks.
2. Assembly: Build context from history, hooks, memory, and tool schemas.
3. Inference: Call the configured model provider.
4. Execution: Validate and authorize selected tools, then append their results.
5. Finalization: Validate output, compact history, record trace data, and run end hooks.

Inference and tool execution may repeat until the model finishes or maxInferenceLoops is reached. Tool results stay paired with their tool calls in thread history.

## What is not in the kernel

- No planner component. The model plans by choosing tools.
- No retrieval engine. Retrieval belongs in memory or knowledge augments.
- No general web framework. Keep the application's normal API in its existing stack.
- No durable workflow engine or persistent job queue. Keep long-running orchestration in a workflow system or application service.
- No automatic policy inheritance. Each capability declares and enforces its own trust and operational limits.

## Related

- [Security](https://auggy.dev/docs/security/markdown)