# Motherbase

> Open source, self-hosted backend platform. Run many isolated projects from one VPS and one
> domain. Postgres with native row-level security, Better Auth, storage, realtime, edge
> functions, triggers, cron, a Studio admin UI, a Supabase-compatible client SDK, a
> multi-project Platform Console and an operator CLI. MIT licensed, TypeScript and Node.js.

The API dialect is PostgREST-compatible and the client SDK is shaped like supabase-js, so
Supabase knowledge transfers directly — but authorization is real PostgreSQL RLS, not an
application-layer check. Read [REST API](https://motherbase.dev/docs/reference/rest-api/) and
[RLS](https://motherbase.dev/docs/platform/rls/) before generating any data-access code.

The entire documentation set is also served as one plain-text file at
https://motherbase.dev/llms-full.txt (~500 KB). Prefer it when you need broad context in a single
fetch; use the per-page links below when you already know which page you want.

Known defects are listed, in full and on purpose, at
https://motherbase.dev/docs/contributing/known-issues/ — read it before asserting that something works.

## Documentation

### Getting Started
- [Overview](https://motherbase.dev/docs/getting-started/overview): What is Motherbase and why does it exist?
- [Quickstart](https://motherbase.dev/docs/getting-started/quickstart): Install the Platform Console, then create your first Motherbase project.
- [Framework Quickstarts](https://motherbase.dev/docs/getting-started/frameworks): Connect a Next.js, React, Vue, Nuxt, SvelteKit, Expo, or Node application to a Motherbase project.
- [Deploy](https://motherbase.dev/docs/getting-started/deploy): Production deployment on a VPS with setup.sh, Traefik, and automatic TLS.
- [Updates](https://motherbase.dev/docs/getting-started/updates): Update the Platform Console, project stacks, images, and migrations without losing project data.
- [Migrate from Supabase](https://motherbase.dev/docs/getting-started/migrate-from-supabase): Move a Supabase project to Motherbase: schema, data, RLS policies, auth users, storage objects, edge functions and secrets.
- [For AI agents](https://motherbase.dev/docs/getting-started/for-ai-agents): Machine-readable entry points, and the handful of Motherbase behaviours a model trained on Supabase will get wrong.

### Architecture
- [Architecture Overview](https://motherbase.dev/docs/architecture/overview): The three planes of Motherbase — Platform Console, per-project API server, and Studio — and how the monorepo maps onto them.
- [Request Lifecycle](https://motherbase.dev/docs/architecture/request-lifecycle): Every middleware a request passes through in the project API, in mount order, and what each one enforces.
- [Settings System](https://motherbase.dev/docs/architecture/settings-system): How operator-editable settings groups are defined, validated, encrypted, cached and applied live without a restart.
- [Data Model](https://motherbase.dev/docs/architecture/data-model): Every Prisma model in a project database, the schema it lives in, and the feature that owns it.
- [Security Model](https://motherbase.dev/docs/architecture/security-model): Trust boundaries, credentials, the two database connection planes, RLS claim propagation, and the guards that back them.
- [REST Engine](https://motherbase.dev/docs/architecture/rest-engine): How /rest/v1 turns a PostgREST query string into SQL: the catalog, the parser, the compiler, exposure rules and HTTP semantics.
- [Edge Runtime](https://motherbase.dev/docs/architecture/edge-runtime): The private Deno sidecar, the worker pool that isolates one function per process, the compatibility bootstrap and the egress guard.
- [Background Jobs](https://motherbase.dev/docs/architecture/background-jobs): Every in-process worker: cadence, leasing, retries, retention, and how they are made testable and restart-safe.
- [Storage Pipeline](https://motherbase.dev/docs/architecture/storage-pipeline): Drivers, the reservation state machine behind presigned uploads, size and MIME enforcement, quotas and cleanup.

### Platform
- [Auth](https://motherbase.dev/docs/platform/auth): Better Auth-powered authentication: email/password, social login, magic links, email OTP, passkeys, two-factor, organizations, per-org SSO, and API keys.
- [API Keys](https://motherbase.dev/docs/platform/api-keys): Publishable and secret project keys, the service_role Postgres role, and how a request picks the role it runs as.
- [Database](https://motherbase.dev/docs/platform/database): SQL editor first, table editor, auto REST routes, and native PostgreSQL RLS.
- [Row Level Security](https://motherbase.dev/docs/platform/rls): Native PostgreSQL RLS in Motherbase: roles, JWT claims, SQL policies, REST, and Realtime.
- [Storage](https://motherbase.dev/docs/platform/storage): Object storage with local or S3-compatible backends, admin buckets, CORS, access tokens, and webhooks.
- [Realtime](https://motherbase.dev/docs/platform/realtime): Socket.IO channels with broadcast, presence, and RLS-aware postgres_changes — plus the room layout, typing indicators, and reconnection rules.
- [Edge Functions](https://motherbase.dev/docs/platform/edge-functions): Server-side TypeScript stored in the database and executed in a private Deno runtime, one process per function.
- [Postgres Triggers](https://motherbase.dev/docs/platform/triggers): Create, inspect, enable, disable, and drop real PostgreSQL triggers from Project Studio.
- [Cron Jobs](https://motherbase.dev/docs/platform/cron-jobs): Schedule recurring SQL jobs with pg_cron and monitor application cron jobs in Project Studio.
- [Git Migrations](https://motherbase.dev/docs/platform/git-migrations): Connect a GitHub repository to a project so every push applies the new .sql migrations in it.
- [MCP Server](https://motherbase.dev/docs/platform/mcp): Expose a project to an AI agent over the Model Context Protocol: schema, policy lint, RLS simulator, and real DDL.
- [AI Assistant](https://motherbase.dev/docs/platform/ai-assistant): The built-in database assistant: bring your own provider key, read-only tools by default, write proposals you approve.
- [Notifications](https://motherbase.dev/docs/platform/notifications): Transactional email over SMTP, SMS over Twilio, and push to iOS/Android/Web — all configured per project from Studio.
- [Events & Webhooks](https://motherbase.dev/docs/platform/events-and-webhooks): Row-change events, webhook matching and delivery, the delivery log, and the SSRF-hardened outbound HTTP client.
- [Observability](https://motherbase.dev/docs/platform/observability): Logs, request metrics, latency time series, the security/performance advisor, the job ledger and its alerts.
- [Integrations](https://motherbase.dev/docs/platform/integrations): First-party integration catalogue — connecting one stores secrets and optionally installs prebuilt edge functions.

### Project Studio
- [Studio Overview](https://motherbase.dev/docs/studio/overview): The admin app: how it is served, the full route map, the app shell, guards, and mock mode.
- [Table Editor](https://motherbase.dev/docs/studio/tables): Browsing and editing rows, and the DDL operations the structure panel performs.
- [SQL Editor](https://motherbase.dev/docs/studio/sql): Running SQL from Studio, the read-only mode and how it resists bypasses, and the audit trail.
- [Database Screens](https://motherbase.dev/docs/studio/database): Functions, triggers, extensions, migrations, backups, webhooks and cron — what each screen calls.
- [Authentication Screens](https://motherbase.dev/docs/studio/auth): Users, providers, MFA, passkeys, organizations, sessions, hooks, policies and auth settings in Studio.
- [Storage Screen](https://motherbase.dev/docs/studio/storage): Buckets, objects, CORS, scoped tokens, per-bucket webhooks, and resumable force-deletion.
- [API Explorer & Edge Functions](https://motherbase.dev/docs/studio/api-tools): The request playground, edge function editing and invocation, and edge secrets.
- [Logs, Observability & Advisor](https://motherbase.dev/docs/studio/logs): The log stream, the shield report, performance, metric series, and advisor findings.
- [Platform & Project Screens](https://motherbase.dev/docs/studio/platform): Projects list, create, overview, connect, org settings, team, usage, billing, and the platform-level actions.

### Platform Console
- [Platform Console Overview](https://motherbase.dev/docs/console/overview): What the Console is, how it boots, how it authenticates operators, and where its state lives.
- [Projects](https://motherbase.dev/docs/console/projects): The project lifecycle: what create writes to disk, which secrets are generated, how status is derived, and what every action does.
- [Preview Projects](https://motherbase.dev/docs/console/preview-projects): One isolated stack per pull request, provisioned from a GitHub webhook and destroyed when the PR closes.
- [Orchestration Daemon](https://motherbase.dev/docs/console/orchestration): The separate process that holds the Docker socket, its HTTP contract, and why the Console never touches Docker directly.
- [Users, Roles & Organizations](https://motherbase.dev/docs/console/users-and-orgs): Console operators, the capability matrix, per-project scoping, and the tenant organization layer above projects.
- [Monitoring, Alerts & Diagnostics](https://motherbase.dev/docs/console/monitoring): Per-project resource usage from docker stats, threshold alerts to a webhook, and DNS/TCP diagnostics for domains.
- [Audit Log](https://motherbase.dev/docs/console/audit-log): What the Console records about operator actions, how entries are sanitized and retained, and where the file lives.
- [Project Proxy](https://motherbase.dev/docs/console/proxy): How the Console reaches a project's admin, REST and edge APIs: upstream resolution, token injection, and the capability mapping.
- [Console API Reference](https://motherbase.dev/docs/console/console-api): Every Platform Console HTTP route with its required role or capability.

### CLI
- [CLI Overview](https://motherbase.dev/docs/cli/overview): Use the Motherbase CLI to operate the Platform Console, linked projects, local stacks, and admin resources.
- [CLI Getting Started](https://motherbase.dev/docs/cli/getting-started): Install the Motherbase CLI, log in to the Platform Console, link a project, and run the first admin commands.
- [CLI Commands](https://motherbase.dev/docs/cli/commands): Reference for the Motherbase CLI command tree.

### Packages
- [Workspace Overview](https://motherbase.dev/docs/packages/overview): Every workspace in the monorepo, what it publishes, what depends on what, and how it is built and tested.
- [Client SDK Internals](https://motherbase.dev/docs/packages/client): Complete source-grounded reference for @motherbase/client, including auth, typed queries, storage, realtime, functions, and errors.
- [SSR Helpers](https://motherbase.dev/docs/packages/ssr): Cookie-backed browser, server, and middleware clients for using @motherbase/client with Next.js.
- [AI Package](https://motherbase.dev/docs/packages/ai): Architecture of the Motherbase agent loop, normalized event stream, tool execution, provider adapters, and server integration.
- [Shared Contracts](https://motherbase.dev/docs/packages/contracts): HTTP, storage, and realtime contracts shared between the Motherbase server and TypeScript client.
- [@motherbase/ui](https://motherbase.dev/docs/packages/ui): Configurable React components for Motherbase authentication, accounts and uploads.
- [CLI Architecture](https://motherbase.dev/docs/packages/cli): Internal design of @motherbase/cli: dispatch, context resolution, authentication, HTTP routing, command modules, and output.
- [create-motherbase-app](https://motherbase.dev/docs/packages/create-app): Scaffold a Next.js or React application with Motherbase authentication ready to customize.

### Self-hosting
- [Self-hosting overview](https://motherbase.dev/docs/self-hosting/overview): Choose the Motherbase topology and prepare its host, DNS, and persistent storage.
- [Setup script](https://motherbase.dev/docs/self-hosting/setup-script): Run setup.sh interactively or unattended and understand every generated file, check, and reset path.
- [Docker topology](https://motherbase.dev/docs/self-hosting/docker-topology): Map every Motherbase Compose file and Dockerfile to its services, images, storage, networks, ports, and checks.
- [Traefik and TLS](https://motherbase.dev/docs/self-hosting/traefik-and-tls): Configure Motherbase host routing, HTTP redirects, ACME certificate resolvers, and access middlewares.
- [Operations](https://motherbase.dev/docs/self-hosting/operations): Operate local and VPS Motherbase stacks with the scripts under deploy.
- [Environment variables](https://motherbase.dev/docs/self-hosting/environment-variables): Reference the install, Console, Traefik, Compose, and project environment from a self-hosting perspective.
- [Backups & Restore](https://motherbase.dev/docs/self-hosting/backups-and-restore): Scheduled and manual pg_dump backups, retention, offsite upload, restore, project export and staging clone.
- [Upgrades](https://motherbase.dev/docs/self-hosting/upgrades): Upgrade and roll back the Motherbase platform and individual projects while preserving Docker volumes.
- [Troubleshooting](https://motherbase.dev/docs/self-hosting/troubleshooting): Diagnose setup, Docker, routing, certificate, migration, storage, and backup failures using the commands the repository exposes.

### Reference
- [SDK Reference](https://motherbase.dev/docs/reference/sdk): Reference for @motherbase/client, the Supabase-compatible TypeScript client SDK.
- [REST API](https://motherbase.dev/docs/reference/rest-api): HTTP API reference for Motherbase core endpoints and dynamic table routes.
- [Environment](https://motherbase.dev/docs/reference/environment): Environment variables for configuring a Motherbase project, the Platform Console, the CLI, and imports.
- [Admin & HTTP API Reference](https://motherbase.dev/docs/reference/admin-api): Every route exposed by the project API controllers, with its guard chain.
- [Settings Reference](https://motherbase.dev/docs/reference/settings): Every operator-editable settings group and field, with type, default and whether it is stored encrypted.
- [Errors](https://motherbase.dev/docs/reference/errors): The response envelopes, the error classes, the default codes, and the SQLSTATE-to-message mapping.
- [OpenAPI Spec](https://motherbase.dev/docs/reference/openapi): Where the spec lives, what it covers, how it is served and how to regenerate openapi.json.

### Example
- [Todo App](https://motherbase.dev/docs/example/todo-app): A Supabase-style walkthrough with SQL, RLS policies, the REST API, SDK, and Realtime.

### Contributing
- [Repo & Toolchain](https://motherbase.dev/docs/contributing/overview): Repository layout, Node version, install, the Turborepo pipeline, and every root script.
- [Local Development](https://motherbase.dev/docs/contributing/development): Running the API, the Console and Studio locally, with Postgres, MinIO, Prisma and seed data.
- [Testing & CI](https://motherbase.dev/docs/contributing/testing): How tests are organized per workspace, how to run one, and exactly what CI enforces.
- [Code Conventions](https://motherbase.dev/docs/contributing/conventions): Folder and naming conventions on the server and in Studio, and the patterns worth following when adding code.
- [Known issues](https://motherbase.dev/docs/contributing/known-issues): What the last audit found, what was fixed, and the constraints that are deliberate rather than defects.

## Source

https://github.com/JulienGuinot/Boilerplate-backend