System Design

Looking to get started using MicroStax? This page explains how MicroStax works internally — it's for architects and platform engineers. If you want to create your first environment, start with Getting Started or the CLI Guide.

This page explains how the control plane is put together under the hood, so engineers and platform teams can reason about the moving parts and make informed adoption decisions.

Design Goal

MicroStax is built to answer one question reliably:

Given a Blueprint and an environment lineage, what should run locally, what should be inherited, how should requests resolve, and how can the result be replayed or audited later?

That requires more than manifest generation. It requires a graph-aware control plane.

Main Design Layers

Click top-right to expand

1. Intake And Validation

Inputs can come from Blueprints, existing environment state, or replay artifacts.

At intake time the system should:

• validate schema and required fields
• normalize service and dependency records into deterministic forms
• assign or confirm stable service identities
• reject invalid lineage or incompatible routing modes early

The important design rule is that comparison happens after normalization, not on raw source files.

2. Environment Graph Store

The graph store is the persistent model of the environment system. It does not have to be a graph database, but it must preserve graph semantics such as:

• service identities
• dependency edges
• baseline and overlay lineage
• provider mappings
• snapshot lineage
• execution and governance artifacts

This is what allows replay, audit, routing inspection, and derived-environment reasoning to stay deterministic.

3. Difference And Composition Engines

Once the graph is loaded, the control plane needs two related capabilities:

Difference analysis

Used to determine:

• added services
• changed services
• removed services
• unchanged but impacted services

Overlay composition

Used to determine:

• parent and ancestor environments
• nearest eligible provider for each inherited service
• final service ownership across overlay chains

Together, these engines decide what the derived environment really is.

4. Planning And Sparse Scheduling

After composition, the planner converts the graph into a runtime plan.

The plan should answer:

• which services must be local
• which services can be inherited
• what order provisioning jobs should run in
• whether snapshot restore or seeds need to run
• which candidate plan best satisfies cost and policy constraints

This is the point where the system stops being descriptive and becomes operational.

5. Identity And Routing Resolution

Sparse environments are only safe if service resolution is explicit.

The resolution layer determines, for each requested service:

• local overlay service
• explicit provider mapping
• inherited ancestor provider
• baseline provider
• shared provider pool
• denied resolution

That result becomes a resolved identity record. Routing artifacts such as DNS aliases, registry entries, proxy rules, or gateway configuration should be downstream products of the resolution record, not the source of truth themselves.

6. Executable Runtime

The executable runtime consumes the planned graph and turns it into ordered actions such as:

• create namespace or runtime scope
• provision workloads and services
• configure bridging and routing artifacts
• run snapshot restore jobs
• run seed jobs
• persist state transitions

The runtime should persist enough state to explain what happened and support replay later.

7. Replay, Snapshot, And Audit State

MicroStax stores more than current environment status.

It should preserve:

• graph revisions
• snapshot references
• execution records
• governance and audit events
• resolution and propagation decisions where needed

That makes features like env replay, governed promotion, and historical diagnosis possible.

8. Validation Beyond Provisioning

Provisioning success is not enough for a shared platform.

The design therefore includes higher-order validation paths:

• conflict detection for branching changes
• shadow traffic and behavioral diffing
• policy and governance checks
• compliance-oriented audit inspection

This is what turns the platform from an environment launcher into an environment control plane.

9. Why Graphs Instead Of Static Config

A graph model is useful because the hard problems are all relationship problems:

• which service changed relative to what baseline
• which dependency becomes locally required
• which ancestor owns a service
• which requests must preserve overlay context
• which snapshot corresponds to which environment lineage

Static manifests can describe desired resources, but they do not preserve enough relationship state to solve those questions well on their own.

10. Design Tradeoffs

The system design makes a few deliberate tradeoffs:

• more control-plane state in exchange for deterministic derived environments
• explicit lineage and resolution records in exchange for better auditability
• graph planning complexity in exchange for lower runtime duplication
• richer orchestration metadata in exchange for replay and shadow validation

Those tradeoffs are what make the patent family and the platform architecture coherent with each other.