What's an app?

What an MDK app actually is, concretely: its anatomy and what's yours versus what's reused

Definition

An MDK app is a publishable package: a route table (mdk-plugin.json) with the controllers behind it, plus a UI module, all described by an mdk-app.yaml manifest. You scaffold it with mdk create app, publish it to npm or GitHub, and anyone installs it into their own stack with mdk add app.

An app is the unit of work you author and ship. A stack is what an operator runs, and it lists the apps it serves under spec.apps in its mdk.yaml.

Anatomy

What the package holds, as mdk create app scaffolds it:

apps/fleet/
├── mdk-app.yaml               # app manifest
├── package.json               # `files` ships the manifest, plugin/ and ui/
├── plugin/
│   ├── mdk-plugin.json        # route table
│   ├── lib/client.js          # the app's own mdk-client
│   └── controllers/summary.js # one module per route
├── ui-src/                    # UI source
└── ui/index.js                # the built UI module, committed

Part	What it is	Who reads it
`mdk-app.yaml`	The manifest: `id`, `version`, `displayName`, and optional `description`, `permissions`, `config` and `main`	The app runtime and the operator, at boot and at `mdk validate app`
`plugin/`	`mdk-plugin.json` declaring the routes, one controller module per route, and the app's own `@tetherto/mdk-client`	The app runtime, which serves the routes
`ui/`	An ES module default-exporting `defineMdkApp({ id, displayName, routes, panels })`, built from `ui-src/` and committed	The dashboard shell, which mounts its pages and panels
`package.json`	The npm identity, and the `files` list that decides what ships in the tarball	npm, and `mdk add app`

backend/apps/demo/ is a shipped app you can read end to end: its manifest, its route table and one controller per route. It serves routes only, so the ui/ half is the one part it does not show; mdk create app scaffolds that.

What's yours versus what's reused

Yours is the app package and nothing else. Kernel, the Gateway, the app runtime, the Workers your routes read from, and the dashboard shell your UI mounts into are all reused unchanged, in every deployment (see architecture).

A Worker Plugin is a separate thing you may also own: it integrates one device family, and the integration model covers how the two differ.

What an app is not

Not a stack. mdk.yaml is the operator's deployment unit, and it lists apps under spec.apps rather than being one.
Not a fork of Kernel or the Gateway. You never edit their source to build an app.
Not a Worker. A Worker speaks a device protocol downward to hardware; an app serves HTTP routes upward to people and agents.
Not loaded by default. A Gateway serves only the apps its stack declares, so installing a package is not the same as serving it.

Next steps

Understand the integration model: what a Worker Plugin and an app each get to do
Understand architecture: how the pieces of a stack talk to each other
Understand the MDK App Toolkit: the layers a UI or headless consumer builds on
Build, publish and install an app from an empty directory
Look up the terms in this page when a word does more than one job