Architecture

Octonode has one architecture concept: a registered source repository and the Projects it contains.

• An architecture is backed by one registered source repository (the monorepo boundary).
• A project is one package or deployable service inside that architecture.
• A project dependency is an explicit consumer-to-provider reference through projectDependencies in the consuming project's .octonode config.
• Plugins, variables, and data tables attached by projects are architecture resources. They are represented once and may be referenced by every project in the architecture.
• Project source files, workflows, executable nodes, and workflow data/control/dependency edges are projected with project-qualified identities. The graph is derived from the repository registry and project configs; it is never persisted as a second editable graph.
• The Architecture is the sole owner of its GitHub repository connection, pull requests, reviews, commits, and implementation status. A Project inherits that repository context and cannot connect to GitHub independently.

For example, an architecture named Prisma packages system may contain @octonode/common and @octonode/serverless. If serverless declares common in projectDependencies, the architecture contains serverless -> common. If both attach the same plugin, variable, or data table, one shared resource node has references from both projects.

Contract and routing

GET /api/architectures/:architectureId is the only architecture projection route. The architectureId is the stable ID of the registered monorepo that supplies its source authority. Project Architecture tabs resolve their owning architecture; they do not derive another project architecture. Workspaces may contain several architectures but are not themselves an architecture.

GitHub uses the same stable Architecture identity. The provider's numeric repositoryId remains a separate external identifier and never replaces Octonode's sourceRepositoryId.

PUT/DELETE /api/architectures/:architectureId/github
GET        /api/architectures/:architectureId/github/pull-requests
GET        /api/architectures/:architectureId/github/pull-requests/:number
GET        /api/architectures/:architectureId/github/pull-requests/:number/workflow-diff?projectId=...

The server validates the Architecture against the repository registry before forwarding a link or read. At link time it sends the contained Project IDs and repository-relative roots to the control plane. PR files are matched against those roots, so one repository-scoped PR can report every affected Project without duplicating the PR. projectId appears only when a workflow review needs a contained-Project projection; it does not grant repository ownership.

The response contains the architecture identity/name, projects, source files, workflows, executable nodes, shared resources, and their relationships. Inclusive mode follows project dependencies and resource references. Exclusive mode keeps the chosen entities, expands their owned descendants, and turns dependency references outside that selection into boundaries.

Studio implementation ledger

Architecture mode contains the repository spine, contained Projects, source-control status, and one PR implementation ledger. Selecting a PR highlights every affected Project; selecting a contained Project then projects that same immutable PR head onto its workflows and nodes. Project screens do not expose GitHub connection or project-owned PR controls.

Knowledge search is optional, read-only supporting context. It may cite canonical repository docs while explaining an Architecture or PR, but it never owns or mutates implementation state.

Playbook is not an Architecture entity or relationship. It is only a publication surface that renders reviewed Markdown from this repository; the repository copy remains authoritative.