From 35b46abd250b5baa40c5b123325b368244d23803 Mon Sep 17 00:00:00 2001 From: Brandon Corbett Date: Tue, 6 Oct 2026 22:55:00 -0400 Subject: [PATCH] docs: add a Start here section with the ecosystem diagram Point new readers at the docs quickstarts (Docker self-hosted first, managed second) before the repo-specific setup, show where the auth API sits in the ecosystem with a Mermaid topology diagram that highlights this repo, and link the compatibility matrix. The block is shared across the public Seamless Auth repos so the front door reads the same everywhere. Refs fells-code/seamless-auth-docs#45 --- README.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/README.md b/README.md index bde1142..a77ce11 100644 --- a/README.md +++ b/README.md @@ -13,8 +13,27 @@ It provides the backend services for passkeys (WebAuthn) and other passwordless > Looking for the managed experience (hosting, upgrades, metrics, backups, SLAs)? See **https://seamlessauth.com** for managed services. +## Start here + +New to Seamless Auth? The [self-hosted quickstart](https://docs.seamlessauth.com/start/quickstart/) runs the full stack locally with Docker. If Seamless hosts your auth instance, follow the [managed quickstart](https://docs.seamlessauth.com/start/managed-quickstart/) instead. + +This repo is the auth API: it owns sessions and issues the tokens your backend verifies. + +```mermaid +flowchart LR + browser["Browser
@seamless-auth/react"] -- "signed httpOnly cookies" --> backend + native["Native app
@seamless-auth/react-native"] -- "bearer tokens" --> backend + backend["Your backend
@seamless-auth/express, fastify, or nextjs
mounted at /auth"] -- "bearer token + service token" --> api + api["seamless-auth-api
owns the session"] --> db[("Postgres")] + backend -. "verifies tokens with JWKS" .-> api + style api stroke-width:3px +``` + +[How the pieces connect](https://docs.seamlessauth.com/start/overview/#how-the-pieces-connect) explains each hop. [Compatibility matrix](https://docs.seamlessauth.com/build/ecosystem/#compatibility-matrix) lists which package versions work together. + ## Contents +- [Start here](#start-here) - [Scope and non-goals](#scope-and-non-goals) - [Why Seamless Auth API](#why-seamless-auth-api) - [High-level architecture](#high-level-architecture)