System model and ownership
Cheetah separates the concerns of a distributed client application so that each one has a clear owner and a replaceable implementation boundary. The separation is not a requirement to deploy many processes. It is a way to keep product decisions, connection lifetimes, returned-data handling, client execution, and platform authority from becoming one indivisible subsystem.
Read from product intent at the top to platform work at the bottom. The blue path carries commands toward a current client. The green path carries progress, outcomes, events, and state through authenticated HTTP ingestion.
Product code owns purpose and consequences
The product defines its workflows, actions, target-selection rules, business state, and user experience. It may ask a browser to inspect a page, a console client to transform a file, or a cooperative web client to report interface state. Those actions are part of the product, not built-in meanings supplied by Cheetah.
Product code calls the application-facing surface from an ordinary web route, worker, scheduler, queue consumer, or another service. It decides whether an outcome is useful and what an uncertain external effect means. For a high-impact action, the product may need a domain idempotency key, reconciliation step, compensation, or human review. The framework cannot infer those rules from transport evidence.
This boundary keeps Cheetah reusable. The framework coordinates named work without absorbing the application's domain model.
Three server roles separate different workloads
The server side has three externally meaningful roles. They can share one process and one component set, or run in separate processes when their workloads and failure domains justify it.
App role
The App role is the product-facing surface. It resolves client presence, prepares commands, applies configured central authorization, registers terminal correlation when requested, dispatches work, exposes retained histories, and provides access to selected higher-level facilities.
It does not need to own the target client's socket. In a coordinated deployment, it can hand work to a different process that owns the current connection.
WebSocket role
The WebSocket role owns live client connections. During connection setup it authenticates the hello, validates protocol information, records the stable client and current runtime instance, and registers the route. It handles heartbeat, replacement, command delivery, delivery acknowledgements, and exact-instance cleanup on disconnect.
This role answers the operational question, "Which process can reach this runtime now?" It does not decide why the product should perform the action.
REST role
The REST role handles information returning from clients through the host's authenticated HTTP edge. It accepts the supported message families, validates their structure and size, checks current-instance identity where applicable, coordinates deduplication and history, notifies collectors, and resolves terminal correlation for accepted results or errors.
It also accepts full client state reports through their dedicated path. The REST role is not a universal web application router: the host still owns concrete routes, TLS, and the authentication integration that derives the trusted principal before calling Cheetah.
Interfaces and implementations hold the roles together
The roles depend on interfaces for responsibilities such as authentication, connection registry, dispatch, correlation, notification, history, deduplication, tracing, topology, context storage, and resource quota. Factories construct nodes from a compatible component set. Presets assemble common implementation families.
An in-memory family is appropriate when one process can own the relevant state. Redis-backed implementations coordinate the responsibilities that must cross process boundaries, such as routes, durable logical-client command mailboxes, correlation metadata, notifications, histories, and deduplication. Live WebSockets and in-process futures still belong to the processes that created them; Redis coordinates around those local resources rather than moving them. Mailbox and response notifications wake likely owners or readers, but retained mailbox or history state remains authoritative when a notification is lost.
Replaceability is a contract, not a promise that any combination is safe. A custom history store, dispatcher, or authentication provider must preserve the identity, lifecycle, tenancy, ordering, and cleanup behavior expected by its neighbors. Presets reduce the risk of assembling individually valid components into an incoherent system.
The client has a shared runtime and a platform layer
The portable TypeScript core contains the behavior that should retain the same meaning in different environments: identity, connection negotiation, action registration, command validation, central and local policy composition, optional approval, leases and cooperative cancellation, handler dispatch, progress and terminal outcomes, response delivery, state reporting, and telemetry hooks.
Platform packages add the capabilities that cannot be honestly generalized. A browser extension works with Chrome extension lifetimes, tabs, windows, content scripts, capture, and parsing. A console process works with files, child processes, flows, downloads, and modules. A web client acts within the authority and lifetime of its page. A native bridge or custom client must map its own platform onto the same identity, authority, and outcome meanings.
The shared runtime is not a remote-superuser layer. Platform code and product handlers still own the real effect, and local policy can narrow or deny a request that central policy permitted.
The host completes the network and operational boundary
Cheetah's server roles are service layers embedded by the host application. The host mounts the WebSocket and HTTP edges, integrates real authentication, terminates TLS, manages secrets, chooses the process topology, starts and stops listener-backed components, and maps framework outcomes into its own web stack.
The host and product also own edge rate limiting and sensitive-operation auditing. Cheetah defines rate-limiter and audit-logger interfaces and implementations, but ordinary node execution does not invoke them automatically. Redis command admission can use the wired resource-quota responsibility; that narrower facility should not be described as a complete public-edge protection system.
Optional facilities attach without changing the core path
Several Cheetah facilities build on the same identities and returned evidence: tracing, diagnostic inspectors and dashboards, reusable UI components, browser capture and parsers, worker/context coordination, response collection, derived views, Local Mode, and site or local-site relay capabilities.
They attach at named seams rather than forming one mandatory stack. This is important both for small applications and for technical honesty. An application that only needs remote browser actions should not have to operate every dashboard or worker service. Conversely, the existence of an optional package does not establish that it has the same maturity or production posture as the core browser and console paths.
Composition changes topology, not the application vocabulary
A local or single-process composition and a Redis-coordinated deployment have different durability, capacity, and operating obligations. They still expose the same central ideas: effective principal, stable client, current runtime instance, named action, progress, terminal outcome, retained response, and platform context.
That continuity is the architectural scaling property. Teams can add clients, machines, and separate role processes without rewriting the product around an unrelated second command model. They still need to design and operate the more distributed topology deliberately.