Buffaly architecture reference
An advanced architecture map for technical Buffaly users, operators, and extenders.
Read this when operating sessions, workers, subagents, and long-running tasks; extending Buffaly with skills, tools, services, web modules, provider modules, or ProtoScript; troubleshooting provider, tool, service, web-module, or compaction issues; or needing a verified map before changing documentation or capability boundaries. New users should start with the user guide and core concepts first.
Quick answer
Buffaly is a typed, ontology-driven agent runtime. User intent resolves into prototype-backed actions and entities, grouped by skills, loaded dynamically as tools, and executed inside stateful sessions.
Services own lifecycle, identity, state, configuration, and related methods. Web modules add browser, UI, and API surfaces. Provider settings select model backends and transports. Sessions preserve timelines, artifacts, compaction state, workers, and child or subagent relationships.
Architecture rule
Prefer the smallest typed boundary that fits the problem.
Durable facts, preferences, contacts, accounts, repos, and environments.
Reusable guidance or stable text workflows.
Typed callable wrappers and light orchestration.
Lifecycle, identity, state, configuration, and related methods.
UI and API packaging for browser-facing capability.
Model and provider integration, transport, and authentication.
Architecture map
| Layer | User-facing purpose | Validation clue |
|---|---|---|
| Web host | Serves docs, UI, settings, routes, assets, and web-facing modules. | Route exists, page loads, static assets and generated API surfaces are present. |
| Runtime and session host | Runs the Buffaly agent, sessions, workers, queued work, and long-running operations. | Session status, queue count, worker state, startup diagnostics. |
| Core session model | Stores timeline, turns, artifacts, Plan, Scratch, task files, parent and child links. | Session key, timeline entries, artifacts, child handles, compaction epoch. |
| Runtime abstractions | Defines execution contracts for actions, tools, providers, services, callbacks, and diagnostics. | Loaded tool list, runtime contract, typed result, explicit diagnostics. |
| Ontology and ProtoScript | Defines prototype-backed actions, entities, semantic phrases, and typed action wrappers. | Semantic action/entity search finds the expected candidate and the action loads. |
| Skills and actions | Groups discoverable capabilities into user-facing skill areas. | Skill list, action list, phrase match, description, and execution result. |
| Tools | Callable execution surfaces with typed parameters and traceable outputs. | Tool loads, input is typed, output is structured, errors are explicit. |
| Services | Own lifecycle, identity, state, configuration, and related methods. | Service instance exists, config is non-secretly verifiable, methods group coherently. |
| Web modules | Package UI, browser flows, static assets, APIs, and module-specific routes. | Manifest, route mapping, generated API surface, assets, runtime config. |
| Provider modules and catalog | Connect model backends, transports, auth, model selection, and reasoning settings. | Provider, model, transport, auth source, and non-secret diagnostics are visible. |
| Session stores and compaction | Persist session state and reduce context size while preserving active work. | Archive snapshots, compaction epoch, token reset evidence, restored Plan/Scratch/tasks. |
User request flow
- A user asks in normal language.
- Buffaly resolves the action and target through semantic action and entity search when needed.
- The needed tool or action is loaded.
- The agent inspects implementation, source, runtime evidence, session state, logs, or configuration.
- Execution happens through the narrowest boundary: typed file tool, ProtoScript action, service method, web module, provider call, or process fallback.
- Progress is recorded in the session timeline, Plan, Scratch, task artifacts, tool calls, and final answer.
- Validation is reported with file existence, scoped git status, changed files, commit hash, logs, route checks, or other concrete evidence.
Source-of-truth boundaries
| Information type | Best boundary |
|---|---|
| One-turn note | Scratch or timeline. |
| Current route | Plan. |
| Durable task | Task artifact. |
| Stable fact, preference, contact, account, repo, environment, or entity | Ontology memory. |
| Credentials and secrets | Protected secret or configuration, not normal memory, wiki, or prompt text. |
| Repeatable procedure | Workflow memory, then prompt action or ProtoScript if stable. |
| Typed callable behavior | ProtoScript action or native wrapper. |
| Stateful external configured binding | Service. |
| UI or API package | Web module. |
| Model backend, transport, or auth | Provider module and catalog. |
Where named pieces live
When debugging, source paths are evidence. Use the active checkout and runtime paths, but think in product-facing categories rather than copying implementation paths into user docs.
Common workflows
Add reusable capability
Choose memory, prompt action, ProtoScript, service, or web module based on durability, typing, lifecycle, and UI/API needs.
Troubleshoot missing tool
Check semantic action search, entity search, loaded tools, diagnostics, and source declaration.
Troubleshoot web module
Separate source presence, installed manifest, route mapping, generated API surface, static assets, and runtime config.
Continue long-running work
Inspect Plan, Scratch, task artifacts, queued work, active session, child handles, compaction state, changed files, and commit scope.
Diagnose provider and model issues
Separate provider, model, transport, reasoning, and auth. Use non-secret diagnostics, and do not silently switch providers unless the user requested a fallback.
Verification and troubleshooting checklist
- What source path or source evidence was inspected?
- What runtime path or runtime object is active?
- Is the boundary choice memory, prompt action, ProtoScript, service, web module, provider, or tool?
- Can non-secret configuration be verified?
- Is the session running, queued, compacted, child-backed, or worker-backed?
- What validation artifact, log, route, status, or commit proves the result?
- Does the action require approval because it is destructive or crosses a safety boundary?