vela-docs

Developer documentation site at docs.velapay.com.

Purpose and Role

• Public technical docs for the SDK and protocol.
• Downstream explanation layer for what the internal wiki tracks privately.
• Static content surface separate from internal planning and ops material.
• SDK reference, integration guides, cookbook recipes, Mermaid architecture diagrams.
• Audience-based information architecture: merchants, developers, subscribers.

Tech Stack

Technology	Version	Purpose
Astro	6.1.x	Base framework — zero JS by default
Starlight	0.38.x	Docs theme — built-in search, navigation, dark/light mode, i18n
@astrojs/cloudflare	latest	CF adapter for Workers deployment
Tailwind CSS	4.2.x	Custom theme styling (emerald palette)
MDX	—	Interactive content with React components
Mermaid	—	Architecture diagrams in documentation
wrangler	4.78.x	Cloudflare CLI for deployment

Directory Structure

vela-docs/
├── src/
│   ├── content/
│   │   └── docs/               # 60+ MDX pages
│   │       ├── guide/          # Getting started, quickstart
│   │       ├── sdk/            # SDK reference (VelaClient, PDAFactory, instructions)
│   │       ├── protocol/       # Protocol concepts (mandates, credentials, streaming)
│   │       ├── integration/    # Integration guides (widget, checkout, webhook)
│   │       ├── cookbook/       # Recipe-style tutorials
│   │       ├── merchants/      # Merchant-focused docs
│   │       ├── subscribers/    # Subscriber-focused docs
│   │       └── webhook-events/ # v1.8 — Event reference pages
│   ├── components/             # Custom Starlight components
│   │   ├── CodeBlock.tsx       # Enhanced code blocks with copy button
│   │   └── MermaidDiagram.tsx  # Mermaid rendering in MDX
│   ├── styles/
│   │   └── custom.css          # Emerald palette, Starlight theme overrides
│   └── plugins/                # Custom Starlight plugins
├── astro.config.mjs            # Astro + Starlight config
├── package.json
└── wrangler.toml

Deployment Target

• Cloudflare Workers: Static site served from edge.
• Domain: docs.velapay.com.

Dependencies

What It Depends On

Dependency	Type	Purpose
Workspace knowledge	Content	Documents the SDK and protocol produced by other repos

What Depends on It

Nothing. Documentation is a terminal consumer with no downstream dependents.

Current Status

• v1.6 complete: 60 MDX pages, custom Starlight theme with emerald palette, cookbook, Mermaid diagrams.
• v1.8 updates: Webhook event reference pages, streaming docs, multi-token guides, upgrade cookbook.

Notable Design Decisions

Starlight over Docusaurus/VitePress

Starlight is lighter (Astro-based, zero JS by default), has built-in search via Pagefind, and Cloudflare uses it for their own docs. Docusaurus is React-heavy with larger bundles. VitePress is Vue-based, misaligned with the React ecosystem.

Audience-Based IA

Documentation is organized by audience (merchants/developers/subscribers) rather than by technical component. This matches how users discover docs — they come with a role, not a component name.

MDX for Interactive Content

MDX allows embedding React components (code playgrounds, Mermaid diagrams, copy buttons) within documentation pages. Static content stays fast; interactive content loads only where needed.

Custom Starlight Theme

Emerald palette matching VelaPay brand. CSS overrides for Starlight's default theme without forking the theme package.

Static Content (No Protocol Dependency)

Docs are purely informational with no live protocol reads. SDK examples show code patterns but don't execute against live chains. This keeps docs fast, cacheable, and independently deployable.

Content Architecture

Page Count and Organization

Section	Pages	Audience	Content Type
Guide	5	Developers	Quickstart, installation, configuration
SDK Reference	15	Developers	VelaClient, PDAFactory, instruction builders, account types
Protocol	10	Developers	Mandates, credentials, streaming, transfer hooks
Integration	8	Developers	Widget, checkout, webhook, CLI
Cookbook	12	Developers	Recipe-style tutorials for common patterns
Merchants	5	Merchants	Setup, plan management, analytics
Subscribers	3	Subscribers	Portal usage, cancellation, plan switching
Webhook Events	6	Developers	Event reference, payload schemas, retry behavior

Mermaid Architecture Diagrams

Key pages include Mermaid diagrams that visualize:

• Billing execution path (merchant → keeper → protocol → transfer hook → Token-2022).
• Dual-program architecture (protocol + transfer hook).
• Arcium MPC integration flow (Phase 1+).
• Service binding architecture (admin → dashboard → D1).
• Multi-repo dependency graph.

Versioning Strategy

Documentation is versioned with the SDK. When @vela/sdk publishes a new version:

1. New features get new documentation pages.
2. Breaking changes get migration guides.
3. Deprecated features are marked but not removed (backward compatibility).
4. CI enforces that docs changes accompany SDK changes.

Search and Navigation

• Pagefind: Built-in search via Starlight. Indexes all MDX content at build time.
• Sidebar navigation: Organized by section with collapsible groups.
• Breadcrumbs: Show current position in the documentation hierarchy.
• Previous/Next: Sequential navigation within sections.
• Dark/light mode: Built-in theme toggle via Starlight.