Software Baas Platforms

---
name: software-baas-platforms
description: "Chooses managed backend platforms such as Supabase, Convex, and Firebase. Use when comparing database, auth, realtime, and backend-service tradeoffs."
compatibility: Portable core. Works on Claude Code and Codex.
version: "1.2"
last_validated: 2026-07-11
---

# Managed App Backends

Use this skill to choose between managed app-backend platforms when the real decision is not just "which database," but which product backend bundle should own auth, data, realtime, storage, server-side functions, and early operational tradeoffs.

This skill covers:

- SQL-first and NoSQL-first managed backend platform choice
- auth, permissions, and data-ownership model tradeoffs
- realtime sync and offline behavior differences
- self-hosted versus hosted operational tradeoffs
- migration and exit paths when a platform stops fitting

## Quick Reference

| Need | Default path | Notes |
|------|--------------|-------|
| Postgres-first product backend with RLS, auth, storage, and realtime | Supabase | Best fit when SQL portability and browser-safe Postgres workflows matter |
| TypeScript-first reactive backend with durable workflows | Convex | Best fit when live subscriptions and function-centric app logic matter more than SQL; the backend is self-hostable under FSL-Apache-2.0 (fair source, with a competing-service restriction and later Apache conversion) |
| Mobile/offline-first app with mature client SDKs | Firebase / Firestore | Strong default when device sync and mobile SDK ergonomics dominate |
| Self-hosted full backend bundle with auth, DB, storage, and functions | Appwrite | Good fit when self-hosting is a first-order requirement |
| Small single-binary app backend or internal tool | PocketBase | Good fit for prototypes and lightweight deployments, not the default for high-criticality systems; still pre-1.0 — verify current version and breaking-change posture before betting production on it |
| Branchable Postgres with separately chosen app services | PlanetScale Postgres or Neon database-only | PlanetScale is a database host; Neon also offers backend primitives. Load the comparison to decide which components you actually adopt |
| Complex compliance, bespoke domain logic, or multi-service boundaries | [../software-backend/SKILL.md](../software-backend/SKILL.md) + [../software-database-design/SKILL.md](../software-database-design/SKILL.md) | Use custom services when you need stronger control than a BaaS can provide |
| Picking the **compute host** (Vercel, Fly.io, Railway, Render, Cloudflare Workers, Deno Deploy) | [../software-paas-hosting/SKILL.md](../software-paas-hosting/SKILL.md) | Sibling skill for the compute layer; this skill is data/auth-layer only |

## Default Workflow

1. Identify the dominant constraint: SQL portability, reactive UX, mobile/offline sync, self-hosting, or speed to first product.
2. Decide whether the platform should own auth, storage, and server-side logic or only the database.
3. Choose the simplest platform that matches the product shape without hiding the security model.
4. Load [migration-exit-strategies.md](references/migration-exit-strategies.md) for schema, identity, storage, and workflow export checks before committing.
5. Load [platform-comparison.md](references/platform-comparison.md) to check product status, Firebase alternatives, and the provider-specific billing/pausing lookup before recommending a plan.
6. For managed agent primitives, load [aws-bedrock-as-agent-baas.md](references/aws-bedrock-as-agent-baas.md); keep application data and end-user auth ownership explicit.

## Platform Selection Rules

| Platform | Primary Signal | Security Starting Point |
|----------|----------------|------------------------|
| Supabase | Postgres as source of truth; SQL, RLS, Realtime, Auth, Storage, Edge Functions in one stack | Schema design + RLS policy quality |
| Convex | TypeScript-heavy interactive product; queries, mutations, actions, subscriptions, durable workflows | Function boundaries, auth propagation, server-owned writes |
| Firebase / Firestore | Offline-first; mature mobile/web SDKs; client-driven sync more important than SQL portability | Rules quality, offline conflict expectations, client trust boundaries |
| Appwrite | Self-hosting first; project-level permissions; integrated auth/DB/functions/storage | Hosting model, admin surface exposure, secrets isolation |
| PocketBase | Extremely small deployment; operational simplicity over ecosystem depth, HA, or long-term guarantees | Admin surface exposure; not for high-criticality systems |
| Custom backend | Complex compliance, highly specific domain services, independent scaling across services | Use [../software-backend/SKILL.md](../software-backend/SKILL.md) + threat model |

