Software estate: systems, components, interfaces, data, environments, decisions and risks.
by Cynergis · embeds the ontology software-architecture@5 · engine >=0.4
/plugin marketplace add Cynergis/oto-registry
/plugin install software-architecture@cynergisThe engine plugin oto comes with it. Then the pack's start skill begins a project from the installed copy: oto init --name "<project>" --pack "${CLAUDE_PLUGIN_ROOT}" --project <root>. At a terminal: oto registry add https://github.com/Cynergis/oto-registry, oto pack add software-architecture, oto init --pack software-architecture.
software-architecture@5: 14 classes, 20 relations, 4 rules, 3 actions, extends oto-core.
| Class | What it is | The question it answers | Why it exists |
|---|---|---|---|
| Document | A source document in the corpus: a design, a review, a standard, a transcript. | Where is this written down? | Every fact needs a checkable source, and the source is a file with its own date. |
| Action | Something that can be done about an entity, described the way an MCP server describes a tool and bound to the graph. Oto lists it; the caller invokes it; the recorded run is evidence. | What can be done about this, and how? | The binding between an entity, the tool that acts on it, its inputs, its credentials by name and its preconditions is otherwise tribal knowledge in an agent's prompt; as a fact it is versioned, reviewed and shared. Oto never invokes it. |
| System | A named application or platform that a team owns and a user or another system consumes. | What is this thing, and who owns it? | A system is the unit people name in conversation and the unit ownership attaches to, so it has to exist even though it is coarse. |
| Component | A part of a system deployed or released as a unit: a service, a job, a library, a front end. | What actually gets deployed, and what does it touch? | Change and failure happen at the deployable unit, not at the system, so impact questions need this level. |
| Interface | A contract others depend on: an API, an event topic, a file feed, a database view. | If we change this, who breaks? | Coupling lives in the contracts others depend on, so the contract must be a node that both sides can point at. |
| DataStore | A place data lives: a database, a bucket, a queue, a cache, a warehouse table. | Where does this data live, and who writes it? | Two writers to one store is the commonest quiet cause of inconsistency, and it is only visible if the store is a node. |
| Environment | A place components run: production, staging, a region, a tenant. | Where does this run, and is the answer the same in production? | Topology differs between environments, and an answer that ignores that is misleading in an incident. |
| Team | The group accountable for something. Attach ownership to a team, not to a person. | Who do I call? | Accountability must point at a group rather than a person, because people move and the question does not. |
| Capability | A business capability the estate supports. This is what the business asks about. | What does the business lose if this is down? | This is the only class a non-engineer will use, so it must exist in their words rather than being inferred from component names. |
| Requirement | A stated need, functional or otherwise, that something must satisfy. | What must this satisfy, and does it? | A stated need outlives the component that meets it, and a replacement must satisfy the same thing. |
| DecisionRecord | A recorded architecture decision: the choice, the alternatives, the reason, the consequences. | Why is it like this? | Architecture without recorded reasons is re-litigated every year, and the reason has its own date and author. |
| Risk | A known way this can hurt: a single point of failure, an end of support, a concentration. | What is fragile, and what are we doing about it? | A risk nobody can trace to a component is not actionable, so it must point at what it threatens. |
| Runbook | The documented way to operate or recover something. | How do I operate or recover this at three in the morning? | The operating procedure is a distinct artifact with its own currency, and it is the thing an incident needs. |
| Repository | Where a component's code lives: a source repository, recorded before it exists (intended) and observed once it does. | Where is the code? | A component without a repository cannot be changed, and an architecture graph that cannot say where the code lives cannot be acted on. Recorded as intended before the repository exists, it is the fact an action realises. |
| Relation | From | To | Meaning |
|---|---|---|---|
cites | Document | Document | This document refers to that one, so a fact traced to it can be traced one step further. |
acts_on | Action | The entity a recorded run of this action read or changed. | |
executed_by | Action | Who is accountable for invoking this action: a team, never a person. | |
part_of | Component|Interface|DataStore | System | This belongs to that system. |
owned_by | System|Component|Interface|DataStore|Capability | Team | The team accountable. |
exposes | System|Component | Interface | The contract something publishes. |
consumes | System|Component | Interface | A contract something depends on. This is where coupling lives. |
depends_on | System|Component | System|Component | The consumer needs the provider to work. Usually derived from consumes and exposes, and stated only when a document says so. |
reads_from | Component | DataStore | A component reading this store. |
writes_to | Component | DataStore | A component writing this store. Two writers to one store is worth knowing about. |
runs_in | Component|DataStore | Environment | Where something runs. |
supports | System|Component|Capability | Capability | What business capability this serves. |
satisfies | System|Component|Interface | Requirement | The requirement something meets. |
decided_by | System|Component|Interface|DataStore | DecisionRecord | The recorded decision that shaped this. |
supersedes | DecisionRecord|Interface|Component|System | DecisionRecord|Interface|Component|System | This replaced that. Use with the temporal fields, never by overwriting. |
threatens | Risk | System|Component|Interface|DataStore|Capability | What a risk applies to. |
mitigated_by | Risk | DecisionRecord|Runbook|Component | What reduces a risk. |
operated_by | System|Component | Runbook | The runbook for something. |
documented_in | System|Component|Interface|DataStore|DecisionRecord|Requirement | Document | Where this is written down. |
implemented_by | Component | Repository | The repository that holds this component's code. |
The pack's sample graph, 18 nodes and 20 edges, in the explorer every project gets: open it full size.
OTO lists them; the caller invokes.
action.check-repository on Repository (read-only): Reads the repository's metadata from GitHub and records that it exists, its URL and its default branch. Realises an intended repository; re-attests a current one.action.create-repository on Repository: Creates the repository an intended Repository fact describes, under its owner, and records the result. Changes the world: a person confirms it by name.action.probe-interface on Interface (read-only): Calls an interface's base URL with a GET and keeps the response as a source document, so what the interface actually answers can be read and curated./software-architecture:start Start or extend an Oto knowledge project in this domain: Software estate: systems, components, interfaces, data, environments, decisions and risks. The pack 'software-architecture' (release 1) embeds the ontology 'software-architecture' (release 5), which declares System, Component, Interface, DataStore, Environment, Team, Capability, Requirement and more. Use when someone wants a knowledge graph, a vocabulary or an interview for this domain.Software estate: systems, components, interfaces, data, environments, decisions and risks.
This skill comes with the software-architecture pack. The ontology is inside the pack, so nothing is fetched.
1. Start a project from this pack.
oto init --name "<project name>" --pack "${CLAUDE_PLUGIN_ROOT}" --project <root>${CLAUDE_PLUGIN_ROOT} is this pack's directory; Claude Code fills it in. Outside Claude Code, with the pack on the machine (oto pack add software-architecture from the cynergis registry), oto init --pack software-architecture does the same. The project records the ontology's origin, so oto status says when a newer release exists and oto ontology diff shows what changed.
2. Run the ontology-interview skill to fit the vocabulary to the documents at hand.
3. Hand over to the build-knowledge-base skill for the documents, and to the query-knowledge skill for questions. The engine plugin oto comes with this pack: the kg_* tools and the generic skills are available once it is installed.
Oto lists them; the caller invokes (the act skill):
action.check-repository on Repository: Reads the repository's metadata from GitHub and records that it exists, its URL and its default branch. Realises an intended repository; re-attests a current one.action.create-repository on Repository: Creates the repository an intended Repository fact describes, under its owner, and records the result. Changes the world: a person confirms it by name.action.probe-interface on Interface: Calls an interface's base URL with a GET and keeps the response as a source document, so what the interface actually answers can be read and curated.It answers the questions people ask about a software estate under pressure, from documents that were written to describe it at rest: what breaks if this changes, who owns it, why it is the way it is, what is fragile, and what the business loses when a part fails. Every answer cites the document that states it and the date it was true.
consumes and exposes, and the rule consumer-depends-on-provider derives the dependency between components so it can be asked directly: oto query neighbors "<component>" depends_on.owned_by to a Team. If the answer is a person, the graph is recording the wrong thing.decided_by to a DecisionRecord and quotes its reason. A decision without a recorded document is flagged by decision-is-documented.threatens and mitigated_by from Risk. The rule risk-reaches-system lifts a risk to a component up to its system.supports to Capability, the one class written in the business's words.Open the explorer (oto serve --http 8765) and read the System column first: each system is a unit of ownership. Then one system's components and the interfaces between them. Read DecisionRecord entries last: they explain what the rest shows. A dashed edge was derived by a rule; oto rules explain <rule> says why the rule exists and what it derived.
The ontology ships three actions, listed by oto actions list and never invoked by Oto: a daily check that a repository exists (read-only; it realises an intended Repository and re-attests a current one), the creation of a repository an intended fact describes (it changes the world, so a person confirms it by name), and a weekly read of what an Interface answers at its URL. Record a run with oto actions record, and the response enters the graph through the gates with the run as its evidence. The act skill is the protocol.
Environment only where a question needs it, and point at the catalog that holds the rest.writes_to is separate from reads_from so this can be asked: oto query neighbors "<store>" writes_to.validated_by empty on a rule for months. A rule nobody confirmed derives facts nobody asked for.None yet: the explorer and the reader every project has.
It answers the questions people ask about a software estate under pressure, from documents that were written to describe it at rest: what breaks if this changes, who owns it, why it is the way it is, what is fragile, and what the business loses when a part fails. Every answer cites the document that states it and the date it was true.
consumes and exposes, and the rule consumer-depends-on-provider derives the dependency between components so it can be asked directly: oto query neighbors "<component>" depends_on.owned_by to a Team. If the answer is a person, the graph is recording the wrong thing.decided_by to a DecisionRecord and quotes its reason. A decision without a recorded document is flagged by decision-is-documented.threatens and mitigated_by from Risk. The rule risk-reaches-system lifts a risk to a component up to its system.supports to Capability, the one class written in the business's words.Open the explorer (oto serve --http 8765) and read the System column first: each system is a unit of ownership. Then one system's components and the interfaces between them. Read DecisionRecord entries last: they explain what the rest shows. A dashed edge was derived by a rule; oto rules explain <rule> says why the rule exists and what it derived.
The ontology ships three actions, listed by oto actions list and never invoked by Oto: a daily check that a repository exists (read-only; it realises an intended Repository and re-attests a current one), the creation of a repository an intended fact describes (it changes the world, so a person confirms it by name), and a weekly read of what an Interface answers at its URL. Record a run with oto actions record, and the response enters the graph through the gates with the run as its evidence. The act skill is the protocol.
Environment only where a question needs it, and point at the catalog that holds the rest.writes_to is separate from reads_from so this can be asked: oto query neighbors "<store>" writes_to.validated_by empty on a rule for months. A rule nobody confirmed derives facts nobody asked for.