Total architecture

This page is the single map of the whole omega_architecture stack: how runtime, channel, flows, agents, navigation, Flutter widgets, and tooling fit together. Use it before diving into the focused guides linked in each section.

For a narrative “why” and product fit, start with Vision & why Omega. For step-by-step setup, see Getting started and omega_setup.dart.

What Omega optimizes for

One communication plane — OmegaChannel broadcasts OmegaEvents; the UI and domain code do not call each other directly.
Intent-first UI — Screens emit OmegaIntents; OmegaFlowManager routes them to running OmegaFlows.
Agents for side effects — OmegaAgent + OmegaAgentBehaviorEngine centralize IO, storage, and imperative work; widgets stay thin.
Observable orchestration — Flows emit expressions (streams) for UI state and can trigger navigation through the same channel conventions the navigator listens for.

More narrative walkthroughs: Getting started, Channel & events, and the example app on GitHub.

Layers at a glance

mermaid

flowchart TB
  subgraph presentation["Presentation (Flutter)"]
    Scope[OmegaScope]
    Pages[Pages / OmegaRoute builders]
    Builders[OmegaBuilder / expression listeners]
    Insp[OmegaInspector / receiver]
  end

  subgraph orchestration["Orchestration"]
    FM[OmegaFlowManager]
    Flows[OmegaFlow instances]
  end

  subgraph domain["Domain & IO"]
    Agents[OmegaAgent + behavior rules]
    Proto[OmegaAgentProtocol]
  end

  subgraph plane["Communication plane"]
    Ch[OmegaChannel]
    NS[OmegaChannel.namespace]
  end

  subgraph nav["Navigation"]
    Nav[OmegaNavigator]
    Routes[OmegaRoute registry]
  end

  Pages --> Scope
  Builders --> Ch
  Flows --> FM
  FM --> Flows
  Agents --> Ch
  Flows --> Ch
  FM --> Nav
  Nav --> Routes
  Proto --> Agents
  Insp --> Scope
  Scope --> Ch
  Scope --> FM

Layer	Responsibility	Typical types
Communication plane	Broadcast events; optional per-module namespaces	`OmegaChannel`, `OmegaEvent`, typed names via `OmegaEventName` / `OmegaIntentName`
Orchestration	Which flow is active; handle intents; translate channel traffic into expressions and navigation signals	`OmegaFlowManager`, `OmegaFlow`, `OmegaFlowContext`, `OmegaFlowExpression`
Domain & IO	Reactions to events (HTTP, DB, device); optional direct agent messaging	`OmegaAgent`, `OmegaAgentBehaviorEngine`, `OmegaAgentProtocol`
Navigation	Map `navigate.*` / `navigation.intent` to Flutter routes	`OmegaNavigator`, `OmegaRoute`
Presentation	Inject dependencies; rebuild on events/expressions; debug surfaces	`OmegaScope`, builders, inspector

Bootstrap: from `main` to a live app

OmegaRuntime.bootstrap is the single factory that wires everything:

Creates one OmegaChannel.
Calls your OmegaConfig Function(OmegaChannel) (usually createOmegaConfig in omega_setup.dart).
Builds OmegaFlowManager, OmegaAgentProtocol, and OmegaNavigator.
Registers agents, flows, and routes from OmegaConfig.
Calls wireNavigator so navigation events on the channel reach the navigator.
Runs optional intentHandlerRegistrars (e.g. OmegaFlowManager.registerIntentHandler, lightweight pipelines).

mermaid

sequenceDiagram
  participant Main as main()
  participant RT as OmegaRuntime
  participant CH as OmegaChannel
  participant CFG as OmegaConfig
  participant FM as OmegaFlowManager
  participant NAV as OmegaNavigator

  Main->>RT: bootstrap(createOmegaConfig)
  RT->>CH: OmegaChannel()
  RT->>CFG: createOmegaConfig(channel)
  RT->>FM: register flows, wireNavigator(NAV)
  RT->>RT: register agents, routes, intentHandlerRegistrars
  RT-->>Main: OmegaRuntime(channel, flowManager, ...)
  Main->>Main: OmegaScope + MaterialApp(navigatorKey)

Cold start is explicit: initialFlowId selects which flow is running; initialNavigationIntent (with OmegaInitialRoute / OmegaScope.initialNavigationIntent) aligns the first Navigator screen with navigate.* semantics. Details: omega_setup.dart, Navigation & routes.

Channel, namespaces, events, and intents

Events — “Something happened” (OmegaEvent: id, name, payload). Consumers use payloadAs<T>() / typedPayloadAs<T>() (extensions on OmegaEvent; typedPayloadAs for OmegaTypedEvent payloads).
Intents — “Something is requested” (OmegaIntent). The flow manager delivers intents to flows in running state via handleIntent or handleTypedIntent (OmegaTypedIntent); use payloadAs / typedPayloadAs on OmegaIntent in onIntent. Navigation uses the same intent model with names like navigate.login or navigate.push.detail.
Namespaces — OmegaChannel.namespace scopes traffic by module (auth, checkout, …) while sharing one physical channel.
Typed wire names — Prefer enums implementing OmegaEventName / OmegaIntentName with OmegaEvent.fromName / OmegaIntent.fromName (static methods; optional <T> on payload) instead of raw strings.

