Rayos Documentation

The official public-facing developer documentation for the Rayos Organization.
Seedless, passkey-native smart wallets for Stellar.

---

📖 About This Repository

This repository contains the source code for the public-facing Rayos Documentation Site. It is built with Docusaurus, a modern static website generator designed for documentation.

Unlike the internal ARCHITECTURE.md files that live inside each individual repository (which are meant for contributors to that specific codebase), this site serves as the comprehensive guide for external developers, integrators, and grant reviewers.

Think of this site as the "book" on how Rayos works.

---

📚 Table of Contents

Our documentation is structured to read like a book, taking you from high-level concepts down to the technical metal:

1. 👋 Introduction — What is Rayos and why did we build it?
2. 🚀 Quickstart — Run the full stack locally in 10 minutes.
3. 🏛️ Architecture Overview — How the 8 repositories fit together.
4. 🔗 Smart Contracts — Deep dive into the Soroban Rust contracts.
5. 📦 Wallet SDK — How frontend apps talk to the blockchain.
6. ⚙️ Relay Backend — The NestJS middleman that pays your gas fees.
7. 🖥️ Applications — The Web, Mobile, and Demo frontends.
8. 🔧 Integrating the SDK — Add passkeys to your own app.
9. 🔄 Recovery Flow — How social guardian recovery actually works.
10. 🛡️ Threat Model — What we protect against and what we don't.
11. 🔒 Responsible Disclosure — Found a bug? Let us know safely.
12. 🗺️ Roadmap — Where we are going next.

---

🛠️ Local Development

Want to preview the documentation site locally or contribute changes?

Prerequisites

• Node.js version 18 or above
• npm or yarn

Installation

git clone https://github.com/Rayos-Org/docs.git
cd docs
npm install

Local Server

npm run start

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

Build

npm run build

This command generates static content into the build directory and can be served using any static hosting service.

---

🤝 Contributing

We welcome contributions to the documentation! If you find a typo, want to clarify a confusing section, or have a new guide to add:

1. Fork the repository
2. Make your edits to the markdown files
3. Test locally using npm run start
4. Submit a Pull Request

All content is written in Markdown (.md) or MDX (.mdx), allowing you to use React components directly within the documentation. We also use Mermaid extensively for architecture diagrams.

---

📄 Content Ownership Rule

Every page under architecture/ is a reader-friendly version of the corresponding repository's internal ARCHITECTURE.md. The repo-level files remain the absolute source of truth for deep technical details. This site focuses on the bigger picture and cross-repository relationships.

---

Built with ❤️ by the Rayos team.