For AI Developers: This document is the core reference for the Funish Vertex project. Please read it thoroughly before starting development.

Funish Vertex is an enterprise-grade, multi-organization developer platform built on Better Auth. It leverages a plugin-based architecture to provide a complete infrastructure solution for modern applications. The platform features a dual-layer authentication architecture: a platform layer manages organizations and users, while each organization is provided with its own independent, configurable Better Auth instance and plugin ecosystem.

• Dual-Layer Authentication: Platform management + isolated Better Auth instances for each organization.
• Plugin-Powered Ecosystem: Functional extensions based on the Better Auth plugin system.
• Multi-Organization Isolation: Complete isolation of data, storage, and configuration between organizations.
• Flexible Configuration: Organizations can freely enable, disable, and configure the plugins they need.
• Unified API: Standardized RESTful API design.

• Authentication Framework: Better Auth (Core) + Custom Plugin Ecosystem
• Frontend: Nuxt 4 + Vue 3 + UnoCSS + PrimeVue
• Backend: Nitro (API Gateway) + Better Auth (Authentication)
• Database: Kysely (ORM) + PostgreSQL + Dynamic Schema Management
• Storage: Unstorage (Multi-Driver Abstraction) + Storage Server
• AI Integration: Vercel AI SDK + Provider Registry

┌──────────────────────────────────────────────────────────────┐
│                     Platform Layer                          │
│  ┌─────────────────┐    ┌─────────────────────────────────┐  │
│  │  Platform       │    │     Universal Plugin Registry   │  │
│  │  Configuration  │    │  ✓ Storage Plugin               │  │
│  │  - Base Plugins │    │  ✓ Database Plugin              │  │
│  │  - Global Rules │    │  ✓ AI Router Plugin             │  │
│  │  - Rate Limits  │    │  ✓ ...and other official plugins  │  │
│  └─────────────────┘    └─────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘
                                │ (Provides)
                                ▼
┌──────────────────────────────────────────────────────────────┐
│                    Organization Layer                        │
│  Organization A         Organization B      Organization C   │
│  ┌─────────────────┐   ┌─────────────────┐  ┌──────────────┐ │
│  │ Org A Config    │   │ Org B Config    │  │ Org C Config │ │
│  │ ├ + Storage(S3) │   │ ├ + Storage(R2) │  │ ├ + Database │ │
│  │ └ + AI Router   │   │ └ + Analytics   │  │ └ + AI Router│ │
│  └─────────────────┘   └─────────────────┘  └──────────────┘ │
└──────────────────────────────────────────────────────────────┘
                                │ (Configures)
                                ▼
┌──────────────────────────────────────────────────────────────┐
│                  Runtime Instances                          │
│    Better Auth Instance A   Better Auth Instance B  etc.     │
│  (Platform + Org A Config) (Platform + Org B Config)         │
└──────────────────────────────────────────────────────────────┘

Our platform is built around a powerful plugin system, managed by our Plugin Registry. This registry allows administrators to discover, enable, and configure plugins for each organization.

• Gateway Plugin: A comprehensive API gateway that provides routing, rate limiting, and API key authentication.
• Storage Plugin: Based on unstorage, providing multi-driver support (S3, R2, etc.) and tenant-isolated storage.
• Database Plugin: Based on Kysely, allowing for dynamic, isolated database schemas per organization.
• AI Router Plugin: Based on the Vercel AI SDK, enabling routing to multiple AI providers like OpenAI, Anthropic, and Groq.
• ...and many more, including official Better Auth plugins for payments, analytics, etc.

• Platform-Level Data: Manages core tables for user, session, organization, and organization_plugin_config.
• Organization-Level Data: Each organization gets its own database schema (e.g., org_123_schema), ensuring complete data isolation. Plugin-specific tables are created within this schema when a plugin is enabled.

• Developer Quickstart Guide - Quick start guide for new developers
• Architecture Design - Detailed system architecture
• Plugin Registry Implementation - Plugin system details

• Multi-Tenant Plugin Development - Comprehensive development guidelines
• Better Auth Plugin Structure - Plugin structure guidelines

/api/v1/
├── platform/          # Platform Management API
│   ├── auth/          # Platform-level authentication
│   └── plugins/       # Plugin Registry discovery
└── {orgId}/           # Organization-specific API
    ├── auth/          # Organization-level authentication
    └── ...            # Plugin-specific routes (e.g., /storage/*)

• Project initialization and documentation design
• Better Auth platform-level setup
• Plugin Registry architecture design and implementation
• Multi-organization dynamic schema management
• Basic API framework

• Storage Plugin (Unstorage integration)
• Database Plugin (Kysely integration)
• AI Router Plugin (Vercel AI SDK integration)
• Gateway Plugin (Routing, Rate Limiting, API Keys)
• Tenant Plugin (Multi-organization support)
• Permission Plugin (Access control and role management)

• Better Auth Vue client setup
• Basic authentication middleware
• Authentication UI components (Login, Register, etc.)
• Organization management interface
• Plugin marketplace UI
• Dashboard and admin panels

1. Align with Better Auth: All plugins must be compatible with the BetterAuthPlugin interface.
2. Type Safety: Use TypeScript strict mode and avoid any.
3. Organization Isolation: Ensure complete data and configuration isolation between organizations.
4. API Versioning: Maintain stable and versioned APIs.

// Simplified example from server/utils/auth.ts

import { betterAuth } from "better-auth";
import { getEnabledPlugins } from "@funish/vertex/plugins/registry";

// Factory function to create a Better Auth instance for a specific organization
export const createAuthForOrganization = async (orgId: string) => {
  const allPluginConfigs = await loadAllOrgPluginConfigsFromDB();
  const { server: serverPlugins } = getEnabledPlugins(orgId, allPluginConfigs);

  return betterAuth({
    // ... base config
    plugins: serverPlugins, // Pass the dynamically instantiated plugins
  });
};

// Simplified example from packages/vertex/src/plugins/registry/register.ts

import { globalPluginRegistry } from "./registry";
import { storagePluginDefinition } from "../storage";

// Register all built-in plugins on startup
export function registerBuiltinPlugins() {
  globalPluginRegistry.register(storagePluginDefinition);
  // ... register other plugins
}