More detail: Channel & events, Data flow.

Flows and flow manager

Piece	Role
OmegaFlow	Business process: onIntent, onEvent, emits expressions for UI and events for agents / navigation
OmegaFlowManager	Registers flows; activate / switchTo; handleIntent / handleTypedIntent to running flows
OmegaFlowState	Only running flows receive intents and process events
OmegaFlowExpression	UI-facing stream of state (loading, success, error, …)
OmegaFlowContext	Context passed into `onIntent` / `onEvent`
OmegaWorkflowFlow	Step-based flows built on the same channel model

Optional OmegaFlowContract documents listened events, handled intents, and emitted expression kinds; in debug, mismatches are reported. See example/lib/auth/ (AuthFlow / AuthAgent) for contract usage.

Snapshots — OmegaFlowSnapshot / app-level snapshots support debugging, persistence, and time-travel tooling (OmegaSnapshotStorage, restoreFromSnapshot).

Focused guides: Intents, flows & manager, Data flow.

Agents and behaviors

Piece	Role
OmegaAgent	Listens to the channel; delegates decisions to the behavior engine; runs onAction for imperative work
OmegaAgentBehaviorEngine	Evaluates OmegaAgentBehaviorRules or custom logic → OmegaAgentReaction
OmegaAgentProtocol	Registry + direct / broadcast messaging between agents (OmegaAgentMessage, inbox) — not a replacement for the global channel

Optional OmegaAgentContract mirrors the flow contract idea for agents.

Focused guide: Agents & behaviors.

OmegaFlowManager.wireNavigator connects the channel to OmegaNavigator:

Payload OmegaIntent on navigation.intent, or
Event names navigate.<id> / navigate.push.<id> derived into intents.

OmegaRoute registers builders; OmegaRoute.typed avoids manual arguments casts.

Focused guide: Navigation & routes.

Flutter UI integration

Widget / API	Use when
OmegaScope	Root: exposes channel, flow manager, optional initial flow / navigation intent
OmegaAgentScope / OmegaScopedAgentBuilder	Bind subtree to a specific agent and its view state
OmegaFlowActivator	Activate flows from UI where needed
OmegaFlowExpressionBuilder	Rebuild from a flow’s expression stream
OmegaBuilder	Rebuild on a named channel event
OmegaInitialRoute / OmegaInitialNavigationEmitter	Cold start navigation
OmegaInspector / OmegaInspectorReceiver / launcher	Debug: events + flow snapshots (including multi-window web)

Lightweight intent handling (optional)

For small apps you can register OmegaFlowManager.registerIntentHandler or use Omega.handle / OmegaIntentReducer / OmegaIntentHandlerPipeline without a dedicated flow class — often wired through OmegaConfig.intentHandlerRegistrars after bootstrap.

Cross-cutting concerns

Topic	Where it lives
Failures	OmegaFailure for semantic errors on the channel or return paths
Contracts (debug)	OmegaFlowContract, OmegaAgentContract — guide: Contracts
Time travel	OmegaTimeTravelRecorder, OmegaRecordedSession — Time travel, `omega trace` (CLI)
Offline-first intents	OmegaOfflineQueue — Offline-first
Package barrel	omega_architecture.dart — canonical exports

Repository and tooling (outside `lib/omega`)

Area	Role
`example/`	Runnable reference: `omega_setup.dart`, auth flow/agent, routes
`bin/omega.dart`	omega CLI: `create app`, ecosystem generation, validate, traces, optional AI helpers
`docs/`	This VitePress site; `public/inspector.html` for VM Service inspector page

Guides: Repository layout, Omega CLI, Inspector & VM Service, Testing.

End-to-end intent → screen (summary)

mermaid

sequenceDiagram
  participant UI as Widget
  participant FM as OmegaFlowManager
  participant F as OmegaFlow
  participant CH as OmegaChannel
  participant A as OmegaAgent
  participant NAV as OmegaNavigator

  UI->>FM: handleIntent / handleTypedIntent(login)
  FM->>F: onIntent (running flows)
  F->>CH: emit auth.login.request
  CH->>A: event stream
  A->>CH: emit auth.login.success
  CH->>F: onEvent
  F->>CH: emitExpression(success) / navigate.home
  CH->>NAV: navigation event
  NAV-->>UI: new route

Total architecture ​

What Omega optimizes for ​

Layers at a glance ​

Bootstrap: from main to a live app ​

Channel, namespaces, events, and intents ​

Flows and flow manager ​

Agents and behaviors ​

Navigation ​

Flutter UI integration ​

Lightweight intent handling (optional) ​

Cross-cutting concerns ​

Repository and tooling (outside lib/omega) ​

End-to-end intent → screen (summary) ​

Suggested reading order ​

Total architecture

What Omega optimizes for

Layers at a glance

Bootstrap: from `main` to a live app

Channel, namespaces, events, and intents

Flows and flow manager

Agents and behaviors

Navigation

Flutter UI integration

Lightweight intent handling (optional)

Cross-cutting concerns

Repository and tooling (outside `lib/omega`)

End-to-end intent → screen (summary)

Suggested reading order