---
title: Platform Concepts
description: Understand the app, Module, Service, and System Plane boundaries behind the public Lenso lifecycle.
---

Lenso is an agent-ready modular application and microservice framework for Rust
business systems. It starts with one exact application composition and keeps
each boundary explicit as the product grows.

## Core model

| Concept | Current contract | Responsibility |
| --- | --- | --- |
| App Composition | `lenso.app.json` | Locks the app revision, content digest, immutable Module Releases, dependencies, implementation bindings, and provenance. |
| Module | `lenso.module.v1` | Owns a stable business identity, typed Business API, events, runtime declarations, and optional Console Surfaces. |
| Provider Service | `lenso.service.v1` metadata and `lenso.provider.v1` runtime | Provides exact Module Releases from a separate Rust or TypeScript process while the Host owns runtime coordination. |
| Autonomous Service | `lenso.service.v2` | Uses the Rust runtime to own its Workloads, Service Store, identity, workflows, and operations. |
| System topology | `lenso.system.v2` | Names the exact Host, Services, Modules, Workloads, contracts, and management relationships in a mixed topology. |
| Console Service | Console API | Connects the exact topology, loads receipt-bound Surfaces, and reports direct object status. |

The contracts compose; they do not replace one another. Moving a Support
Ticket Module from linked delivery to a Provider does not rename its business
identity or operations. An Autonomous Service adds an independently owned
runtime boundary while keeping its declared contracts explicit.

## Public lifecycle

The same four steps apply to developers, operators, and coding agents:

1. **Compose** an exact `lenso.app.json` from a product blueprint.
2. **Run locally** with `lenso dev up`; add `--console-root` to start an existing
   Console checkout with the Host and Provider Services.
3. **Connect** the signed local Service enrollment, exact `lenso.system.v2`
   topology, and its Management Binding through the bundle produced by the
   connected local command.
4. **Status** each Service, Module, Surface, Adapter, and Workload directly.

Production release and deployment stay with external delivery systems. Console
does not create, adopt, release, deploy, or repair the connected app.

## Modules keep business identity

`ModuleManifest` is serializable declaration data. It names capabilities,
Business API routes, runtime functions, events, lifecycle work, dependencies,
and Console Surfaces. Executable handlers stay in either a linked binding or a
Service implementation.

Operator UI is a digest-bound `console_ui_esm` artifact in the same immutable
Module Release. Its generated client calls declared operations through Surface
Gateway under an exact Surface Grant. Browser code receives neither Service
credentials nor direct Store access.

## Service capability tiers

Provider and Autonomous Service are different ownership levels, not two names
for any out-of-process Module:

- Provider keeps compatibility/process metadata in `lenso.service.v1`, installs
  exact `lenso.module-release.v1` releases, and uses the Host-owned
  `lenso.provider.v1` runtime at `/lenso/provider/v1`. It supports Rust and
  TypeScript.
- Autonomous Service `lenso.service.v2` is Service-owned and Rust only.

Current Rust Autonomous Service capabilities include direct HTTP/gRPC, Event
Contracts, Durable Workflows, Workload Identity, Delegated Actor Context, and
service-owned storage. TypeScript does not provide Autonomous Service parity.

See [Service Capability Tiers](/docs/autonomous-services) for the exact support
boundary.

## Data Plane and System Plane stay separate

Business calls use declared Module or Service contracts. Autonomous Service
traffic goes directly between Services; it does not pass through Console or a
Host Provider proxy. Each receiving boundary verifies actor, tenant, deadline,
idempotency, identity, and contract policy locally.

Console is the operator-facing System Plane. It validates the exact active
enrollment, topology digest, Management Binding, and advertised Core contract
before storing a connection. Its browser surfaces use the same-origin Console
Service, which keeps target credentials server-side.

## Status is object-specific

Every connected object reports one state with a direct reason:

- `connected`: the exact contract and live target agree;
- `unavailable`: the declared target cannot currently be observed;
- `incompatible`: a protocol, contract, release, or artifact does not match;
- `unmanaged`: no current Management Binding covers the object.

An unavailable Local Control Adapter leaves Workload observation `unknown` and
rejects mutation without queueing or fallback. Console does not collapse these
states into an app-wide score.

Continue with [Host Quickstart](/docs/quickstart) for the complete lifecycle or
[Service System Plane](/docs/service-system-plane) for the mixed-topology
connection model.