Architecture

The big picture

Four layers: authoring, source of truth, build, delivery. The translation layer is the load-bearing step — everything else is integration.

Components

The vault repo — cybersader/cyberbase

The durable artifact. A plain Obsidian vault: markdown files + a .obsidian/ config directory. Cyberbaser reads from this repo but never writes to it from the build side. Contributions reach it via commits from one of the three entry points.

Content loader — astro-loader-obsidian

The first stage of the build. Discovers markdown files in the vault, parses frontmatter, and feeds them into Astro’s content collection. Currently a third-party dependency; may need to be replaced or augmented depending on how much Tier 1 translation it handles internally.

Translation layer — remark + rehype plugins

The hot spot. A composed pipeline:

1. remark-obsidian-callout — > [!note] blocks → Starlight <Aside> components
2. remark-wiki-link — [[Page]] and [[Page|alias]] → resolved HTML links
3. Custom embed handler — ![[image.png]] and ![[Note]] — needs to resolve against the vault index
4. rehype-mermaid — fenced mermaid blocks → inline SVG at build time
5. rehype-external-links — external anchors get target="_blank" + rel

Each Tier 1 feature gets a round-trip test fixture. See Translation Layer for the full tiered list.

Starlight renderer

Turns the transformed MDX into HTML pages with sidebar, search, and navigation. Uses the Nova theme for layout and the full sibling plugin stack for consistency.

Site graph + search — starlight-site-graph + Pagefind

Backlinks, graph view, full-text search. Built by crawling the rendered output.

Delivery — Cloudflare Pages

Static hosting. Cloudflare Pages Function hosts the OAuth proxy so Decap’s Open Authoring can handshake with GitHub without exposing the OAuth client secret in the browser.

Boundaries — what each component must NOT do

Vault repo

MUST NOT: contain cyberbaser build artifacts; depend on cyberbaser-side plugins to function in Obsidian; have its file structure dictated by cyberbaser’s URL scheme (only the other way around).

Translation layer

MUST NOT: apply lossy transforms; modify files on disk during build; assume it’s running in any particular environment (must be pure functions over markdown AST).

Web CMS

MUST NOT: depend on Obsidian being running; hold content state outside the repo; require the maintainer to do anything special for an incoming edit.

OAuth proxy

MUST NOT: log or store tokens; have any persistent state beyond the OAuth secret (which lives in Cloudflare secrets, not in code).

Open architectural questions

See Open Questions for the full list. The architecturally-significant ones:

• Does astro-loader-obsidian handle Tier 1 features sufficiently, or does it need replacement?
• Where does backlinks data get computed — inside the content loader, or as a post-build rehype pass?
• What’s the incremental build story for a vault that grows past ~1000 pages?
• How do assets (images) get resolved when the CMS edits a page — does Decap need vault-wide awareness, or can links stay relative?