Projects and branches

Project

A project is an isolated workspace for building the operating system for a company or division. It connects a customer-owned monorepo to its project database, backend, apps, connections, and delivery state. The repository contains the backend, apps, shared packages, infrastructure declarations, and delivery configuration.

We generally recommend one project per company or division, not one per team. Shared operations compound when they reuse the same objects, tools, permissions, and integrations.

Branch

A branch is a source line of change. Feature branches normally get preview environments so a change can be exercised with real URLs, bindings, and data before it reaches main.

The branch is not the environment. It produces a candidate release that can be deployed to one.

Environment

An environment is a running target. It has URLs, bindings, secret values, a database, deployed executables, and a lifecycle. Preview, staging, and production are environments.

Production records the exact release that is live.

Release

A release is an immutable, resolved manifest for the entire project. It records:

• artifact hashes for the backend and every app;
• the backend contract and infrastructure declarations;
• migrations and dependency versions;
• compatibility metadata.

The same release can move through staging and production without being rebuilt.

Deployment

A deployment reconciles a release into an environment. It updates only the executables and managed infrastructure whose resolved state changed, while recording the complete manifest.

Rollback deploys a prior release. It does not rebuild old source.

The delivery path

1. A feature branch gets a preview environment.
2. Merging to main resolves one immutable project-wide release.
3. Checks evaluate that release.
4. Deployment reconciles the approved release into production.
5. The same release may move through staging first when the operation needs it.
6. Rollback redeploys a known prior release.