Skip to content
Beskid Platform specification

Beskid

Jump to a Beskid service

Beskid

Jump to a Beskid service

Domain, Area and Feature template bundle

Platform spec feature

Domain, Area and Feature template bundle

Back to Spec maintenance Open in platform map

Spec standingStandard

Owner
Piotr Mikstacki
Submitter
Piotr Mikstacki

Normative platform contract

Section titled “Normative platform contract”
  1. Every new or materially reworked platform-spec topic must choose one canonical level: Domain, Area, or Feature.
  2. Regular sections must be authored in markdown headings/lists/admonitions first; Astro components are reserved for edge cases only.
  3. Architecture visuals must use fenced code blocks with language arch (Mermaid C4 syntax) for static topology; procedural flows may use fenced mermaid (flowchart, sequenceDiagram, stateDiagram-v2). Inline graph components in docs are legacy-only.
  4. Feature pages may include article bundles, but article pages must not redefine canonical normative requirements that belong to the feature hub.
  5. Type names with generics in prose must use a single backtick literal per type (for example write Fiber-of-T as one fenced inline code span in source), not HTML-escaped angle brackets. Mermaid node labels must not contain raw less-than or greater-than characters; use plain names or quoted labels (for example "Channel T").

Required Domain sections

Section titled “Required Domain sections”

A Domain page must include the following sections in this order:

  1. Scope and boundaries - what this domain defines and what is out of scope.
  2. Terminology - core nouns and exact meanings used by child pages.
  3. Architectural principles - durable design rules for this domain.
  4. Area map - navigable list of areas with one-sentence responsibilities.
  5. Normative guarantees - stable contract guarantees expected by users and tooling.
  6. Conformance evidence - how compliance is demonstrated.
  7. Change policy - compatibility and migration expectations.
  8. Related domains - cross-domain dependencies and links.

Required Area sections

Section titled “Required Area sections”

An Area page must include:

  1. Area contract - subsystem mission, boundary, and external obligations.
  2. Responsibility boundaries - explicit handoffs to sibling areas or domains.
  3. Internal model - high-level stages, data flow, or topology.
  4. Feature index - canonical feature pages under this area.
  5. Failure and diagnostics model - error classes and reporting expectations.
  6. Verification matrix - tests/checks that validate the area contract.
  7. Operational guidance - usage, rollout, or maintenance notes.
  8. Related areas - sibling and upstream/downstream links.

Required Feature Hub sections

Section titled “Required Feature Hub sections”

The Feature Hub page must include all of the following sections in this order:

  1. Contract statement - concise statement of the feature obligation.
  2. Inputs and outputs - data and API surfaces consumed and emitted.
  3. State model - persistent/transient state and lifecycle constraints.
  4. Algorithms and flow - normative sequence and key decisions.
  5. Edge cases and errors - known exceptional behavior and diagnostics.
  6. Compatibility and versioning - forward/backward compatibility policy.
  7. Security and performance notes - mandatory cautions and limits.
  8. Examples - representative examples linked to canonical behavior.
  9. Verification and traceability - test anchors and drift detection.
  10. Related features - direct dependencies and sibling contracts.
  11. Decisions - hub summary plus adr/ directory (see below); required on every Standard feature hub.

Required Feature Hub — Decisions and adr/

Section titled “Required Feature Hub — Decisions and adr/”

Every Standard feature hub must:

  1. Include a ## Decisions section (summary only: open items, or no open decisions, plus pointers to adrId values).
  2. Publish at least one file under adr/<slug>.mdx with specLevel: adr (unless the feature is explicitly exempt in a Standard maintenance policy).

Each ADR file must include ## Context, ## Decision, and ## Consequences, with frontmatter adrId, adrStatus, and optional adrDate. Use Project inception for cross-cutting historical ADRs.

Legacy decisions-record.mdx articles may remain during migration; new decisions must not be added only to monolithic decision tables.

Reference: Concurrency package ADRs.

Anti-stub and circular canon rules

Section titled “Anti-stub and circular canon rules”

The following are forbidden on Standard pages:

  1. Circular canon — Body text that only self-references the same page URL as the sole authority without substantive normative MUST/SHOULD/MAY prose in the same file.
  2. Placeholder-only articles — Article bundles where every sibling file is scaffold-only (“What this article covers” + “see the parent feature hub” with no role-specific sections).
  3. Hub-only authority — Articles that repeat the feature hub contract without adding role-specific detail; normative requirements belong on the hub, articles add depth.

Minimum article payload by role

Section titled “Minimum article payload by role”

Each article in a bundle must meet a minimum for its role (in addition to Required Article sections):

Article roleMinimum normative payload
design-modelData/state model, invariants, and at least one diagram or structured flow (arch block or table)
contractsMUST/SHOULD table or numbered rules testable independently of the hub summary
verificationConcrete test paths, crates, CI jobs, or registry codes — not “TBD”
operations / migrationProcedures, rollout constraints, or compatibility steps
decisions-recordLegacy only—migrate rows into adr/ files per Specification authority and embedded decisions
adrOne decision per file; SpecAdrChrome; reader ADRs tab lists expandable detail

Pages that cannot meet the minimum must use status: Proposed until expanded.

Required Article sections

Section titled “Required Article sections”

Each optional Article page in a bundle must include:

  1. Purpose and scope — what this article explains and where it does not apply.
  2. Canonical references — links back to the Feature Hub and any normative source pages it relies on.
  3. Detailed behavior or procedure — implementation-facing explanation, examples, or workflows.
  4. Verification and maintenance notes — how drift is detected, reviewed, or tested.
  5. Related topics — at minimum one parent or sibling link.

Newcomer reading order requirements

Section titled “Newcomer reading order requirements”

Every Feature Hub must publish an explicit ordered list that supports first-time orientation:

  1. Start with the parent Area page for system context.
  2. Read the Feature Hub for canonical boundaries and invariants.
  3. Read bundle articles from conceptual overview to operational details.
  4. End with verification and maintenance policy pages (including lastReviewed governance when relevant).

The order must be written to remain stable when new articles are added; append articles by preserving the conceptual-to-operational flow.

Markdown-first authoring policy

Section titled “Markdown-first authoring policy”
  • Use markdown heading structure for all regular sections.
  • Use arch fenced blocks for architecture diagrams.
  • Use tables sparingly; prefer short lists for readability.
  • Component usage is allowed only for non-standard interactive UI or migration edge cases, and must include a rationale note in the page.

Decisions

Section titled “Decisions”

No open decisions. Closed maintenance ADRs under adr/ — D-COMM-HUB-0001 through D-COMM-HUB-0005 (reader ADRs tab).