Architecture

Sora UI is designed as an open-source, motion-first component system built with a dual-comprehension philosophy: UI components whose behavior, accessibility constraints, animation semantics, and composition rules are directly understandable by both developers and AI assistants.

It combines an open copy-paste registry architecture with structured metadata served via an MCP server, offering flexible primitives across multiple headless foundation libraries.

Core Principles

• Built for humans and AI — Native Model Context Protocol (MCP) support exposing component intents, composition patterns, and constraints directly into AI coding workflows.
• Three-tier component model — A clear hierarchy spanning Motion Primitives, Headless UI Implementations, and Complex Catalog Components.
• Multi-primitive foundations — Components built on robust accessibility primitives including Radix UI, Base UI, and Headless UI.
• Deep motion system — Fluid, physics-based animations with accessible defaults and first-class prefers-reduced-motion support.

Monorepo Layout

Sora UI is organized as a Turborepo monorepo with dedicated apps and modular packages:

apps/
  www                  — Documentation site, interactive playground & registry catalog
  xmcp                 — Model Context Protocol (MCP) server for AI coding agents
packages/
  ui                   — Shared UI utilities, styles, and core building blocks
  auth-ui              — Better-auth UI components and session management
  db                   — Database client and Drizzle ORM schemas (Postgres / Neon)
  www-cli              — Internal CLI tools for component scaffolding and registry audits
  typescript-config    — Shared TypeScript configurations

Applications

• apps/www: Built with Next.js (App Router) and Fumadocs. Serves the documentation, component previews, theme switcher, and JSON registry endpoints.
• apps/xmcp: A standalone MCP server delivering real-time search, documentation, and installation schemas to AI assistants (Cursor, Claude Code, VS Code, Windsurf).

Packages

• packages/db: Database layer using Drizzle ORM and Postgres, powering docs authentication, starred components, and user bookmarks.
• packages/auth-ui: Authentication views and state integration using better-auth.
• packages/ui: Shared design tokens, Tailwind configuration, and utility functions used across internal applications.
• packages/www-cli: Internal development utilities including automated registry generation and health audit commands (bun run doctor).

Registry Architecture

Components are distributed via an open, copy-paste registry following the shadcn distribution schema. The registry is structured into three distinct tiers:

registry/
  primitives/            — Tier 1: Motion Primitives (animation building blocks)
    animate/             — Core animation wrappers and state transitions
    buttons/             — Animated buttons and micro-interactions
    effects/             — Visual effects, backgrounds, and shaders
    texts/               — Typography motion and text reveals
    disclosure/          — Accordions, tabs, and collapsible motion
  ui/                    — Tier 2: Foundation UI (accessible primitives)
    base/                — Components built on @base-ui-components/react
    radix/               — Components built on @radix-ui
  demo/                  — Interactive examples and documentation previews
  hooks/                 — Reusable React animation and lifecycle hooks
  lib/                   — Internal utilities, cn helper, and math functions

Component Tiers

1. Motion Primitives (registry/primitives/): Low-level, composable building blocks focused on motion and gesture interactions powered by Framer Motion / Motion.
2. UI Components (registry/ui/): Standard application UI elements (dialogs, dropdowns, inputs, tooltips) wired to battle-tested headless primitives like Radix UI or Base UI for full WAI-ARIA compliance.
3. Catalog & Compositions: Advanced, production-ready composite patterns that combine motion primitives with UI components.

Self-hosting the docs site

Sora UI's documentation site keeps sign-in sessions and bookmarks in a Postgres database. The schema and client live in packages/db, built on Drizzle ORM and postgres.js.

Recommended: Neon

Neon is the provider we recommend for self-hosting Sora UI. It fits the way this app talks to Postgres:

• Pooled connections at runtime. Neon exposes a PgBouncer endpoint that accepts thousands of client connections over a small pool of real ones — ideal for a serverless deployment that opens a connection per request.
• Direct connections for migrations. The same project hands you a direct (unpooled) endpoint, which schema migrations need because transaction-mode pooling does not support session-level state.
• Branching for preview deployments. A Neon branch is an instant, copy-on-write clone of the database with its own connection string — handy for testing migrations without touching production.
• Scale to zero. Idle computes suspend after a few minutes, so a low-traffic docs site costs close to nothing.

Connection strings

Neon gives you two URLs for the same database. They differ only by the -pooler suffix in the hostname:

Both use port 5432 and require sslmode=require:

DATABASE_URL="postgresql://USER:PASSWORD@ep-xxx-pooler.us-east-2.aws.neon.tech/neondb?sslmode=require"
DATABASE_URL_DIRECT="postgresql://USER:PASSWORD@ep-xxx.us-east-2.aws.neon.tech/neondb?sslmode=require"

Copy both URLs from the Neon console with the Connect button. Enable Connection pooling for DATABASE_URL, then disable it for DATABASE_URL_DIRECT.

The Neon CLI can pull the pooled and direct URLs as DATABASE_URL and DATABASE_URL_UNPOOLED:

neon env pull

This project uses DATABASE_URL_DIRECT instead of Neon's DATABASE_URL_UNPOOLED name, so copy the unpooled value into DATABASE_URL_DIRECT in apps/www/.env.

Environment variables

Set these in apps/www/.env:

Applying migrations

Schema lives in packages/db/src/schema. Run migrations from the package root:

cd packages/db
bun run db:migrate

drizzle-kit prefers DATABASE_URL_DIRECT and falls back to DATABASE_URL. Always give it a direct connection — running migrations through a transaction-mode pooler fails in confusing ways.

Other schema commands:

bun run db:generate   # generate SQL from the schema
bun run db:push       # push schema without a migration file (dev only)
bun run db:studio     # open Drizzle Studio

Using a different Postgres provider

Any Postgres provider works — the schema is plain Postgres, and the client connects with prepare: false so it stays compatible with transaction-mode poolers (Neon's -pooler endpoint, Supabase's port 6543).

Point DATABASE_URL at a pooled endpoint and DATABASE_URL_DIRECT at a direct one, then apply the migrations above.

Origins & Attribution

Sora UI originated as a fork of Animate UI by @imskyleen, from which it inherited early monorepo boilerplate and documentation layout conventions.

Since then, the project has been fully re-architected with independent component implementations, an AI-native MCP server, a 3-tier registry architecture, and dedicated fullstack docs infrastructure. Component implementations are developed independently or credited in their respective documentation pages under ## Credits.

Original Sora UI code is distributed under the MIT License. Portions derived from upstream remain subject to their original licenses:

Portions Copyright (c) 2025 Elliot Sutton (Animate UI — https://github.com/animate-ui/animate-ui)

Full license text is available on the License page. If something looks like it's missing credit, please reach out.