Standard Garden Architecture v1

The Blueprint for the Universal Publishing Protocol.

This document outlines the finalized architecture for Standard Garden. It defines our pivot from a complex AI content generator to a robust, utility-first publishing tool.

1. The Core Philosophy

“Turn Chaos into Order.”

Standard Garden is a utility, not a platform. It accepts messy input (text, images, HTML) and outputs standardized, beautiful, permanent documents.

• The Moat: The “Four Standards” (Typography).
• The Input: “Drop All, Paste All.”
• The Output: Static, Semantic HTML.
• The Network: A Citation Economy (Links > Likes).

2. The Universal Funnel (Ingestion)

We handle input entirely in the browser (Client-Side) before it hits the API.

A. The “Drop All, Paste All” Interface

We aggressively sanitize input to produce pure Markdown.

• HTML Paste: Intercepted via turndown. Strips fonts, colors, and layout. Keeps structure (H1, B, I, Links).
• Image Drop:
  • Single: Uploads to R2 -> Inserts ![](url) at cursor.
  • Multiple (Gallery Mode): Detects >1 image drop.
    • Uploads in parallel.
    • Generates a “Skeleton Note” with stacked images.
    • Auto-Title: “Gallery [Date]” (if empty).
• Unsupported Files: Rejected client-side.

B. Title Inference Protocol (The Dirty Input Handler)

We never block a save for lack of a title. We infer it in this order:

1. Frontmatter: title: ...
2. H1 Tag: # My Title
3. Filename/Subject: my_doc.txt -> “My Doc”
4. First Line: First 50 chars of text.
5. AI Fallback: Cloudflare AI summarizes text into 3 words.
6. Timestamp: Last resort.

3. The Grand Unified Linking Theory

We separate the system into Roots (Explicit) and Mycelium (Implicit).

A. The Roots (Wiki Links)

The user’s explicit intent. Deterministic.

• Syntax: [[Slug]] or [[Display Text|Slug]]
• The “Flat Garden” Rule: We ignore folder paths. [[Folder/Note]] resolves to Note. Uniqueness is enforced by filename/slug.
• Social Linking: [[@user/slug]] links to another user’s public note.
• Silent Resolution: If a target does not exist (or is private), we render Plain Text. No 404s. No “Ghost” styling. It just looks like text.

B. The Lean Weaver (Implicit Discovery)

The system’s contextual suggestions. Probabilistic.

• No Auto-Linking in Body: We killed the complex “Weaver” to preserve reading flow and performance.
• The “Related” Footer:
  • Trigger: Build Time (SSG).
  • Source: Vectorize (Top 50 Semantic Neighbors).
  • Filter: Sorted by content_score (Gravity).
  • Output: A simple list of “Related Notes” at the bottom of the page.
  • Context: Because neighbors are pulled by vector, they automatically respect context (Polysemy solved).

4. The Citation Economy

“The Currency of the Garden is Thought, not Clicks.”

• No Like Button: We do not have a heart icon.
• Proof of Thought: To upvote a note, you must Link to it from your own garden.
• The Metric: We display Linked by 12 Gardens instead of likes.
• The UI: Clicking the count reveals the list of backlinks (Citations).

5. Data Architecture (D1)

We avoid complex relationship tables in favor of calculated properties.

notes Table

• id (nano_id): Primary Key.
• owner_id: The User.
• slug: URL friendly identifier.
• original_filename: To support Obsidian file renaming.
• content_score: Calculated gravity (Word count + Richness + Pins).
• vector_id: Reference to Cloudflare Vectorize.

edges Table (The Graph)

Stores ONLY explicit Wiki Links found during ingestion.

• source_id
• target_slug (Resolved)
• target_owner (For social links, NULL = local)
• is_valid (Cached boolean for quick rendering)

6. Implementation Priorities

1. Database Migration: Add edges table and content_score column.
2. Ingestion Worker: Build the “Title Inference” and “Drop Handler”.
3. Markdown Parser: Implement markdown-it folio for Silent Resolution of [[...]].
4. Vector Pipeline: Connect workers-ai to generate embeddings on save.