Node

This page is the canonical definition of Project and Node in Topoo Cloud.

The model starts from the problem Topoo needs to solve: a small product may be understandable as one body of work, while a large product contains many distinct problem domains that people, Agents, and programs must advance in parallel without losing context or overwriting one another.

Read Node Workbench and Lifecycle Model for the canonical Source, editor, Submission, Node Version, Artifact, Release, and Deployment objects attached to these boundaries.

Canonical definitions

Project is the unified product and release subject exposed to the outside world.

Node is a persistent, permission-scoped code container and attention boundary inside a Project.

A Project organizes Nodes into one coherent product. A Node gives one problem domain a durable code container, bounded context, permission scope, version history, and delivery record.

Node is not defined first as a file, repository, package, process, server, Agent, Session, or domain. Some Nodes may bind or produce those objects, but none of them alone defines a Node.

Why Node exists

Node exists to make large products understandable and governable.

It provides:

• a clear problem and responsibility boundary
• durable context that survives individual Agent Sessions
• a bounded source and resource scope
• independent work, review, and version history
• a submission channel for people, Agents, and programs
• conflict and dependency visibility across parallel work
• an auditable delivery record that the Project can accept into a release

The primary value of Node is attention management and responsibility isolation. Independent build or runtime behavior may follow from that boundary, but it is not the universal definition.

Small and large Projects

A small Project may use one default Node:

Project
└── Default Node

The user does not need to manage additional structure until the work requires it.

A large Project may contain many problem-oriented Nodes:

Topoo Cloud Project
├── UI System Node
├── Deployment System Node
├── Authentication Node
├── Billing Node
├── Observability Node
└── Domain System Node

These Nodes may use different Agents, programs, repositories, packages, runtime targets, and review rules while remaining part of one externally unified product.

Project responsibility

Project owns the unified product boundary:

• product identity and objective
• Node topology and dependency policy
• members, permissions, and production authority
• environments, resources, domains, and routes
• release candidates and integrated checks
• Preview and Production promotion
• observability, audit, and rollback
• the final set of accepted Node versions that form a Project Release

Project is the authority that decides which accepted work represents the product.

Node responsibility

Node owns the durable working and delivery boundary for one problem domain:

• problem statement, scope, and acceptance framing
• Agent identity, prompt, permissions, and operating procedure
• linked source scope such as repository, branch, root path, or package
• Work Session links and their Node-scoped Submissions
• Submissions, checks, summaries, and review state
• immutable Node revisions and delivery versions
• dependencies, consumers, and affected Project surfaces
• build and Artifact records when the Node produces a buildable output

A Node may be code-producing, package-producing, runtime-capable, workflow-oriented, component-oriented, or coordination-oriented. Runtime is a Node capability or type, not the definition of every Node.

Node Workbench and editor relationship

Node is the responsibility object. Node Workbench is the operating surface for that object.

The Workbench may present a Code editor, visual website editor, component editor, workflow canvas, schema editor, document editor, or Agent editor. These are editor adapters over the same canonical, versionable Source model rather than separate product lifecycles.

Node
├── Canonical Source
├── Code or specialized editor adapters
├── Submissions and Node Versions
├── Checks and optional Artifacts
└── Preview and delivery history

A no-code editor must change canonical structured Source and produce a reviewable Diff. Direct Source changes must also be reflected when that specialized editor reads the new revision. Visual state must not become a hidden, unversioned database copy.

The current Code editor direction should therefore evolve into a general Node Workbench shell. Deep code-editing or visual-editing engines can progress independently while every editor uses the same lifecycle objects.

Agent and Work Session relationship

Node carries long-lived responsibility. Work Session carries short-lived attention.

Project
├── Nodes
│   ├── UI System
│   ├── Deployment System
│   └── Domain System
└── Work Sessions
    ├── Session 1 ── scope ── UI System
    ├── Session 2 ── scope ── Deployment System
    └── Session 3 ── scope ── UI System + Domain System

A Work Session belongs to one Project and links to one or more Nodes through explicit Session Node Scopes. One Node may receive work from multiple Agents and many Sessions. One Session is not a Node, and creating a new Session does not create a new responsibility boundary.

This Project-scoped relationship supports the normal habit of opening one new execution-client Session for one small requirement. A narrowly authorized contractor Session may be restricted to one Node, while an internal task may cross several Nodes without weakening their separate permissions, Base Revisions, checks, or version histories.

Sessions may be created in Codex, VS Code, Claude, or another execution client. Topoo does not need to own the chat interface. Topoo provides the Project identity, Node scopes, isolated Session Workspace, authority, and Submission channels that the external Session uses.

Read Work Sessions and Local Runtime for the isolation and execution architecture.

Submission and release relationship

