Skip to content

ADR 0011: Universal Document URL Strategy and Publishing Pipeline

Status

Proposed

Date

2026-08-06

Context

OVES produces documents of several types with different audiences:

Type Source Lifetime Audience
Internal docs GitHub mkdocs Permanent WeCom SSO
External decks WorkBuddy/Build tools Permanent WeCom + Keycloak
Memos WorkBuddy HTML Temporary WeCom SSO
Training WorkBuddy/Build tools Permanent WeCom SSO
Media WorkBuddy/Build tools Permanent WeCom + Keycloak

Old pipeline (Cloudflare Pages) serves all types with no type-awareness. New pipeline needs COS storage + branded omnivoltaic.cn domain system + per-type access control.

Decision

Subdomain-per-type URL system, COS prefix-based origin routing, EdgeOne Edge Functions per subdomain.

URL System

Subdomain Doc Type Auth COS Prefix
Subdomain Doc Type Auth COS Prefix
----------- ---------- ------ ------------
docs.omnivoltaic.cn Internal repo docs WeCom SSO docs/
decks.omnivoltaic.cn External presentations/pitches WeCom + Keycloak decks/
memo.omnivoltaic.cn Internal short-lived memos WeCom SSO memo/
training.omnivoltaic.cn Training materials WeCom SSO training/
media.omnivoltaic.cn Media presentations WeCom + Keycloak media/

Pipeline

Source → Build → COS (permanent) → EdgeOne CDN → [doc-type].omnivoltaic.cn

Design Principle

Subdomain = access control. Path = content identity.

The subdomain determines who can access the content (WeCom SSO vs. WeCom+Keycloak). The path after the subdomain identifies the content (repo name, pitch name, memo title, etc.). This keeps auth configuration simple — one Edge Function per subdomain — and content organization flexible — any path structure within the subdomain.

Why subdomains over paths

  • Each subdomain = independent Edge Function (no conditional routing)
  • Different CDN cache policies per type
  • Self-documenting URLs: docs.omnivoltaic.cn clearly means "documentation"
  • Cookie-based SSO shares .omnivoltaic.cn session across subdomains
  • Auth is tied to subdomain, not path — simplifies security model

Lifecycle Rules

Prefix IA (30d) Deep Archive (90d) Delete (365d)
docs/ No ✅ No
decks/ No ✅ No
memo/ ✅ ✅ ✅
training/ No ✅ No
media/ No ✅ No

Consequences

  • One pipeline, all doc types — COS is the single artifact store
  • Auth at the edge — no auth logic in application code
  • Per-type lifecycle — internal permanent, memos auto-expires
  • Future-proof — add new type = COS prefix + subdomain + Edge Function
  • No rebuild on serving change — swap CloudStudio for EdgeOne CDN