OpenSPAD / DOCS 2.0← Documentation Hub
Role Guide 01 · Administration

Administrator Guide

Govern shared Concepts, review semantic changes, validate graph rules, manage data-source provenance, and protect existing project references.

Global KnowledgeConcept LifecycleReview & PublicationAudit & RecoveryBaseline 7.8.53
ROLE OPERATING MODEL

Curate once. Reuse safely.

Global Concepts and Reference Use Cases form a governed shared knowledge layer. Project information uses stable published version references, with explicit approval for migration.

AdministratorCurate & publish shared knowledge
BIM ManagerProject-specific use cases & validation
Standard UserCompose approved use cases

Version rule: published Concept versions are immutable. New revisions must undergo review, and existing Use Cases stay pinned until explicitly upgraded and revalidated.

SECTION 01

Administrator mission

The Administrator curates shared semantic knowledge and governs its use across projects. This role controls publication of global Concepts, source registration, rules, and operational safeguards. A BIM Manager proposes project needs; a Standard User composes approved resources.

VERIFIED SCOPE: conceptual documentation. Actual role-based enforcement is not established by the 7.8.53 pilot.
SECTION 02

Access & responsibility

Administrator: review and publish global knowledge, authorize global data sources, administer business rules and inspect audit history. BIM Manager: assemble project-specific use cases, bring project data and request changes. Standard User: reuse published reference use cases and compose a project IDM; no global editing.

PLANNED: complete RBAC policy engine, project access enforcement and tenant isolation.
SECTION 03

Create a global Concept

  1. Capture the intent, stable identifier and accountable owner.
  2. Select a semantic type, root eligibility and provenance.
  3. Choose relevant source ontologies and classes.
  4. Associate IFC property sets, properties, required values and optional alignment evidence.
  5. Propose graph rules such as ALLOWS_CHILD or EXCLUDES.
  6. Save a Draft; run structural, semantic and dependency checks.
  7. Submit for review; publish an immutable version only after approval.
PILOT: versioned draft concept graph and narrow relationship-rule tests; comprehensive guided review and publication controls are planned.
SECTION 04

Correct a published Concept

  1. Open an immutable published version.
  2. Create a new Draft revision rather than editing the published snapshot.
  3. Record a change reason and source evidence.
  4. Diff classes, properties, mappings and graph rules.
  5. Compute impacted Use Cases and other Concept references.
  6. Review and publish a new version.
  7. Offer projects an explicit migration with revalidation; never silently repoint their references.
ARCHITECTURE DECISION: published revisions immutable; existing Use Cases remain pinned until explicit migration.
SECTION 05

Register a new data source

  1. Classify source scope: global vocabulary versus project-instance data.
  2. Register source URI, authority, access restrictions, version and refresh policy.
  3. Extract and normalize candidate graph fragments.
  4. Align candidates with existing Concepts, recording confidence and evidence.
  5. Review unmatched and conflicting terms.
  6. Propose amendments as new Concept drafts; approve only reviewed mappings.
  7. Re-run impact checks before exposing updated knowledge.
PLANNED: generalized connectors and automatic impact pipeline; do not imply BigQuery, NATSPEC or server federation are operational today.
SECTION 06

Graph business rules

Use explicit directed relationships and typed semantics. Examples: ALLOWS_CHILD establishes a permitted composition; EXCLUDES prevents a pairing; REQUIRES and PRECEDES describe dependencies. Root eligibility is separately governed. Enforce cycle checks for hierarchy-like relations, while preserving valid multiple-parent graph relationships.

PILOT: Heating Systems → Boilers permitted, Heating Systems → Accessibility blocked in tested 7.8.53 pilot. Global rule validation is not yet complete.
SECTION 07

Version review & impact

For every proposed publication, inspect changed attributes, source citations, changed graph edges, affected Use Cases, constraints, IDS definitions, and project-specific pins. Make the review decision explicit: approve, request changes or reject. Store reviewer identity, timestamp, rationale and source-version evidence.

PLANNED: automated complete change-impact report and managed project migration.
SECTION 08

Global vs project boundaries

Shared graph: published ontologies, classifications, reusable Concepts and Reference Use Cases. Project graph: IFC instance models, Excel/JSON instance records, project mappings, project use cases, project IDS/IDM and validation evidence. Link project nodes to pinned global versions without rewriting global definitions.

ARCHITECTURE DECISION: project knowledge must not automatically modify shared knowledge.
SECTION 09

Operations & recovery

Verify service health, documentation routes and Neo4j instance before any disruptive operation. Back up database and configuration with integrity verification. Record a recovery procedure and perform a separate restore rehearsal. Preserve audit trails; do not reset credentials, stop Neo4j or alter live project data as part of documentation maintenance.

VERIFIED BASELINE: Neo4j 5.26 instance and offline dumps in 2026-10-17 operational snapshot; a fully exercised restore is still pending.
SECTION 10

Federation & security

Long-term design: independently managed OpenSPAD servers expose authorized graph fragments through identity-aware and versioned interfaces. Provider-managed manufacturer product graphs may disclose selected public nodes while withholding private records. Authorization must govern traversal, derived results, caches, queries and exports.

FUTURE ARCHITECTURE: distributed query and cross-tenant access isolation are not deployed features.
SECTION 11

Administrator acceptance checklist

Before publishing: confirm stable identity and type; source provenance; direct/derived mappings; relationship constraints; root eligibility; version diff; impacted references; approvals; audit entry; and rollback/recovery notes. If a check is inconclusive, keep the revision in Draft/Review.

TARGET PROCEDURE: checklist is a specification, not a guarantee of currently automated controls.
REFERENCE MATERIAL

Related architecture chapters