How FlowLayer Works

// Runtime Modeloverview

FlowLayer turns one JSONC configuration into a predictable runtime session. Same valid config, same dependency graph, same startup decisions — deterministic by design.

The server computes planning, runs lifecycle actions, evaluates readiness, and streams canonical state and logs to clients.

Runtime Model in One Line

config -> DAG -> startup waves -> readiness gates -> session state + logs -> control actions

Three Layers

flowlayer.jsonc

Config

Declares services, dependencies, readiness intent, and session settings. Strict JSONC — unknown fields are rejected.

flowlayer-server

Server

Plans waves from the DAG, orchestrates lifecycle, evaluates readiness, and publishes canonical state and logs.

flowlayer-client-tui & custom

Clients

Observe state and logs over WebSocket and request control actions. Never invent state from local guesses.

Dependency Graph (DAG)

• Services and dependsOn edges are parsed into a directed graph.
• Unknown references and invalid graph structures fail fast.
• The graph is reused for boot decisions and later control actions.

Startup Waves

• Services with satisfied dependencies can start in the same wave.
• Downstream services wait until upstream readiness passes.
• This gives safe parallelism without losing dependency ordering.

Readiness Gates

• Readiness decides when a service is considered available.
• If readiness does not pass, dependents remain blocked.
• Blocked state is visible to clients through session state and logs.

One Runtime, Many Clients

• The server owns canonical lifecycle and log state.
• Multiple clients can connect to the same session.
• Every client sees the same truth: snapshot baseline + event stream deltas.

Session Timeline

1. Client authenticates to /ws.
2. Server sends hello.
3. Server sends snapshot.
4. Runtime emits event updates (service_status, log, …).
5. Client sends command messages.
6. Server responds with ack, then result when applicable.

What You See / What FlowLayer Does

What you see	What FlowLayer does
blocked service	Keeps it paused until upstream readiness conditions pass.
Two services start together	Places them in one startup wave after dependency checks.
Restart request on one node	Re-applies dependency and lifecycle rules from server-side state.
Shared session across operators	Keeps one consistent control plane for all connected clients.

Logs and Control Plane

• Process logs are centralized by the server and streamed to clients.
• State transitions are published from server lifecycle decisions.
• Clients can reconnect and rebuild context from server data, not local guesses.

What This Is Not

• Not a free-form script runner with hidden ordering logic.
• Not a multi-master control model where each client decides orchestration.
• Not a replacement for production deployment orchestration.

Next: read Server for orchestration responsibilities, then Client / TUI for the client perspective.