Skip to content

Architecture Decision Records (ADRs)

Summary

SkyCMS ADRs are maintained in the main SkyCMS repository as the canonical source of truth.

Canonical ADR Location

ADR Index

Architecture topic summaries

Use this section as a fast architecture map before diving into individual ADR files.

1. Platform direction and operating model

  • ADR 0003: Establishes split deployment paths for single-tenant and multi-tenant editor operation.

8. Editor modernization and terminology alignment

  • ADR 0035: Defines the file explorer modernization approach and connector adapter boundary.
  • ADR 0036: Standardizes layout terminology and docs strategy for editor consistency.
  • ADR 0039: Unifies file-surface controller logic for security parity and shared behavior.
  • ADR 0040: Introduces canonical storage paths with friendly display paths in file manager UX.

9. Article lifecycle, deletion, and read-model alignment

  • ADR 0037: Defines lifecycle status semantics across article workflows.
  • ADR 0038: Formalizes two-step delete lifecycle (soft-delete then permanent trash).
  • ADR 0041: Requires trashed article assets to be hidden and blocked in editor file surfaces.
  • ADR 0042: Keeps ArticleCatalog rows on soft-delete and removes them on permanent delete.
  • ADR 0043: Consolidates event-by-event lifecycle side effects for catalog and assets.

2. Tenant resolution and isolation

  • ADR 0002: Makes early domain-based tenant resolution a first-order architectural constraint.
  • ADR 0022: Standardizes proxy-aware domain resolution through a singleton dynamic configuration provider.
  • ADR 0008: Prevents cross-tenant authentication leakage via cookie-domain isolation strategy.

3. Data portability and provider strategy

  • ADR 0004: Requires cross-provider query safety, including Cosmos-compatible query constraints.
  • ADR 0005: Defines provider auto-detection strategy for portable database runtime behavior.
  • ADR 0017: Aligns storage provider selection with connection-pattern detection.

4. Publishing and delivery patterns

  • ADR 0006: Formalizes publisher operating modes and startup mode selection.
  • ADR 0007: Splits content delivery paths to support performance, security, and mode flexibility.
  • ADR 0024: Confirms editor-publisher separation with shared data and storage contracts.

5. Runtime correctness and security posture

  • ADR 0029: Locks middleware ordering as an architecture-level correctness contract.
  • ADR 0026: Sets secure transport and cookie defaults as baseline security posture.
  • ADR 0011: Standardizes policy-based rate limiting for abuse protection.

6. Startup safety and setup governance

  • ADR 0018: Adds early validation and diagnostic-only startup mode to reduce misconfiguration risk.
  • ADR 0031: Gates setup entry through explicit setup enablement configuration.
  • ADR 0019: Protects operational health checks during setup gating.

7. Architecture operations and observability

  • ADR 0016: Defines tenant-scoped cache lifecycle behavior.
  • ADR 0034: Captures domain-event and setup-audit observability model.

ADR decision dependency map

%%{init: {"theme":"base","themeVariables":{"primaryColor":"#eef6ff","primaryTextColor":"#0f172a","primaryBorderColor":"#2563eb","lineColor":"#334155","secondaryColor":"#f8fafc","tertiaryColor":"#ffffff","fontFamily":"Segoe UI, Arial, sans-serif"}}}%%
flowchart LR
  ROOT[Foundational product direction] --> ADR0002[ADR 0002 Tenant resolution]
  ROOT --> ADR0006[ADR 0006 Publisher modes]
  ADR0002 --> ADR0022[ADR 0022 Dynamic configuration provider]
  ADR0022 --> ADR0029[ADR 0029 Middleware ordering contract]
  ADR0004[ADR 0004 EF cross-provider query contract] --> ADR0005[ADR 0005 DB provider auto-detection]
  ADR0005 --> ADR0020[ADR 0020 ApplicationDbContext abstraction]
  ADR0006 --> ADR0007[ADR 0007 Content delivery path segregation]
  ADR0007 --> ADR0024[ADR 0024 Editor-publisher separation]
  ADR0024 --> ADR0034[ADR 0034 Domain events and setup audit observability]

Mirror Policy

  • Authoritative edits happen in SkyCMS docs/adr.
  • This docs page mirrors IDs and titles only.
  • CI validates that all canonical ADR IDs are represented here.