If the team cannot clearly explain who is allowed to read and write each record, do not pick the platform yet.

**Supabase vs. Firebase, as an actual decision (not a preference)**: pick Supabase/Postgres+RLS when the team already thinks in SQL, needs ad-hoc joins/reporting, or wants a Postgres schema with an exit path tested for extension, role, and managed-feature compatibility on the destination (RDS, Neon, PlanetScale, self-hosted). Pick Firebase/Firestore when the product is mobile-first, needs offline caching and client synchronization, and the data shape is naturally document-like with shallow queries. The tie-breaker is usually query complexity: complex relational queries and reporting favor Supabase; simple per-document reads/writes at high device-offline tolerance favor Firebase. Do not decide this on team familiarity alone — RLS policy bugs and permissive Firestore rules are both common breach vectors, so budget real review time either way.

## Operational Gotchas

Critical production patterns documented from real incidents. See [references/platform-comparison.md](references/platform-comparison.md) for full details.

- **PostgREST-style filter APIs can hit URL or proxy length limits** when large ID lists are serialized into query parameters. Batch aggressively and verify the deployed edge limit before assuming giant `.in()` filters are safe.
- **Admin and user-list APIs are usually paginated**. Never assume a single call enumerates the full tenant; check current page-size defaults and iterate explicitly.
- **Egress/bandwidth overages are a recurring hidden-cost trap**, not a rounding error, on Postgres-hosted BaaS (Supabase, Neon, PlanetScale): media-heavy or high-read apps can blow past included egress allowances quickly, and the per-GB overage rate is a volatile, frequently-revised number. Model expected monthly egress (database + storage + cached vs. uncached) before committing, and verify the current allowance and $/GB rate at the platform's official pricing page — do not rely on a remembered figure.

## When To Use This Skill

Use this skill when the user asks:

- "Should I use Supabase or Convex?"
- "Is Firebase still the better choice for this app?"
- "What is the best managed backend for a startup MVP?"
- "Should I keep Supabase or move to a custom backend?"
- "How do Appwrite and PocketBase compare to Supabase?"

## When NOT To Use This Skill

- Native iOS app skeletons that explicitly want iCloud/CloudKit instead of Supabase, Vercel, Firebase, or another backend platform -> [software-ios-native](../software-ios-native/SKILL.md).
- Apple-only private user data synced through SwiftData/Core Data + CloudKit -> [software-ios-native](../software-ios-native/SKILL.md).
- On-device Apple Foundation Models, local semantic search, or iOS-local retrieval/vector storage -> [software-ios-ai-engine](../software-ios-ai-engine/SKILL.md).
- App Intents, Siri, Spotlight, widgets, controls, or Apple Intelligence system exposure for a native iOS app -> [software-ios-native](../software-ios-native/SKILL.md), then [software-ios-ai-engine](../software-ios-ai-engine/SKILL.md) if local AI is involved.

## Pre-Commit Checklist

Before committing to a BaaS platform, verify:

- [ ] Permission model documented: who can read and write each record type
- [ ] Security model tested: two isolated tenants or users cannot access each other's data
- [ ] Exit path audited: schema portability, auth migration, storage migration, client-SDK lock-in assessed
- [ ] Compliance requirements mapped: no pending compliance gap that requires custom service boundaries
- [ ] Operational budget confirmed: self-hosted option has budget for upgrades, backups, monitoring, secrets rotation
- [ ] Server-owned writes identified: writes that must not originate from client code are protected at the platform layer
- [ ] Exit proof scaled to lock-in and consequence: always inventory exportability, stable IDs, and platform dependencies; sample-export material data, identities, and files for ordinary selection; require a timed neutral-target restore only for a material production commitment or when switching risk decides the choice

