Source and Git

Topoo Cloud uses GitHub as the canonical provider for editable source and document history. Topoo does not expose a second Git remote and does not maintain a parallel repository authority.

The product model separates three responsibilities:

• GitHub stores repositories, branches, tags, commits, Pull Requests, Checks, and file history
• Topoo Project owns identity, repository bindings, the Product Technical Documentation and Product Development Plan identities, Node scopes, Source Revision records, and accepted Change Sets
• Topoo Release Controller validates, builds, promotes, verifies, audits, and rolls back immutable releases

The canonical objects and editor relationship are defined in Node Workbench and Lifecycle Model.

One Git authority, two working interfaces

Users may manage source directly in GitHub or work through Topoo's UI and Agents. These are two interfaces to the same GitHub history, not two repositories being synchronized.

When a user or Agent changes source or either canonical Project document inside Topoo, Topoo creates or updates a GitHub branch, commit, or Pull Request through the authorized GitHub integration. GitHub remains the file and commit authority; Topoo records the exact provider revision and converts it into an immutable Source Revision and Project Change Set.

Topoo therefore does not need its own customer-facing Git hosting to provide:

• Project and Node organization
• Agent work orchestration
• source and documentation impact analysis
• Preview and Production deployment
• release approval, audit, and rollback
• automatic maintenance of Product Technical Documentation and Product Development Plan

Source relationships

A blank Project or uploaded package may offer an explicit Create GitHub repository action when the user has authorized it. That repository is still a GitHub resource owned under the selected GitHub account or organization. Topoo does not silently create a provider repository during a repeated import.

Repository, Project, and Node boundary

Repository, Project, and Node are not aliases.

• one GitHub repository may be imported into several independent Topoo Projects
• one monorepo may supply several Nodes through different root paths
• one Node may bind multiple source inputs when one responsibility genuinely spans them
• one Project may organize Nodes backed by several GitHub repositories

Each import creates a new permanent Topoo Project identity, with independent Nodes, resources, secrets, domains, environments, documents, releases, deployments, and audit history. Importing the same repository three times does not require three GitHub repositories.

Deleting or archiving a Topoo Project removes or archives Topoo-owned records only. It does not delete the GitHub repository. Repository deletion remains an explicit GitHub lifecycle operation.

Each Node Source Binding identifies the repository, reference policy, primary root path, additional affected paths, required Checks, build contract, Artifact contract, and versioned dependencies.

GitHub repository: product-monorepo
├── apps/console   → Console Node
├── apps/api       → API Node
└── packages/ui    → UI System Node

Node topology follows problem ownership, durable attention, permission, and delivery responsibility. Repository layout is one source input, not the product identity.

GitHub-connected flow

1. The user authorizes a GitHub App installation and selects a repository and branch.
2. Topoo records the Project binding and resolves the exact commit.
3. Topoo imports an immutable source snapshot and creates a Source Revision record.
4. The Agent analyzes source, build configuration, Product Technical Documentation, and Product Development Plan impact.
5. A Topoo-originated change is delivered to a GitHub branch or Pull Request.
6. GitHub commits, Pull Requests, and Checks become provider evidence attached to the Topoo Change Request.
7. Accepted changes form an immutable Project Change Set and release candidate.
8. Preview and Production reuse the same accepted Artifact set.
9. The deployment record preserves Source Revisions, document revisions, Changes, Checks, Nodes, Artifacts, Environment, operator, approval, and time.

GitHub is not called again merely to open a Project page. Topoo reads its own Project, source-binding, revision, document, and release records. Live GitHub calls are reserved for explicit synchronization, source reads not yet cached, or write operations.

Product Technical Documentation and Product Development Plan

Every Project owns two canonical document identities:

1. Product Technical Documentation records accepted current truth: product boundaries, architecture, interfaces, Node topology, bindings, deployment behavior, operating constraints, and runbooks.
2. Product Development Plan records intended change: goals, decisions, milestones, work items, dependencies, status, acceptance criteria, and unresolved questions.

Their file representations and edit history live in the bound GitHub repository. Topoo owns their Project identity, document paths and Node scopes, immutable accepted revisions, audience rules, Change Set linkage, and release evidence.

An Agent may update code and both documents together, but it must keep proposed work out of accepted technical truth until the corresponding Change Set and Production verification are accepted.

Agent submission channels

An Agent must not deploy merely because it changed files.

Each writing Session receives an isolated worktree or equivalent copy-on-write Workspace based on a pinned GitHub revision. Routine Git mechanics may remain ambient in the Topoo UI, but every accepted source or document change resolves to GitHub history.

Every Agent submission enters a channel with explicit authority:

Submission authority and deployment authority remain separate.

Provider outage behavior

Topoo stores immutable source captures and release evidence so an already accepted revision can still be inspected, rebuilt, redeployed, or rolled back during a temporary GitHub outage.

Topoo cannot create a new canonical source or document commit while GitHub is unavailable. New editable history resumes when the GitHub authority is reachable again. This avoids split-brain histories while preserving runtime continuity.

Portability rule

GitHub history remains normal Git history. Disconnecting a repository does not remove Topoo's existing immutable Source Revisions, Artifacts, deployments, or audit ledger. Reconnecting or changing a binding is explicit and audited.