Agent work must move through explicit authority boundaries:

Project-scoped Work Session
→ one or more Node Submissions
→ immutable Node Version
→ optional Node Artifact
→ Project Release Candidate
→ immutable Release Artifact Set
→ Preview
→ Approval
→ Production

Node publication and Project deployment are different:

• Node publication creates a new immutable Node Version and, when buildable, one or more immutable Artifacts for one responsibility domain.
• Project deployment promotes an accepted combination of Node Versions through one immutable Release Artifact Set.

A Node version becoming available must not silently change a Project. The Project explicitly accepts that version into a Release Candidate.

Source, repository, and monorepo relationship

Repository and Node are not the same object.

• one repository may provide source to one Node
• one monorepo may provide different root paths to several Nodes
• one Node may bind more than one source when the responsibility requires it
• one Project may organize Nodes backed by several repositories

Node boundaries follow problem ownership and delivery responsibility, not repository layout alone.

Project
├── Node A ── Repository X / apps/web
├── Node B ── Repository X / apps/worker
└── Node C ── Repository Y /

Splitting a Node does not automatically require splitting a Git repository. Splitting a repository does not complete the architecture until the consuming Node records a real, versioned dependency on the separated output.

The relationship is therefore many-to-many:

Repository 1 ── supplies ── Node A
             └─ supplies ── Node B
 
Node C ─────── binds ────── Repository 2 / packages/ui
       └────── binds ────── Repository 3 / catalog

Two Nodes may intentionally use the same repository when they own different problem domains. In a monorepo, each Node must declare an explicit Source Binding rather than treating the repository root as its identity.

For example:

Repository: topoo-cloud
├── Node: Cloud Console
│   ├── Root path: apps/cloud-web
│   ├── Checks: cloud-web typecheck and build
│   └── Artifact: cloud-web
├── Node: Cloud API
│   ├── Root path: apps/cloud-api
│   ├── Checks: API contract and worker build
│   └── Artifact: cloud-api-worker
└── Node: Topoo UI
    ├── Root path: packages/topoo-ui
    ├── Checks: component and package checks
    └── Artifact: @topoo/ui package

Repository sharing does not remove conflict risk. Shared files, lockfiles, build configuration, generated schemas, and cross-Node packages must be declared as affected source or dependency scopes. The Release Controller uses those scopes to detect overlapping Submissions and to decide which Node Versions must be checked together.

The following decision rule prevents artificial Node proliferation:

• use different Nodes when responsibilities, permission scopes, version histories, Checks, Artifacts, dependencies, or delivery decisions are genuinely different
• use one Node with multiple Agents or linked Sessions when the work changes the same source scope, produces the same output, and follows one lifecycle
• use Sessions to divide temporary tasks such as sidebar, top bar, and component refinements; do not create a Node for every task
• allow one coherent Session to link to several Nodes when the requirement genuinely crosses durable responsibility boundaries
• do not claim that two Nodes are independently deliverable until shared dependencies and accepted versions are explicit

Package and runtime examples

TopooUI illustrates why Node cannot be defined only as a running process.

TopooUI responsibility
├── versioned @topoo/ui Package Artifact
└── runtime-capable catalog site

The shared UI responsibility may publish a versioned Package Artifact. Consumer Projects choose when to accept that package version. The catalog site may also run as a site-capable Node and be exposed through a Project-owned domain.

For runtime-capable Nodes, Topoo may record build, Artifact, runtime, deployment, and health state. For non-runtime Nodes, those fields are absent rather than fabricated.

Release example

Topoo Cloud Release 101
├── UI System Node        → Version 13
├── Deployment System    → Version 8
├── Authentication Node  → Version 21
└── Billing Node         → Version 5

If only the UI System Node changes, the next Project Release may pin:

Topoo Cloud Release 102
├── UI System Node        → Version 14
├── Deployment System    → Version 8
├── Authentication Node  → Version 21
└── Billing Node         → Version 5

The Project changes locally without rebuilding or redefining unrelated responsibility domains.

Product invariants

The following rules must remain true:

1. Project is the external product, environment, domain, and Production authority.
2. Node is the persistent, permission-scoped code container and attention boundary inside a Project.
3. Agent is an actor working under Node scope; it is not the Node itself.
4. Work Session is an ephemeral Project-scoped work transaction linked to one or more Nodes.
5. Submission is proposed work, not deployment authority.
6. A Node Version is immutable after publication and pins its Source Revision, accepted Submissions, Checks, and dependencies.
7. A Project Release pins the accepted Node Versions and their immutable Artifact relationships.
8. A Node version does not silently update consuming Projects.
9. Repository layout does not define Node topology by itself.
10. Runtime state is shown only for Nodes that actually have a runtime capability.