An exit diagram is not proof of portability. Keep stable application-owned IDs across auth and data, inventory platform-specific SDK calls, and record what cannot be exported automatically and who owns the manual step. Use external restore infrastructure only when it is within the authorized task and the proof is proportionate to the decision.

## Known Traps

- Choosing a platform from a feature checklist without first validating its permission model, trust boundaries, and operator responsibilities.
- Assuming an exit path is cheap because the underlying database looks portable, while ignoring auth, storage, realtime, function, and client-SDK coupling.
- Stretching a managed platform into compliance-heavy or domain-heavy workflows that need custom service boundaries.
- Picking self-hosting as the “safer” answer without budgeting for upgrades, secrets handling, backups, monitoring, and operational ownership.
- Letting frontend convenience determine the backend boundary before deciding which writes must stay server-owned.
- Sizing total cost of ownership on the advertised plan price alone while ignoring egress, compute add-ons, and overage rates that materially change the real bill at scale.

- Using service-role or admin credentials in clients to bypass permission design.
- Treating the platform commitment as permanent without explicit revisit triggers.

## Scenarios

Recipes keyed to platform-selection or integration moments. Each lists the shortest path to a correct, safe implementation.

### S1 — Supabase RLS for multi-tenant SaaS

1. Add a `tenant_id` column (FK to `tenants`) to every data table; never rely on application-layer filtering alone.
2. Enable RLS on each table: `ALTER TABLE foo ENABLE ROW LEVEL SECURITY;`.
3. Put the tenant claim where users cannot write it: `app_metadata` (server-set), never `user_metadata` (user-editable). Use a custom access-token hook only if you need a top-level claim.
4. Write a `SELECT` policy that wraps the JWT read in a sub-select (evaluated once per statement) and casts to the column type: `USING (tenant_id = ((select auth.jwt()) -> 'app_metadata' ->> 'tenant_id')::uuid)` — `::uuid` only if `tenant_id` is uuid. Index `tenant_id`; unindexed policy predicates can cause expensive scans; inspect the actual EXPLAIN plan.
5. Repeat for `INSERT`, `UPDATE`, `DELETE` policies; leave deliberately inaccessible tables default-deny; add policies only for intended operations and set grants independently.
6. Test with two separate authenticated users: confirm cross-tenant data is invisible. See [references/security-and-ownership-models.md](references/security-and-ownership-models.md).
7. Add CI allow/deny tests for every operation, including tenant-B attempts against tenant-A rows. The Dashboard [RLS Tester](https://supabase.com/changelog/45233-feature-preview-rls-tester) can help debug policies; check its supported operations before use and retain mutation tests outside any SELECT-only UI.

### S2 — Convex action vs mutation routing

1. Identify whether the operation reads/writes Convex tables only, or calls an external service or API.
2. Use a **mutation** for pure Convex reads/writes: transactional, deterministic, retryable by the runtime.
3. Use an **action** for any external I/O (HTTP calls, third-party APIs, file uploads); actions are not transactional.
4. From an action, call internal mutations to persist results; never write to the database directly in an action.
5. Verify scheduling: use `ctx.scheduler.runAfter` inside mutations for deferred work; do not spawn actions ad-hoc from the client.

### S3 — Firebase rules + App Check for mobile-only client

1. Enable App Check with the appropriate attestation provider (Play Integrity on Android, App Attest on iOS).
2. In Firebase console, enforce App Check for Firestore and Storage — unverified clients are blocked at the platform level.
3. For existing records, check the authenticated UID against `resource.data.userId`; on create use `request.resource.data.userId`. On update prevent changing the owner field.
4. Leave unmatched paths denied. A catch-all deny does not override an overlapping allow: Firebase rules combine matching allows with OR.
5. Test rules with the Firebase Emulator Suite: run the rules unit-test suite on every PR. See [references/security-and-ownership-models.md](references/security-and-ownership-models.md).

### S4 — BaaS-to-self-hosted exit plan trigger

1. Identify the exit trigger: vendor pricing change, compliance requirement, or outgrown platform boundary.
2. Audit coupling: schema portability, auth migration path, storage bucket ownership, edge function replacement, client SDK lock-in.
3. For Supabase: export schema/data and inspect the Auth schema separately; an admin user listing is not proof that password hashes, MFA factors, or sessions transfer. Copy storage objects and their access metadata separately.
4. Verify parallel-stack parity on auth flows, realtime subscriptions, and RLS behavior; choose the observation window from traffic and rollback requirements.
5. Cut over DNS/config with rollback criteria; decommission only after the agreed retention and recovery checks pass. See [references/migration-exit-strategies.md](references/migration-exit-strategies.md).

### S5 — Per-platform secrets boundary

1. Never commit secret keys or admin credentials to the repo; use environment variables in the deployment platform.
2. For browser/mobile clients: use the Supabase publishable key (`sb_publishable_...`) + RLS, or Firebase `apiKey` + rules — these are intentionally public-facing but constrained by policy.
3. For server-side operations (webhooks, admin tasks): use the Supabase secret key (`sb_secret_...`) or admin credentials only in backend functions, never in client bundles.
4. Supabase is deprecating the legacy JWT-based `anon` / `service_role` keys by the end of 2026: migrate to publishable/secret keys, then disable the legacy keys in the dashboard (Settings > API Keys).
5. Rotate secrets after any suspected exposure; verify rotation does not break existing auth sessions before cutting over.
6. Document required env vars in the sibling YAML with descriptive placeholders; never real values.

## Navigation

**References**
- [references/platform-comparison.md](references/platform-comparison.md) - platform fit, data model, and strongest-use-case matrix
- [references/security-and-ownership-models.md](references/security-and-ownership-models.md) - RLS, function auth, rules engines, and permission surfaces
- [references/migration-exit-strategies.md](references/migration-exit-strategies.md) - signals that a platform no longer fits and practical exit paths
- [references/aws-bedrock-as-agent-baas.md](references/aws-bedrock-as-agent-baas.md) - AWS Bedrock AgentCore as a BaaS-for-agents: primitives, platform fit, and pairing
- [data/sources.json](data/sources.json) - official platform docs and supporting primary sources

**Related Skills**
- [../software-database-design/SKILL.md](../software-database-design/SKILL.md) - schema shape, migrations, and relational/document modeling
- [../software-backend/SKILL.md](../software-backend/SKILL.md) - custom backend services when a managed platform is no longer enough
- [../software-realtime/SKILL.md](../software-realtime/SKILL.md) - transport and collaboration decisions after platform choice
- [../software-mobile/SKILL.md](../software-mobile/SKILL.md) - mobile product delivery and offline-first client decisions
- [../software-ios-native/SKILL.md](../software-ios-native/SKILL.md) - Apple-native iOS app skeletons, SwiftData/Core Data, CloudKit/iCloud, App Intents, and release gates
- [../software-ios-ai-engine/SKILL.md](../software-ios-ai-engine/SKILL.md) - Apple Foundation Models, on-device local AI, and iOS-local retrieval/vector search
- [../software-security-appsec/SKILL.md](../software-security-appsec/SKILL.md) - secure design, auth, and secrets handling

## Learnings Loop

When prior decisions or pitfalls are relevant, consult `learnings.consolidated.md` if present; use `learnings.md` only for needed history or as the available fallback. Otherwise skip both.

After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to `learnings.md` via `agents-skills-feedback-loop/scripts/append_learning.py`. Do not modify `SKILL.md` itself.