Orchestrata Ultimate › Plans › architecture-ontology-draft

Architecture Ontology — RATIFIED (implementation pending)

Source: plans/architecture-ontology-draft.md at 8a2cb42ad · last changed 2026-07-27 · first committed 2026-07-18 · 543 lines.

Prose pending.

Plan text

Architecture Ontology — RATIFIED (implementation pending)

STATUS: RATIFIED 2026-07-19 — all 8 open questions ruled (see §9); schema not yet applied. This is the ontology-before-graph-import step (project doctrine: never dump docs into a graph without a schema). It distills a node/relationship/property/constraint vocabulary for representing software & system architecture knowledge in the orchestrata operational Neo4j KG, from the system-design Claude Code plugin. It is written as an EXTENSION PROPOSAL compatible with src/orchestrata_ultimate/knowledge_graph/canonical_schema.py (SPEC-106 FR-001): every node type gets an explicit canonical identity key + MERGE semantics; every relationship gets direction + cardinality + property set; everything is project-scoped unless genuinely global. No ingestion code, no writer changes — this is the schema draft. Nothing here is committed or applied.

1. Purpose & sources

Purpose. Give the KG a first-class vocabulary for design/architecture knowledge — the systems we design, their components/interfaces/dataflows, the requirements (BDD) and quality attributes that drive them, the decisions (ADRs) and trade-offs, the patterns applied, the technology/cloud choices gated by requirements, capacity/cost models, deployment topology, and SLOs/alerts/risks — so that context injection, provenance queries, and cross-project search can reason over architecture the same way they already reason over code structure, specs, tests, and runtime events.

Method mine. The plugin's 6-phase workflow is the concept taxonomy: Phase 0 ground truth → Phase 1 BDD requirements + constraints → Phase 2 capacity & cost → Phase 3 high-level design (components/dataflow/data model/APIs/storage) → Phase 4 decisions & trade-offs (ADRs, patterns, technology choices) → Phase 5 cross-cutting / WAF review (failure modes, SLOs, security, regions) → Phase 6 deliverables (design doc / OpenSpec change / ADR log). Node families are derived from the material, not assumed.

Sources read (plugin root …/system-design/skills/system-design/):

Existing project conventions read: src/orchestrata_ultimate/knowledge_graph/canonical_schema.py (canonical NodeType/RelationshipType constants, CANONICAL_MERGE_KEYS, _CONSTRAINT_NAMES, CONSTRAINTS DDL, apply()/check()); plans/kg-schema-gaps.md (split-brain debt, unwired provenance edges, Component keyed on name, Task gaps); scripts/sync_architecture_to_neo4j.py (the current architecture writer — see §7 for coexistence/supersession).

2. Design principles (inherited from SPEC-106 + project doctrine)

