SeedStart DocsInternal documentation

Architecture, deployment, runbooks, and release history for the seedsite repo. Auto-built from Markdown — Claude is the primary author.

📐 Architecture

How the system is structured, how the pieces talk to each other, and where each piece lives.

🚀 Deployment

How the dev and prod environments are wired up, and what each tag triggers in CI.

🔌 API Reference

HTTP endpoints exposed by the Cloud Run functions service.

🗄️ Firestore Schema

Collection layouts, document shapes, and security-rule constraints.

🔐 Secrets & Permissions

How secrets are stored, where they live, and which service accounts touch what.

📜 Release History

Every v1.0.X tag with the commits that landed in it. Auto-generated by GitHub Actions on tag push.

How this site works

This site is rendered by VitePress from the Markdown files in docs/. There is no second source of truth — every page you see here corresponds to a single .md file in the repo. The HTML you're reading right now only exists on the Cloudflare CDN; it is not committed to git.

What's automated

Release notes (RELEASES.md) — regenerated on every prod tag push by update-release-notes.yml. The workflow walks every v*.*.* tag and writes the file back to main.
This site — rebuilt and redeployed on every push to main that touches docs/ by deploy-docs.yml, which pnpm docs:builds the VitePress site and ships it to Cloudflare Pages via wrangler pages deploy.
Sidebar — auto-built from the filesystem at compile time. New .md files appear automatically without sidebar config edits.
Access control — the published site is gated behind Cloudflare Zero Trust (free plan). Only explicitly allowlisted emails can reach it; anyone else hits an email-OTP sign-in wall.

The deployment pipeline

Two self-reinforcing automated loops keep the docs site current without human intervention:

Both loops converge on the same deploy-docs.yml workflow, so a new prod tag ends up refreshing the rendered release notes on the docs site within ~2 minutes of the tag push — with zero human steps.

How diagrams work

Architecture diagrams should be authored as Mermaid code blocks in Markdown, not as hand-drawn SVG. Mermaid is text-based, AI-readable, and renders to a real diagram in your browser via the vitepress-plugin-mermaid plugin. Example:

markdown

```mermaid
graph LR
  Browser --> CDN
  CDN --> Frontend
  Frontend --> API
  API --> Firestore
```

…renders as:

Hand-drawn SVGs are technically supported (just embed them with ![](./diagram.svg)) but should be avoided — Claude can't read SVG path data, only text labels, so editing or extending the diagram from a prompt becomes a manual loop. Mermaid keeps the workflow fully prompt-driven.