# Architecture

Level: Advanced

## Goal

Understand the runtime objects that matter when integrating Flow Core with gameplay code, graph wrappers, generated registries, and external systems.

## High-level Model

Flow Core keeps graph structure, runtime state, and scene data separate:

| Layer            | Owns                                                                                            | Typical user action                                                        |
| ---------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| Flow Graph asset | Serialized nodes, ports, edges, comments, and graph settings.                                   | Author behavior visually.                                                  |
| FlowCoreProcess  | Scene lifecycle, graph assignment, Local Blackboard bindings, and runtime ownership.            | Bind a graph to a GameObject.                                              |
| FlowGraphRuntime | Executable runtime built from graph data.                                                       | Runs triggers, entries, chains, BT branches, Stack, FSM, or GOAP behavior. |
| FlowContext      | Runtime state, active payload, temp payload, resolved Blackboard collection, and chain context. | Read indirectly through instructions, conditions, and supported APIs.      |
| Registries       | Discoverable instructions, conditions, enums, drawers, serializers, and generated entries.      | Rebuild after codegen or extension changes.                                |

The most important rule: graph assets describe behavior, while processes and contexts own runtime state.

## Runtime Build Flow

At runtime, `FlowCoreProcess` prepares its Blackboard collection, disposes any previous runtime during rebuild, then creates a new runtime from either embedded graph data or the assigned `FlowGraphAssetBase`.

For normal graph assets, `FlowGraphAsset.CreateRuntime` builds the runtime from the graph data and the provided Blackboard collection. For custom graph asset wrappers, `FlowCoreProcess` still calls the same supported boundary: `CreateRuntime(FlowBlackboardCollection blackboards)`.

This means wrapper and bridge code should respect the process as the runtime owner. The wrapper may choose which graph asset creates the runtime, but it should not share one runtime between processes.

## Core Runtime Objects

### FlowCoreProcess

`FlowCoreProcess` is the MonoBehaviour entry point. It owns the assigned graph source, Local Blackboard list, runtime rebuild calls, lifecycle trigger forwarding, and public entry points used by gameplay systems.

Use it when you need to bind a graph to a scene object, rebuild after changing graph source, cancel active chains, or inspect process-level runtime counts.

### FlowGraphRuntime

`FlowGraphRuntime` is the executable graph instance. It contains the runtime representation of triggers, entries, nodes, chains, and module-specific runtime data. A runtime belongs to one process build.

Do not cache and reuse one runtime across multiple GameObjects. If a graph source is selected again, create a fresh runtime for that process.

### FlowContext

`FlowContext` carries per-execution state such as payload, TempPayload, active Blackboard collection, and context values. User-authored instructions and conditions normally interact with it through supported helper APIs and value containers rather than storing long-lived state on nodes.

Use Blackboard for persistent or shared state. Use payload and TempPayload for runtime-transient data inside the active chain.

### Registries

Registries make generated and authored instructions, conditions, enums, drawers, serializers, and related metadata discoverable. If a generated instruction exists on disk but cannot be found in the editor, the registry step may be stale.

Use [Codegen Pipeline](/flow-core-docs/documentation/api-extension-guide/codegen-pipeline.md), [Codegen Generators](/flow-core-docs/documentation/api-extension-guide/codegen-generators.md), and [Generated Items](/flow-core-docs/documentation/api-extension-guide/generated-items.md) to maintain this layer.

## Integration Implications

* Graph wrappers should return a fresh runtime and pass through the provided Blackboard collection.
* Data bridges should write typed values into the correct Blackboard scope before the graph needs them.
* Event bridges should publish signals on the main thread and avoid modifying listener ownership during dispatch.
* Custom instructions and conditions should keep runtime state in context or Blackboard, not in shared graph asset data.
* Codegen changes usually require both generated outputs and registries to be refreshed.

## Example: Inspect Runtime Readiness

```csharp
using UnityEngine;
using TwoCatsCode.FlowCore;

public sealed class FlowRuntimeInfo : MonoBehaviour
{
    [SerializeField] private FlowCoreProcess process;

    private void Start()
    {
        int triggers = process.GetTriggerCount();
        int enters = process.GetEnterCount();
        int nodes = process.GetNodeCount();
        FlowContext context = process.GetContext();

        Debug.Log($"Triggers={triggers} Enters={enters} Nodes={nodes} ContextReady={context != null}");
    }
}
```

Use this kind of check only as a quick diagnostic. For normal authoring, prefer Debug Context, visual debugging, and the graph editor summaries.

## Common Mistakes

* Treating a graph asset as if it owned per-object runtime state.
* Sharing a runtime instance from a wrapper asset.
* Updating an external system and Blackboard in both directions without a clear owner.
* Running codegen but skipping registry refresh.
* Reading Local Blackboard data without confirming the process Local Blackboard list.

## Related

* [Lifecycle and Dataflow](/flow-core-docs/documentation/runtime-guide/lifecycle-and-dataflow.md)
* [Graph Asset Wrapper](/flow-core-docs/documentation/api-extension-guide/graph-asset-wrapper.md)
* [Third-party Bridges](/flow-core-docs/documentation/api-extension-guide/third-party-bridges.md)
* [Generated Items](/flow-core-docs/documentation/api-extension-guide/generated-items.md)
* [Performance and Failure Modes](/flow-core-docs/documentation/troubleshooting/performance-and-failure-modes.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://flow-core.gitbook.io/flow-core-docs/documentation/runtime-guide/architecture.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.