Skip to content

Mental Model

Jump to bottom
Adrian Burlacu edited this page Feb 6, 2026 · 3 revisions

Mental Model — Stark as an Operating System

To understand Stark, stop thinking in layers like frontend/backend or UI/server. Instead, think of Stark as:

a programmable operating environment where orchestration is the core runtime.

Understanding how Stark Orchestrator thinks will help you use it effectively. This page explains the core mental model behind Stark's design.

The Kernel

In Stark, the orchestrator functions like a kernel:

  • It schedules pods (running processes)
  • It enforces constraints (CPU, memory, policies)
  • It restarts failed pods
  • It tracks desired vs actual state
  • It emits system events for observation

Nothing bypasses the orchestrator.

The Kubernetes Inspiration

Stark draws heavy inspiration from Kubernetes, but adapted for JavaScript workloads running in both Node.js and browser environments.

Kubernetes Stark Purpose
Container Image Pack Deployable unit of code
Container Pod Running instance
Node Node Execution environment
Namespace Namespace Resource isolation
Service Service Managed pod lifecycle

Core Abstraction Layers

┌─────────────────────────────────────────────┐
│                   Packs                     │
│  (Bundled, versioned code - the "what")     │
└─────────────────────┬───────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────┐
│                   Pods                      │
│  (Running instances - the "how")            │
└─────────────────────┬───────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────┐
│                   Nodes                     │
│  (Execution environments - the "where")     │
└─────────────────────────────────────────────┘

Packs vs Pods

  • A pack is a software package — a bundle of code, metadata, and dependencies
    (analogous to a library or installable artifact).
  • A pod is an instantiation of a pack — a running process scheduled by the orchestrator
    (similar in concept to how Kubernetes schedules pods as execution units).

Packs are inert until they become pods.

The Shell

The "client" or "UI" in Stark is:

  • Just another set of packs instantiated as pods
  • Capable of rendering interfaces
  • Not required for the system to function

Stark's shell is composable and replaceable.

The Isomorphic Principle

Stark's unique value is isomorphic execution. The same pack can run on:

  • Node.js servers - Backend services, workers, CLI tools
  • Browsers - UI applications, client-side logic

The orchestrator abstracts away the runtime differences, giving you a unified service model.

Declarative vs Imperative

Stark supports both styles:

Imperative (Direct Commands)

# Create a pod directly
pod create --pack my-app --node my-node

Declarative (Managed Resources)

# Create a service, let Stark manage pods
service create my-app --pack my-app --replicas 3

Services are declarative—you specify what you want (3 replicas), and Stark ensures that state is maintained.

Resource Ownership Model

Stark has a clear ownership model:

User (owner)
  └── Nodes (owned by user)
  └── Packs (owned by user, private or public)
  └── Pods (run on user's nodes or admin nodes)
  └── Services (manage user's pods)

Key ownership rules:

  • Users can only deploy their own packs to their own nodes
  • Public packs can be deployed by anyone to their nodes
  • Admin nodes are shared infrastructure that can run any user's packs

State Machine Thinking

Pods progress through a state machine:

Pending → Scheduled → Running → Succeeded/Failed
                ↓
            Stopping → Stopped

Understanding these states helps debug scheduling and execution issues.

The Key Shift

Traditional systems separate:

  • processes vs user interfaces
  • orchestration vs execution
  • system vs application

Stark blurs those lines.

Everything in Stark:

  • is packable
  • becomes schedulable
  • runs as a process
  • is observable and restartable

That is the operating environment.

TODO: Add More Details

Next Steps

Clone this wiki locally