[Docs] Interactive Developer Hub, Live RPC Playground & Protocol Architecture Portal #1481

Overview & Background

As FlowFi evolves into a protocol standard on Stellar, external developers—ranging from hackathon participants to institutional integration partners—need a unified, interactive Developer Portal. Fragmented Markdown files in docs/ and raw OpenAPI YAML are insufficient. Providing a modern developer documentation site with live runnable API requests, an interactive Soroban RPC sandbox, and visual protocol sequence diagrams accelerates integration and ecosystem growth.

Detailed Problem Statement

1. Scattered Documentation:
   • Architecture ADRs, threat models, backend READMEs, contract interfaces, and SDK guides are scattered across disparate directories (docs/, backend/docs/, packages/flowfi-sdk/).
2. No Interactive API Sandbox:
   • Developers cannot test REST API endpoints, simulate transactions, or inspect webhook payloads directly within documentation.
3. Missing Visual Sequence Diagrams:
   • Complex lifecycle flows (e.g. Batch Withdrawal, Milestone Vesting, Dead-Letter Replay, Client-Side Signing) lack interactive visual walkthroughs.

Technical Specification & Architecture

1. Developer Portal Framework (Mintlify / Docusaurus / Starlight)

Set up a dedicated documentation portal in docs-site/ or /docs:

• Navigation Structure:
  • Getting Started: Protocol Overview, Core Concepts, Quickstart in 5 Minutes.
  • Smart Contracts: Stream Lifecycle, Storage TTLs, Batch Operations, Emergency Pause, Rust Soroban Reference.
  • Backend & Indexer: Event Ingestion, SSE/WebSocket Streams, Webhooks, Dead-Letter Triage.
  • Client SDKs: TypeScript (@flowfi/sdk), React (@flowfi/react), Python, Rust.
  • Guides & Recipes: Setting up DAO Payroll, SaaS Subscription Billing, Milestone Vesting for Grants.
  • API Reference: Interactive OpenAPI specification with "Try It Out" test console.

2. Live Interactive RPC & Sandbox Console

• Embed an interactive Soroban RPC playground connected to Stellar Testnet:
  • Select contract method (create_stream, withdraw, get_stream).
  • Pre-filled mock parameters.
  • Real-time simulation output and decoded Soroban XDR responses.

3. Architecture & Protocol Sequence Diagrams

• Incorporate interactive Mermaid diagrams illustrating:
  • Client-side transaction signing flow with backend preflight simulation.
  • Soroban event emission -> Indexer worker -> PostgreSQL -> SSE/WebSocket fanout.
  • Webhook retry with exponential backoff and dead-letter triage.

Target Files

• docs-site/mint.json (or Docusaurus config)
• docs-site/pages/quickstart.mdx
• docs-site/pages/contracts/lifecycle.mdx
• docs-site/pages/api-reference/
• .github/workflows/deploy-docs.yml

Acceptance Criteria

• Documentation site compiles without broken links or missing assets.
• Interactive API console allows executing live requests against testnet/mock endpoints.
• Mermaid sequence diagrams clearly depict core protocol architectures.
• Comprehensive TypeScript, Python, and cURL code samples provided for every major operation.
• Automated CI workflow deploys documentation preview on pull requests.