The application graph

Kuppit keeps one picture of your application and derives everything else from it. The picture has four kinds of thing in it: components, nodes, references and external services. 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 says in words on a phone.

A connection is the deliberate form of this: web → database made as one act, injecting every variable the database exposes and owning those references. The graph draws an edge either way — for a connection, and for references written by hand — and a connection and a hand-written reference to the same database are two edges between the same pair.

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 — and the overview draws that reference as it resolves, from staging's web into Production's box, as a cross-environment connection. Choosing another environment's database under Connect to… makes the share and the connection in one step; see connections.
• 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.

External services

An external service is something the application depends on that Kuppit does not run: Stripe, an email sender, an error tracker, an API of your own. It is not a component and has no node — nothing instantiates it — and the project knows it once, however many environments use it. The overview draws it per environment: beside each box whose nodes use anything stands one External services card, saying how many and whether the environment has set what they read, with one line to it from every node that uses something; open the card and the services stand behind it, one card each, so Stripe appears beside Production and beside Staging when both use it while Kuppit still holds one Stripe. Which environments' web reach Stripe is what each environment's own commit says: Kuppit reads every deployment's commit for what the component uses there, so a service a pull request began using stands behind its preview and not behind Production until the change deploys there. A service detected in an environment's commit that nobody has decided about is counted on that environment's card as suggested, and asked about in its panel.

Kuppit detects these when it analyses the repository, asks you which belong on the graph, and draws the ones you confirm. External services has what it looks for and how a service is confirmed, ignored or added by hand.

Changes and findings

Every deployment's commit is read for what it requires — the names each component reads, the services it uses, the resources it connects to — and remembered. A change is what one commit says relative to another: a pull request began reading RESEND_API_KEY, started using Resend, now requires PostgreSQL. A finding is what that means for one environment: the preview does not have RESEND_API_KEY. The same change reads differently in each environment, which is why the two are kept apart. A preview's box counts both; its panel lists them, and offers to set what is missing. Application changes has the whole of it.

What is derived from the graph

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