1. One canonical MERGE key per label, everywhere — mirrors CANONICAL_MERGE_KEYS. Every new label below declares exactly one identity key and one uniqueness constraint. No label gets two ways to be identified.
2. Project-qualified identity is the default — the KG holds 100+ projects (multi-project invariant, plans/kg-project-scoped-identity.md). Any architecture entity whose natural id recurs across projects (a component named "Gateway", an ADR numbered 0001, an environment "prod") keys on id = "{project}:{natural_id}" and keeps the bare value as a display property (name / natural_id / slug), exactly the File/Directory/Package precedent. project here = Project.slug, and must not contain :.
3. Global (unqualified) identity ONLY for genuinely cross-project reference data — the vendor/cloud service catalog (CloudService), the design/cloud pattern catalog (Pattern), the WAF pillars (WAFPillar), and cloud regions (Region) are shared reference vocabularies that mean the same thing in every project. These key on their global natural id (name / code). A project's own components, ADRs, requirements, SLOs, costs are project-scoped.
4. Reuse/extend existing canonical types; never mint a duplicate — where a concept already has a canonical label (Architecture, Component, Pattern, Requirement/RequirementItem/Spec, Scenario, UserStory, Change, Artifact) this proposal REUSES it and says so per-type in §3. New labels are introduced only for concepts with no existing home.
5. ADRs are append-only / immutable — an ArchitectureDecision's body (context/decision/alternatives/consequences) is frozen once status = Accepted. The only mutable field is status; reversal is a new node linked by SUPERSEDES. Neo4j has no per-property immutability, so enforcement is writer-side + a check()-style conformance guard (open question §9.1).
6. Constraint-driven graph — the "name the requirement that forces it" gate is a first-class edge: TechnologyChoice -[:FORCED_BY]-> RequirementItem. A technology choice or component with no FORCED_BY/SATISFIES edge is the graph-level signal of an unjustified decision (the plugin's core review rule, made queryable).
7. DDL is generated from the identity table — same discipline as canonical_schema.py: constraints are rendered CREATE CONSTRAINT <name> IF NOT EXISTS FOR (n:Label) REQUIRE n.<key> IS UNIQUE from a single {label: key} map, so DDL can never drift from identity (§5).
8. This ontology targets the Neo4j OPERATIONAL graph only. RDF/OWL/TTL/SHACL and Stardog (from ontology-stardog-ttl.md) are a different stack — that is SPEC-105 domaingen/ + the Memgraph/Stardog semantic side, explicitly out of scope per kg-schema-gaps.md. See §9.4 for what, if anything, belongs on the Memgraph side.

3. Node types

Legend — Reuse: REUSE (existing canonical label, unchanged), REUSE+EXT (existing label, this proposal extends/re-scopes it — migration noted), NEW. Scope: project (id = {project}:…) or global.

Count: 21 NEW · 4 REUSE+EXT · 6 REUSE = 31 node types touched (25 written by this ontology; 5 reference-data / global; the rest project-scoped).

4. Relationship types

Direction is from → to. Cardinality per canonical instance. Relationship names REUSE existing REL_* constants where one fits (marked); new names follow the SCREAMING_SNAKE convention of canonical_schema.py.

Count: ~38 new/retargeted + 6 reused = ~44 relationship types.

5. Constraints & indexes (what apply() would emit)

Following canonical_schema.py, DDL is generated from a single {label: key} map. New uniqueness constraints (Neo4j 5 syntax), each idempotent:

-- Project-scoped (id = "{project}:{natural}")
CREATE CONSTRAINT api_contract_id           IF NOT EXISTS FOR (n:ApiContract)          REQUIRE n.id   IS UNIQUE;
CREATE CONSTRAINT data_entity_id            IF NOT EXISTS FOR (n:DataEntity)           REQUIRE n.id   IS UNIQUE;
CREATE CONSTRAINT quality_attribute_id      IF NOT EXISTS FOR (n:QualityAttribute)     REQUIRE n.id   IS UNIQUE;
CREATE CONSTRAINT constraint_id             IF NOT EXISTS FOR (n:Constraint)           REQUIRE n.id   IS UNIQUE;
CREATE CONSTRAINT capacity_model_id         IF NOT EXISTS FOR (n:CapacityModel)        REQUIRE n.id   IS UNIQUE;
CREATE CONSTRAINT cost_model_id             IF NOT EXISTS FOR (n:CostModel)            REQUIRE n.id   IS UNIQUE;
CREATE CONSTRAINT cost_line_item_id         IF NOT EXISTS FOR (n:CostLineItem)         REQUIRE n.id   IS UNIQUE;
CREATE CONSTRAINT environment_id            IF NOT EXISTS FOR (n:Environment)          REQUIRE n.id   IS UNIQUE;
CREATE CONSTRAINT deployment_id             IF NOT EXISTS FOR (n:Deployment)           REQUIRE n.id   IS UNIQUE;
CREATE CONSTRAINT architecture_decision_id  IF NOT EXISTS FOR (n:ArchitectureDecision) REQUIRE n.id   IS UNIQUE;
CREATE CONSTRAINT tradeoff_id               IF NOT EXISTS FOR (n:TradeOff)             REQUIRE n.id   IS UNIQUE;
CREATE CONSTRAINT risk_id                   IF NOT EXISTS FOR (n:Risk)                 REQUIRE n.id   IS UNIQUE;
CREATE CONSTRAINT failure_mode_id           IF NOT EXISTS FOR (n:FailureMode)          REQUIRE n.id   IS UNIQUE;
CREATE CONSTRAINT technology_choice_id      IF NOT EXISTS FOR (n:TechnologyChoice)     REQUIRE n.id   IS UNIQUE;
CREATE CONSTRAINT slo_id                    IF NOT EXISTS FOR (n:ServiceLevelObjective) REQUIRE n.id  IS UNIQUE;
CREATE CONSTRAINT alert_id                  IF NOT EXISTS FOR (n:Alert)                REQUIRE n.id   IS UNIQUE;
CREATE CONSTRAINT change_id                 IF NOT EXISTS FOR (n:Change)               REQUIRE n.id   IS UNIQUE;  -- fills the LABEL_CHANGE gap

-- Global reference data
CREATE CONSTRAINT waf_pillar_name           IF NOT EXISTS FOR (n:WAFPillar)            REQUIRE n.name IS UNIQUE;
CREATE CONSTRAINT region_code               IF NOT EXISTS FOR (n:Region)               REQUIRE n.code IS UNIQUE;
CREATE CONSTRAINT cloud_service_name        IF NOT EXISTS FOR (n:CloudService)         REQUIRE n.name IS UNIQUE;
-- Pattern.name (pattern_name) already declared canon; extend properties only, no new constraint.

-- Non-identity lookup indexes (query-shaped)
CREATE INDEX architecture_decision_status   IF NOT EXISTS FOR (n:ArchitectureDecision) ON (n.status);
CREATE INDEX component_project              IF NOT EXISTS FOR (n:Component)             ON (n.project);
CREATE INDEX technology_choice_category     IF NOT EXISTS FOR (n:TechnologyChoice)     ON (n.category);
CREATE INDEX cloud_service_neutral_kind     IF NOT EXISTS FOR (n:CloudService)         ON (n.neutral_kind);
CREATE INDEX risk_impact                    IF NOT EXISTS FOR (n:Risk)                 ON (n.impact);

Re-scoping migrations (breaking — gated, not auto-applied): Architecture id name → "{project}:{name}"; Component id name → "{project}:{name}". These change existing canonical keys and touch the 5 live Component nodes + the sync writer's Architecture node, so they run through the existing migrate_neo4j_canonical.py + check() conformance path, never a blind apply() (open questions §9.2). The Change constraint is additive (label existed with no key). All other constraints are net-new labels — zero migration.

6. Core ontology diagram

Global reference-data nodes (WAFPillar, Region, CloudService, Pattern) are labeled (global); every other node is project-scoped.

7. Coexistence with scripts/sync_architecture_to_neo4j.py

The current writer creates a single global Architecture{name} plus Component{name}, Rule{name}, Pattern{name} and the edges HAS_COMPONENT, HAS_RULE, HAS_PATTERN, MUST_FOLLOW, USES_PATTERN. This proposal supersedes it as follows:

• Architecture — re-scope id to {project}:{name}; the writer's global name-keyed node ("Orchestrata Ultimate") becomes the orchestrata-ultimate project's Architecture. Migration through migrate_neo4j_canonical.py.
• Component — re-scope to {project}:{name}; the writer's 5 nodes (VizInt UI, Gateway, Kernel, Redis, Neo4j) get the orchestrata-ultimate prefix and gain responsibility/compute_platform (already present as responsibility).
• Rule → Constraint — the writer's architecture "rules" ("Gateway never serves HTML/JS/CSS", "Never hardcode service IPs") are design invariants, not Prolog rules. They MUST NOT keep the Rule label (which the canon reserves for Tier-A Prolog rules keyed on id). They move to Constraint{kind:"invariant"}; the MUST_FOLLOW edge is retargeted Component → Constraint. This resolves a live label collision (§9.3).
• Pattern — the writer's operational protocols (PID file, Health check, Graceful shutdown…) are kept, re-tagged category:"operational", alongside the cloud/GoF catalog entries. Edge USES_PATTERN is deprecated in favour of IMPLEMENTS (converge later; keep the synonym until writers migrate).
• HAS_RULE/HAS_PATTERN (Architecture→Rule/Pattern) — replaced by Architecture→Constraint via CONSTRAINS and Component→Pattern via IMPLEMENTS.

Until a converged writer exists (out of scope here — schema draft only), the two can coexist read-only: the writer keeps producing global nodes; nothing in this draft is applied. The converged writer is a separate follow-up that the user green-lights after this schema is ratified.

8. Worked example — a notification service (the README's example)

Project slug acme-notify. ~22 nodes/edges in Cypher-MERGE pseudocode, demonstrating every identity key. (Reference data — CloudService, Pattern, WAFPillar, Region — is MERGEd globally, unqualified.)

// --- reference data (global; shared across all 100+ projects) ---
MERGE (sb:CloudService {name: "Azure Service Bus"})
  SET sb.vendor="azure", sb.neutral_kind="message-broker", sb.category="messaging";
MERGE (pg:CloudService {name: "Azure Database for PostgreSQL - Flexible Server"})
  SET pg.vendor="azure", pg.neutral_kind="relational-db", pg.category="database";
MERGE (qll:Pattern {name: "Queue-Based Load Leveling"})
  SET qll.category="cloud", qll.problem_area="messaging", qll.pillars=["Reliability","Cost","Performance"];
MERGE (cc:Pattern {name: "Competing Consumers"}) SET cc.category="cloud", cc.problem_area="messaging";
MERGE (rel:WAFPillar {name: "Reliability"}) SET rel.concern="resiliency, availability, recovery";
MERGE (eu:Region {code: "westeurope"}) SET eu.geography="Europe", eu.has_availability_zones=true;

// --- project + system root (project-scoped) ---
MERGE (p:Project {slug: "acme-notify"});
MERGE (a:Architecture {id: "acme-notify:Notification Service"})
  SET a.name="Notification Service", a.version="1.0.0", a.status="draft";
MERGE (p)-[:HAS_ARCHITECTURE]->(a);

// --- components ---
MERGE (api:Component {id: "acme-notify:Notify API"})
  SET api.name="Notify API", api.responsibility="Accept + validate send requests", api.compute_platform="Container Apps";
MERGE (wrk:Component {id: "acme-notify:Dispatch Worker"})
  SET wrk.name="Dispatch Worker", wrk.responsibility="Drain queue, call providers", wrk.compute_platform="Container Apps";
MERGE (a)-[:HAS_COMPONENT]->(api);
MERGE (a)-[:HAS_COMPONENT]->(wrk);
MERGE (api)-[:DATA_FLOWS_TO {protocol:"AMQP", sync:false, critical_path:true, via:"Azure Service Bus"}]->(wrk);

// --- requirement (BDD) + NFR gate ---
MERGE (r:Requirement {id: "acme-notify:REQ-send"}) SET r.title="Send notification", r.critical_path=true;
MERGE (ri:RequirementItem {id: "acme-notify:REQ-send-01"}) SET ri.text="A send survives a provider outage of up to 1h";
MERGE (r)-[:HAS_ITEM]->(ri);
MERGE (sc:Scenario {id: "acme-notify:SC-send-outage"})
  SET sc.given="the email provider is down", sc.when="a send is requested", sc.then="the request is queued and retried within 1h", sc.is_edge_case=true;
MERGE (ri)-[:HAS_SCENARIO]->(sc);
MERGE (qa:QualityAttribute {id: "acme-notify:availability-send"})
  SET qa.name="Send availability", qa.metric="success-rate", qa.target="99.9% / 30d", qa.pillar="Reliability";
MERGE (ri)-[:HAS_QUALITY_ATTRIBUTE]->(qa);
MERGE (qa)-[:ADDRESSES_PILLAR]->(rel);
MERGE (api)-[:SATISFIES]->(ri);

// --- decision (ADR) + the "name the requirement" gate ---
MERGE (tc:TechnologyChoice {id: "acme-notify:async-via-servicebus"})
  SET tc.name="Async dispatch via Service Bus", tc.category="messaging", tc.reversibility="one-way";
MERGE (tc)-[:SELECTS]->(sb);
MERGE (tc)-[:FORCED_BY]->(ri);              // <-- the gate: choice justified by REQ-send-01
MERGE (adr:ArchitectureDecision {id: "acme-notify:ADR-0001"})
  SET adr.adr_number=1, adr.title="Async notifications via a durable queue",
      adr.status="Accepted", adr.date=date("2026-07-18"), adr.one_way_door=true,
      adr.decision="Dispatch through Azure Service Bus; API only enqueues",
      adr.consequences="Eventual consistency; consumers must be idempotent";
MERGE (adr)-[:CHOSE]->(tc);
MERGE (adr)-[:REJECTED {reason:"direct RPC cannot survive a 1h provider outage"}]->(pg);
MERGE (adr)-[:JUSTIFIED_BY]->(ri);
MERGE (adr)-[:APPLIES]->(qll);
MERGE (wrk)-[:IMPLEMENTS]->(cc);

// --- ops: SLO + alert + deployment ---
MERGE (slo:ServiceLevelObjective {id: "acme-notify:Notify API:send-success"})
  SET slo.sli="send success rate", slo.target="99.9%", slo.window="30d", slo.error_budget="0.1%";
MERGE (api)-[:HAS_SLO]->(slo);
MERGE (slo)-[:MEASURES]->(qa);
MERGE (al:Alert {id: "acme-notify:send-fastburn"})
  SET al.alert_on="2% budget in 1h", al.tier="page", al.runbook_url="docs/runbooks/send.md";
MERGE (al)-[:ALERTS_ON]->(slo);
MERGE (dep:Deployment {id: "acme-notify:Dispatch Worker:prod"}) SET dep.delivery_model="pull-gitops", dep.resiliency="multi-zone";
MERGE (wrk)-[:DEPLOYED_AS]->(dep);
MERGE (dep)-[:IN_REGION]->(eu);

Every project-scoped id is {project}:{natural}; every reference node is global. Re-running this MERGE block is idempotent (the identity keys guarantee it).

9. Open questions — RULED 2026-07-19

All eight questions were answered on 2026-07-19 (session 242). Rulings: (1) ADR immutability: BOTH — writer-side guard on Accepted-body SET and a body_sha conformance gate. (2) Component: UNIFY design-time with runtime-ownership Component and project-qualify to {project}:{name}; migrate the 5 live bare-name nodes via migrate_neo4j_canonical.py. (3) Fold sync-writer architecture rules into Constraint{kind:"invariant"}; Rule reserved for Prolog. (4) Semantic twin: YES as phase 2 — ADR/ DesignDoc prose chunked into Memgraph keyed by the Neo4j id; not blocking phase 1. (5) ArchitectureDecision and Decision stay two distinct labels. (6) CloudService: lazy creation + a curated ~30-service seed with neutral_kind; full-catalog ingestion rejected. (7) Confirmed: OpenSpec owns LABEL_CHANGE, id = "{project}:{change_id}". (8) Converged writer: BOTH, phased — rewrite sync_architecture_to_neo4j.py onto this ontology first, then extend pipeline/session KG writers; triggers = on-demand /system-design runs write immediately, and session start initiates a FULL architecture sync (user amendment 2026-07-19, superseding the earlier seed-only trigger): the whole design corpus is idempotently MERGEd on boot — cheap at this layer's scale (unlike the code graph, which stays incremental per SPEC-023) — run BACKGROUNDED so session start never blocks on Neo4j, with ruling 1's guard enforced inside it (never mutates an Accepted ADR body).

Original questions (as posed)

1. ADR immutability enforcement. Neo4j has no per-property immutability. Do you want (a) writer-side guard only (the writer refuses to SET body props on an ArchitectureDecision whose status=Accepted), (b) a check()-style conformance gate that flags any Accepted-ADR body drift (comparing against a content hash property body_sha), or (c) both? Recommendation: (c) — hash on accept, gate in the conformance check, mirroring canonical_schema.check().
2. Component re-scoping (breaking). Canon currently keys Component on bare name (5 live Tier-C nodes used by query_engine.volk_work_context). This proposal project-qualifies it to {project}:{name} (multi-project invariant, Package/File/Directory precedent). Also, is the design/architecture Component the SAME node as the runtime-ownership Component ((volk)-[:OWNS]->(:Component)) — i.e. one unified Component per system module — or two distinct labels? Recommendation: unify (one Component, project-qualified); the volk owns the same architectural component it works on. This is the single most consequential reconciliation and needs your sign-off before any migration.
3. Rule label collision. The sync writer's architecture "rules" currently share the Rule label with Tier-A Prolog rules. This draft moves them to Constraint{kind:"invariant"}. Confirm that's the wanted resolution (vs. a new ArchitectureRule label). Recommendation: fold into Constraint — fewer labels, and they are design invariants.
4. RDF/Memgraph vs Neo4j split. ontology-stardog-ttl.md describes OWL/TTL/ SHACL/SPARQL — that stack is SPEC-105 domaingen/ + Stardog, and the Memgraph HA graph holds the semantic/RAG chunks. This ontology is Neo4j-only and models design records as operational data. Nothing architectural here belongs on Memgraph except: if you want semantic retrieval over ADR/design-doc prose ("find decisions about queue back-pressure"), the ADR/DesignDoc text should also be chunked into the Memgraph semantic graph (as SemanticChunk), with the Neo4j ArchitectureDecision.id as the cross-graph key. Confirm whether ADR prose gets that semantic-layer twin, or stays Neo4j-only.

   Phase-2 implementation note (2026-07-19): the twin label is ArchitectureChunk (own vector index architecture_chunk_embedding_idx), NOT the SemanticChunk this parenthetical suggested: SemanticChunk sits in the ingest pruner's STALE_CHUNK_LABELS and its match predicate (has id, no chunk_id, no DERIVED_FROM) would have flagged live twin chunks for deletion under --prune-stale-labels --apply. Ruling 4's mandate (Neo4j id as the cross-graph key, same embedder/vector space as the code ingest) is unchanged. Implemented in semantic_graph/architecture_twin.py + scripts/sync_architecture_semantic_twin.py.

5. ArchitectureDecision vs canon Decision. Kept DISTINCT here (Decision = Tier-C runtime/pipeline/governance decision; ArchitectureDecision = design ADR). Confirm you want two labels (recommended — different lifecycles, different immutability rules) rather than overloading Decision with a kind.
6. CloudService catalog ingestion. Is the Azure service catalog (714 icons / the services named across the 26 refs) ingested as global reference data (one-time seed, versioned), or only created lazily when a project's TechnologyChoice SELECTS one? Recommendation: lazy + a small curated seed of the ~30 services the refs actually name, tagged with neutral_kind so vendor-neutral queries work; full-catalog ingestion is a separate call.
7. Change canonical key. LABEL_CHANGE exists in canon with NO merge key. This draft assigns id = "{project}:{change_id}". Confirm the OpenSpec change is the intended owner of that label (vs. a generic git/spec change).
8. Scope of the converged writer. This is a schema draft only. When ratified, do you want the follow-up to (a) rewrite sync_architecture_to_neo4j.py onto this ontology, (b) add architecture extraction to the pipeline/session KG writers, or (c) both — and on what trigger (session-start seed vs. on-demand /system-design run)?

10. Non-goals (explicit)

• No ingestion code, no writer changes. This is the schema draft that must precede import. sync_architecture_to_neo4j.py is untouched; no converged writer is written here.
• No apply() run / no migration executed. The DDL in §5 and the migrations in §7 are proposals; nothing is applied to any live graph.
• No RDF/OWL/SHACL/Stardog artifacts. That is SPEC-105 domaingen/ + the Memgraph/Stardog side, out of scope (§9.4).
• No Memgraph semantic-graph changes. Cross-graph twinning of ADR prose (§9.4) is flagged as an option, not designed here.
• No canonical_schema.py edit. The reuse/extend/new decisions are a proposal for the user to ratify; folding them into the canon is a separate, gated step.
• Not a design-doc/ADR authoring tool. This models architecture as graph data; the plugin's authoring workflow is unchanged.

## Related

- [Plans](/projects/orchestrata-ultimate/plans/index)
- [Orchestrata Ultimate — project index](/projects/orchestrata-ultimate/index)
- [Workflow](/projects/orchestrata-ultimate/workflow)
- [Tasks](/projects/orchestrata-ultimate/tasks)