ADR-001 — Canonical Repository Layout¶

Status: Superseded by ADR-002

Date: 2026-07-04

Owner: Architecture Board

Decision Type: Foundational

Context¶

UC-BoK has evolved from a documentation repository into a model-driven knowledge platform.

The repository now contains:

• normative specifications
• machine-readable schemas
• canonical knowledge catalogs
• executable query engine
• knowledge graph
• generated documentation

Without a clear separation of responsibilities between these areas, the repository will progressively accumulate duplicated knowledge, inconsistent sources of truth and fragile generators.

This ADR establishes the canonical repository layout.

Decision¶

Every top-level directory MUST have exactly one responsibility.

The repository SHALL distinguish between:

• normative knowledge
• canonical knowledge
• executable components
• generated artifacts
• published documentation

No directory may mix these concerns.

Top-Level Directory Rule¶

A top-level directory represents an architectural responsibility.

It must never represent a domain of knowledge.

Knowledge domains are organized inside their architectural layer.

Examples:

• specifications/007-ontology/ is correct — ontology lives inside the normative layer.
• A top-level ontology/ would be wrong — ontology is not a new architectural responsibility, it is part of specifications.
• catalogs/business-objects/ is correct — business objects are a knowledge domain inside the canonical knowledge layer.

If a concept cannot be assigned to an existing architectural responsibility, a new ADR is required before creating a new top-level directory.

Canonical Layout¶

uc-bok/

AGENTS.md
PROJECT.md
README.md

.context/
.github/
.skills/

planning/

specifications/

schemas/

catalogs/

queries/

graph/

scripts/

tests/

docs/

site/

Directory Responsibilities¶

specifications/¶

Normative architecture.

Contains the official definition of:

• meta model
• naming rules
• lifecycle
• relationships
• conventions

These documents define the architecture.

They are never generated.

schemas/¶

Machine-readable schemas.

Examples:

• JSON Schema
• YAML Schema

Used only for validation.

No business knowledge belongs here.

catalogs/¶

Canonical Unified Commerce knowledge.

Contains the authoritative catalog of:

• Business Objects
• Events
• Capabilities
• Processes
• Applications
• APIs
• Vendors

This directory is the business source of truth.

graph/¶

Executable graph implementation.

Contains graph builders, relationship algorithms, exporters, graph utilities.

Contains no business definitions.

queries/¶

Executable query engine.

Allows querying the canonical catalog.

Contains runtime logic only.

Contains no business definitions.

scripts/¶

Automation.

Generators.

Validators.

Migration tools.

No business knowledge.

docs/¶

Human-readable documentation.

Documentation explains the platform.

It does not define the platform.

Whenever possible documentation is generated.

site/¶

Generated MkDocs site.

Never edited manually.

May be deleted at any time.

tests/¶

Validation scenarios.

Regression tests.

Schema validation.

Knowledge validation.

planning/¶

Project planning.

Roadmap.

Epics.

Issues.

Releases.

Contains no business knowledge.

.context/¶

Working memory for AI agents.

Reports.

Assessments.

Temporary artifacts.

Never considered authoritative.

Source of Truth¶

The repository has multiple sources of truth, each valid for a specific concern.

No other directory may become authoritative.

Generated Content¶

Generated artifacts must never become editable sources.

If a file can be regenerated, it should not be manually maintained.

Deprecated Concepts¶

The following repository layouts are deprecated.

docs/specifications/¶

Specifications belong to

specifications/

Documentation may reference them but must not duplicate them.

docs/generated/¶

Generated documentation should progressively move to the build pipeline.

Generated artifacts are implementation details, not repository knowledge.

models/¶

The historical models directory is deprecated.

Its responsibilities must be progressively split into:

• schemas/
• catalogs/

Migration should be incremental to avoid breaking generators.

Migration Strategy¶

Phase 1

Freeze current structure.

Phase 2

Migrate business knowledge to catalogs/.

Phase 3

Migrate machine schemas to schemas/.

Phase 4

Retire models/.

Phase 5

Simplify generators.

Non Goals¶

This ADR does not define:

• the Unified Commerce meta-model
• Business Objects
• Events
• Capabilities

These are defined elsewhere.

Consequences¶

Positive

• single responsibility

• explicit source of truth

• AI-friendly repository

• simpler generators

• easier validation

• easier onboarding

Negative

• temporary coexistence of models/ and catalogs/

• migration effort

Status¶

Accepted.

All future architectural work must comply with this ADR.