A governed knowledge plane that gives people and AI a stable map of technical concepts, systems, relationships, evidence, and ownership—without replacing the operational systems that remain authoritative for code, configuration, APIs, telemetry, incidents, or decisions.
The document is continuous, but each audience has a different shortest path. The encyclopedia itself should follow the same principle: guide first, then permit deeper exploration.
Read the decision, operating-model comparison, outcomes, risks, and success metrics.
Read the knowledge model, content semantics, reference architecture, and staged platform choices.
Use the schema, content templates, ingestion contracts, retrieval pipeline, and implementation plan.
Use governance roles, lifecycle states, review triggers, evidence rules, and health metrics.
A wiki alone is too unstructured. A graph alone is too opaque. A catalog alone covers software entities, not domain understanding. The recommended design combines each where it is strongest.
Identity, terminology, scope, conceptual explanations, relationship types, article ownership, evidence mappings, and the location of authoritative sources.
Deployment versions, API schemas, endpoints, runtime health, incident status, repository metadata, ownership directories, and other rapidly changing operational facts.
No single reference model solves the whole problem. The blueprint combines proven mechanisms from encyclopedias, technical documentation systems, taxonomies, structured data, software catalogs, and knowledge-centered operations.
| Reference model | Mechanism to reuse | Do not copy blindly | Enterprise adaptation |
|---|---|---|---|
| Wikipedia Collaborative encyclopedia | Lead summaries, progressive depth, article splitting, cross-linking, verifiability, revision history.1, 2 | Unrestricted editing, implicit ownership, uneven review depth. | Keep summary style; add accountable owners, review gates, access controls, and typed evidence. |
| Stanford Encyclopedia Expert-curated reference | Subject editors, expert authors, referee process, living entries plus stable archive editions.3 | Heavy editorial cost for every item. | Apply rigorous review to high-consequence domains; use lighter workflows for lower-risk content. |
| DITA and Diátaxis Information typing | Separate concepts, tasks, reference, troubleshooting, tutorials, how-to, explanation.6, 7 | Forcing every artifact into one universal template. | Give each content type its own schema, required sections, review cadence, and retrieval behavior. |
| MDN Technical reference | Different page structures for reference, concepts, guides, glossaries, and landing pages.8 | Assuming public web technology is equivalent to private enterprise systems. | Add internal status, owner, policy, environment, applicability, and security metadata. |
| SKOS and ACM CCS Knowledge organization | Broader, narrower, related concepts and polyhierarchical classification.4, 10 | Using one rigid tree as the domain model. | Use a browsable taxonomy plus typed cross-domain relationships and search aliases. |
| Wikidata Structured statements | Claims augmented with qualifiers, references, and ranks.9 | Reducing all knowledge to property-value statements. | Keep narrative articles for understanding; use claims for queryable, auditable assertions. |
| Backstage Software catalog | Uniform entity metadata, ownership, discoverability, docs near code.11 | Treating catalog entities as sufficient domain explanation. | Project catalog data into system entries; preserve the encyclopedia as a broader conceptual layer. |
| KCS Living operations | Improve knowledge during use; treat the system as continuous rather than a one-time migration.12 | Optimizing only for support cases. | Apply reuse-driven improvement across engineering, architecture, operations, and AI retrieval. |
The core model prevents prose, software inventory, source records, and assertions from becoming indistinguishable.
Display names change. Identifiers should not. Use namespaced IDs such as system:content-api.
Distinguish depends-on, part-of, implements, governed-by, and supersedes.
Record when a statement was valid in the domain and when the platform learned or published it.
Attach evidence to consequential claims, not only to the page footer.
Declare which system is authoritative for each fact category rather than claiming one universal source of truth.
Start with a compact property graph. Introduce formal ontology semantics only when inference or validation justifies the complexity.
| Primitive | Required properties | Typical query | Primary failure prevented |
|---|---|---|---|
| Concept | ID, preferred label, aliases, definition, domains | “What is token exchange?” | Terminology drift and duplicate definitions |
| Entity | ID, kind, owner, lifecycle, authoritative links | “Who owns the identity gateway?” | Orphan systems and ambiguous names |
| Article | Lead, typed sections, audience, owner, review state | “Explain how this system fits into the platform.” | Fragmented facts without narrative |
| Claim | Type, statement, scope, status, confidence, validity | “Which services depend on this at runtime?” | Unqualified assertions hidden in prose |
| Evidence | Class, locator, publisher, retrieval time, hash | “What supports this architecture assertion?” | Unverifiable or circular knowledge |
| Relationship | Predicate, source, target, qualifiers, evidence | “What does this component consume and produce?” | Ambiguous, untyped links |
A content type defines semantics, required metadata, expected sections, review policy, relationships, retention, and retrieval behavior—not merely visual layout.
Explains an abstract idea, mechanism, vocabulary, boundaries, and trade-offs.
Explains the purpose, boundary, architecture, ownership, dependencies, and operational posture of a specific system.
Describes a constituent part of a system and the responsibility it owns.
Captures a reusable solution shape, its context, forces, consequences, and counter-patterns.
Defines normative rules, applicability, exceptions, controls, and compliance evidence.
Provides exact, scannable facts such as interfaces, fields, commands, states, and limits.
Guides a qualified user through a goal with prerequisites, steps, verification, and recovery.
Supports operation and recovery under time pressure with signals, diagnostics, mitigation, and escalation.
Maps observable symptoms to likely causes, tests, remedies, and escalation criteria.
Records context, considered options, decision, rationale, consequences, and supersession.
Preserves what happened, impact, timeline, contributing factors, learning, and follow-up.
Provides a concise organization-specific definition, aliases, and links to deeper concepts.
Normalizes a source locator, class, publisher, retrieval time, hash, and limitations.
The lead must function as a complete orientation layer. Deeper sections then explain structure, mechanism, trade-offs, failure, enterprise application, and provenance. Wikipedia’s summary style and MDN’s differentiated page types support this layered approach.1, 8
| Section | Purpose | Required content | Evidence expectation |
|---|---|---|---|
| Identity | Resolve the subject unambiguously. | Title, one-sentence definition, aliases, type, domain, state, owner. | Authoritative identity source where applicable. |
| Lead | Provide a self-contained orientation. | What it is, why it matters, where it fits, distinguishing characteristics. | Cite consequential or contestable claims. |
| Context and scope | Establish boundaries. | Problem, drivers, audience, inclusions, exclusions, non-goals. | Policy, charter, decision, or approved architecture source. |
| Conceptual model | Explain structure. | Components, roles, boundaries, state, data and control flows. | Architecture models plus validation against implementation. |
| Mechanism | Explain behavior. | Sequence, protocol, state changes, invariants, runtime interactions. | Specifications, code, tests, or observed behavior. |
| Relationships | Connect the domain. | Broader, narrower, related, dependencies, implementations, owners. | Each consequential edge should be sourced or projected. |
| Alternatives and trade-offs | Support decisions. | Credible options, benefits, drawbacks, selection criteria, reversibility. | Evidence quality and assumptions must be explicit. |
| Security and operations | Expose consequential qualities. | Trust boundaries, controls, failure modes, observability, recovery links. | Threat models, standards, runbooks, telemetry. |
| Enterprise application | Connect general knowledge to local reality. | Approved uses, restricted uses, implementations, adoption state. | Catalog, policy, deployment, and governance sources. |
| Provenance and lifecycle | Make trust inspectable. | Sources, authors, reviewers, validity, last review, archived versions. | Mandatory for canonical publication. |
Fact: externally or internally verifiable assertion. Observation: measured or directly witnessed state. Interpretation: analysis derived from evidence. Recommendation: proposed action. Prediction: future expectation. Assumption: condition treated as true for the current analysis.
Normative: standard or policy. Authoritative record: system of record. Observed: telemetry, test, trace, or inspection. Reported: interview, ticket, or narrative. Analytical: synthesis or derived result. Predictive: forecast or modeled future state.
type KnowledgeType =
| "concept" | "system" | "component"
| "pattern" | "standard" | "reference"
| "procedure" | "runbook" | "troubleshooting"
| "decision" | "incident" | "glossary" | "evidence";
type ClaimType =
| "fact" | "observation" | "interpretation"
| "recommendation" | "prediction" | "assumption";
interface KnowledgeObject {
id: `${string}:${string}`;
type: KnowledgeType;
title: string;
summary: string;
aliases?: string[];
lifecycle: Lifecycle;
classification: Classification;
ownership: Ownership;
content: ContentBlock[];
relationships: Relationship[];
claims: Claim[];
provenance: Provenance;
}
interface Claim {
id: `claim:${string}`;
claimType: ClaimType;
statement: string;
status: "unverified" | "supported" | "verified" |
"disputed" | "deprecated";
confidence?: number;
scope?: string;
validFrom?: string;
validUntil?: string;
evidenceRefs: string[];
}The full Draft 2020-12 schema and a canonical sample entry are included beside this HTML file. They can be used as the starting contract for validation, editors, ingestion pipelines, and API payloads.
Publication state and confidence are separate. A page may be published but unverified, or canonical but approaching review. Expert review should scale with consequence.
| Role | Accountability | Decision rights | Scale control |
|---|---|---|---|
| Contributor | Proposes and improves knowledge during work. | Create drafts and submit evidence. | Templates, automated checks, contribution guidance. |
| Article owner | Accuracy and lifecycle of a named entry. | Accept routine changes and initiate review. | Ownership tied to role or group, not a single individual. |
| Domain steward | Terminology, taxonomy, coverage, and consistency within a domain. | Resolve duplicates, aliases, and domain relationships. | Domain health dashboards and bounded scope. |
| Technical reviewer | Engineering correctness and applicability. | Verify technical claims. | Risk-tiered review; code owners and guilds. |
| Evidence reviewer | Source quality, claim support, and provenance. | Approve evidence class and confidence. | Automated source checks plus spot audit. |
| Security reviewer | Sensitive content, trust boundaries, and access policy. | Approve restricted publication and security guidance. | Triggered only by classification or content rules. |
| Editorial council | Cross-domain policy, taxonomy governance, and disputes. | Approve standards and settle semantic conflicts. | Exception-based escalation, not page-by-page control. |
| Platform steward | Reliability, schemas, indexing, versioning, audit, and integrations. | Operate the platform and enforce technical controls. | Automation, SLOs, and migration compatibility. |
Glossary terms and basic guides can use owner review plus automated quality checks.
System architecture, operational guidance, and reusable patterns require qualified reviewers.
Security, compliance, public interfaces, and normative standards require named authorities and immutable approval evidence.
The encyclopedia should orient retrieval. It should not be the only RAG corpus. The pipeline first identifies entities, concepts, intent, scope, and authorization; it then gathers the appropriate typed evidence.
Textual similarity is only one signal. Ranking should be aware of identity, authority, lifecycle, content type, applicability, and successful reuse.
score =
lexicalRelevance
+ semanticRelevance
+ titleAliasMatch
+ entityResolutionConfidence
+ sourceAuthority
+ lifecycleConfidence
+ typeAppropriateFreshness
+ organizationalApplicability
+ graphProximity
+ successfulReuse
- stalenessPenalty
- authorizationRisk
- contradictionPenaltyChunk by semantic section, not arbitrary length alone. Every chunk should retain the metadata required for filtering, explanation, and audit.
Authorization must be enforced before retrieval and again before response assembly. Vector indexes, caches, traces, and evaluation datasets can leak restricted facts even when the final user interface is permission-aware. Treat every derived representation as governed data.
The same concepts, entities, claims, and evidence should support a website, developer portal, API, IDE, CLI, MCP server, agent, audit view, and future interfaces.
| Capability | MVP implementation | Scale implementation | Adoption rule |
|---|---|---|---|
| Canonical objects | Git-managed YAML or JSON, schema validation, static generation | PostgreSQL JSONB with versioned event log | Move when concurrent workflow and cross-repository queries become limiting. |
| Full-text retrieval | SQLite FTS5 or client-side index for a bounded corpus | OpenSearch or Elasticsearch with field-level security | Move when corpus size, facets, relevance tuning, or authorization demand it. |
| Semantic retrieval | Embeddings stored with object and section metadata | Managed vector index or OpenSearch k-NN with hybrid ranking | Require offline evaluation before production AI use. |
| Relationship graph | PostgreSQL edge table or in-memory projection | Neptune, Neo4j, or another graph store | Add a graph database only when multi-hop traversal or graph algorithms justify it. |
| Archive | Git history and release tags | Immutable object versions in S3 with retention and legal hold | Required for audit, regulated data, and reproducible AI citations. |
| Events | Repository webhooks and scheduled synchronization | EventBridge or Kafka with idempotent ingestion consumers | Use events for source changes, not for unnecessary internal choreography. |
| Policy | Repository permissions and coarse object classification | Central policy decision point with object, field, and claim controls | Scale before ingesting restricted or mixed-classification corpora. |
The first milestone is not a graph database or an AI assistant. It is a small domain where users can find, trust, improve, and reuse high-value knowledge.
A large corpus can be a liability. Health metrics should reveal whether the knowledge is owned, current, supported, discoverable, reusable, and safe.
How much of the critical domain has a canonical, owned orientation layer?
How many consequential claims have adequate supporting evidence?
How much canonical content is inside its type-specific review window?
Can representative users reach the correct answer with low interaction cost?
Does knowledge reduce repeated explanation and resolution work?
How often do supported claims disagree for the same scope and validity period?
Are objects owned by active, durable groups with valid escalation paths?
Do retrieval and generation honor classification and policy consistently?
Do citations support the specific generated claim rather than the general topic?
| Risk | Consequence | Control | Residual concern |
|---|---|---|---|
| Wiki-as-file-dump | High volume, low trust, weak retrieval. | Typed objects, required owners, lifecycle gates, domain coverage plans. | Contribution friction can reduce participation; automate routine metadata. |
| Duplicated live state | Conflicting endpoints, versions, owners, and operational guidance. | Project from authoritative systems; display source and synchronization time. | Source systems may themselves be incomplete or incorrect. |
| Graph without semantics | Misleading traversal and weak AI grounding. | Controlled predicates, qualifiers, validation, and evidence requirements. | Relationship vocabularies require ongoing governance. |
| AI-generated circularity | Hallucinated synthesis becomes a source for later synthesis. | Mark generation method; prohibit generated text as sole evidence; retain source lineage. | Human reviewers can still accept plausible but unsupported claims. |
| Authorization leakage | Restricted content exposed through indexes, caches, logs, or summaries. | Policy enforcement across ingestion, storage, retrieval, generation, cache, and evaluation. | Derived information can reveal sensitive relationships even without verbatim text. |
| Over-formal ontology | Delivery slows while the semantic model becomes detached from user tasks. | Start with minimum viable semantics and measurable query requirements. | Later schema evolution requires compatibility discipline. |
| Stale canonical content | High-confidence but incorrect guidance. | Volatility-based review, source change triggers, usage feedback, expiry states. | Silence from sources does not prove continued validity. |
The blueprint is a synthesis and design recommendation. Each cited source supports a specific mechanism; the overall architecture is an inference that combines them for enterprise technical knowledge.
Supports layered treatment: lead summary, major sections, and separate deeper articles when subjects grow.
Supports the distinction between sourced encyclopedic synthesis and unsupported original claims.
Supports expert authorship, editorial review, substantive update review, and durable editorial authority.
Supports concept schemes and direct broader, narrower, and related semantic relationships.
Supports interoperable representation of provenance across entities, activities, agents, and derivation contexts.
Supports explicit typing for concepts, references, tasks, troubleshooting, and glossary information.
Supports organizing documentation around distinct reader needs: tutorial, how-to, reference, and explanation.
Supports differentiated structures for references, conceptual pages, glossaries, guides, and landing pages.
Supports statements enriched with qualifiers, references, and ranks in a linked data structure.
Supports polyhierarchical technical classification and its use in semantic applications and search.
Supports centralized software metadata, ownership, discoverability, and documentation stored near code with contextual metadata.
Supports treating knowledge as a living system improved through use rather than a finite publishing project.
Supports machine-validatable structural contracts for knowledge objects and authoring tools.
Supports formal classes, properties, individuals, and logical semantics when stronger ontology reasoning is justified.