The application graph

Kuppit keeps one picture of your application and derives everything else from it. The picture has three kinds of thing in it: components, nodes and references. Understanding them explains why environments behave as they do, what a reference costs and does not cost, and why the overview looks the way it does.

Components

A component is a thing your application is made of, named once per project: the web service, the database database. The component owns the name and the kind. That is why the same component is web in Production, in staging and in every preview, and why nothing can be api in one environment and backend in another.

Nodes

An environment has a node for each component it includes. The node is the environment's instance of the component: the service that deploys this environment's branch, the database this environment's services connect to. A node's status, hostname, deployments and variables are its own.

A node normally is its own instance. Two decisions change that:

• Share. The node points at another environment's instance. It reports that instance's status and credentials, keeps its own place in this environment, and creates nothing new.
• Clone. The node is its own instance, seeded from a copy of another environment's data when the environment was created. Afterwards it is independent, and Kuppit records where the data came from and consults it for nothing.

An environment also records the components it deliberately does not have, so Don't include stays distinguishable from a component added to the project later.

References

A reference is a variable on one node whose value is a variable another node exposes:

database ── DATABASE_URL ──▶ web

Read it as: web references a variable exposed by database. The arrow follows the data. The database provides the value; the service consumes it. That direction is what the overview draws, and what the Connections list beneath it says in words.

Three rules give references their character:

• A reference targets a node in the same environment, always. Staging's web references staging's database; a database in another environment is, to it, indistinguishable from one that does not exist. Sharing is how an environment deliberately brings another environment's instance inside that rule.
• A reference is resolved when a deployment is prepared, from the target's state at that moment, and the resolved value is frozen into that deployment. The service is connected to the database as it is now, and a rollback restores the connection as it was then.
• A reference is a dependency, and Kuppit treats it as one. A deployment waits for a database still being created, fails clearly for one that no longer exists, and names every connected service before a database is deleted.

What is derived from the graph

Nothing reads the raw list of resources or connections; a third rendering would read the same graph.