diff --git a/CODEBASE_MAP.md b/CODEBASE_MAP.md index 1631da3..3cde298 100644 --- a/CODEBASE_MAP.md +++ b/CODEBASE_MAP.md @@ -1,6 +1,16 @@ # BetterBase — Codebase Map -> Last updated: 2026-03-29 +> Last updated: 2026-03-30 + +## Canonical Orientation Files + +Use these as the official project index set: + +1. `NOTICE.md` — backbone summary and navigation entry point. +2. `README.md` — product overview and onboarding. +3. `CODEBASE_MAP.md` — architecture and package map (this file). +4. `docs/README.md` — complete documentation map. +5. `docs/guides/provider-capabilities-and-rollout.md` — provider limitations and rollout strategy. ## What is BetterBase? @@ -2100,4 +2110,3 @@ All notable changes to BetterBase will be documented in this file. ## License BetterBase is released under the MIT license. - diff --git a/NOTICE.md b/NOTICE.md new file mode 100644 index 0000000..3ff2362 --- /dev/null +++ b/NOTICE.md @@ -0,0 +1,110 @@ +# BetterBase Notice / Backbone Index + +> Last updated: 2026-03-30 + +This is the **backbone file** for the BetterBase repository. +It gives owners, contributors, and agents a single entry point to understand the project and navigate quickly. + +--- + +## 1) What BetterBase Is + +BetterBase is an AI-native Backend-as-a-Service platform built as a monorepo. +It provides database APIs, auth, realtime, storage, webhooks, functions, and IaC workflows with Bun-first tooling. + +--- + +## 2) Canonical Project Entry Points + +Read these in order: + +1. [`README.md`](./README.md) — product overview and quick start. +2. [`CODEBASE_MAP.md`](./CODEBASE_MAP.md) — detailed architecture and package map. +3. [`docs/README.md`](./docs/README.md) — complete docs navigation. +4. [`docs/guides/provider-capabilities-and-rollout.md`](./docs/guides/provider-capabilities-and-rollout.md) — provider limitations + rollout strategy. +5. [`SELF_HOSTED.md`](./SELF_HOSTED.md) — self-host deployment playbook. + +--- + +## 3) Repository Index (Top-Level) + +- `apps/` — runnable applications (dashboard). +- `packages/` — core libraries (`core`, `client`, `shared`, etc.). +- `docs/` — end-user and developer documentation. +- `templates/` — starter templates. +- `docker-compose*.yml` / `Dockerfile*` — runtime and deployment definitions. +- `README.md` / `CODEBASE_MAP.md` / `NOTICE.md` — core orientation docs. + +--- + +## 4) Multi-Tenant Provider Limitations (Must Read) + +Provider capabilities are **not identical**. Multi-tenant behavior must be adapted per provider. + +### Current provider limitations snapshot + +| Provider | Tenant isolation model | RLS | Branching in core | CDC/event behavior | Notes | +|---|---|---|---|---|---| +| Postgres | DB-native + app guardrails | ✅ | ✅ | ✅ LISTEN/NOTIFY | Best baseline for strict tenancy | +| Neon | DB-native + app guardrails | ✅ | ✅ | ⚠️ limited/polling fallback | Use external CDC connectors for high-fidelity streams | +| Supabase | DB-native + app guardrails | ✅ | ✅ | ✅ LISTEN/NOTIFY | Postgres-compatible model | +| Turso | App-enforced tenancy | ❌ | ❌ | ✅ SQL heuristic CDC wrapper | Enforce strict tenant filters in API | +| PlanetScale | App-enforced tenancy | ❌ | ❌ | ❌ no-op callback | Enforce strict tenant filters + scoped writes | +| Managed | N/A | N/A | N/A | N/A | Placeholder; not available yet | + +### Mandatory handling rules + +1. API-first capabilities (UI must consume API, not create UI-only behavior). +2. If provider has no native RLS, enforce tenant guardrails at application/API layer. +3. Block unscoped writes in strict multi-tenant mode. +4. Surface limitation warnings in both docs and UI. +5. Use provider-specific rollout sequencing based on capability gaps. + +Canonical guide: + +- [`docs/guides/provider-capabilities-and-rollout.md`](./docs/guides/provider-capabilities-and-rollout.md) + +--- + +## 5) Documentation Ownership Rules + +When behavior changes in code, update at least: + +- `README.md` (if product-facing behavior changed) +- `CODEBASE_MAP.md` (if architecture/package map changed) +- Relevant guide(s) in `docs/` +- `NOTICE.md` if entry points or backbone structure changed + +--- + +## 6) API and Dashboard Parity Rule + +Any new feature that can be configured in Dashboard must also be available via API. +Dashboard acts as an API client, not a separate source of truth. + +--- + +## 7) Queue / Background Workflow Limitations + +BetterBase currently documents and integrates background workflows around **Inngest**. + +- Preferred queue/workflow path: Inngest-backed jobs and event workflows. +- Self-hosted and local options are available through Inngest runtime configuration. +- There is currently no first-class Laravel Queue adapter documented in this repository. + +Handling guidance: + +1. For Laravel-based systems, integrate using HTTP/webhook/event bridge patterns first. +2. Require idempotency keys and retry-safe handlers across queue boundaries. +3. Keep queue configuration API-driven and documented per provider environment. + +--- + +## 8) Current Snapshot Notice + +This file is an orientation index, not a replacement for detailed docs. +For implementation details and current constraints, always verify against: + +- `packages/*` source +- `docs/core/*` +- `docs/guides/provider-capabilities-and-rollout.md` diff --git a/README.md b/README.md index e4f7190..cd0abe4 100644 --- a/README.md +++ b/README.md @@ -17,12 +17,30 @@ Blazing-fast backend development with Sub-100ms Local Dev — Built on Bun + SQL *Database • Authentication • Realtime Subscriptions • Storage • Serverless Functions • Vector Search* -**Last Updated: 2026-03-29** +**Last Updated: 2026-03-30** --- +## Project Backbone (Start Here) + +If you want the fastest path to understanding this repository, start with these files: + +1. [`NOTICE.md`](./NOTICE.md) — project backbone, index, and provider limitation notice. +2. [`CODEBASE_MAP.md`](./CODEBASE_MAP.md) — package/module map and architecture details. +3. [`docs/README.md`](./docs/README.md) — full documentation index. +4. [`docs/guides/provider-capabilities-and-rollout.md`](./docs/guides/provider-capabilities-and-rollout.md) — provider limitations and rollout plan. + +### Provider Rollout Status + +BetterBase supports multiple providers, but capabilities vary by provider (RLS, branching, CDC, GraphQL). +Use the rollout guide before implementing tenant isolation or provider-specific features: + +- [Provider Capabilities, Limitations, and Rollout Plan](./docs/guides/provider-capabilities-and-rollout.md) + +--- + ## Why Choose Betterbase? ``` @@ -644,4 +662,4 @@ SOFTWARE. [Website](#) • [Documentation](docs/README.md) • [Discord](https://discord.gg/R6Dm6Cgy2E) • [GitHub](https://github.com/weroperking/Betterbase) • [Twitter](#) - \ No newline at end of file + diff --git a/docs/README.md b/docs/README.md index cbfe647..4ecef75 100644 --- a/docs/README.md +++ b/docs/README.md @@ -35,7 +35,8 @@ The documentation is organized into logical sections for easy navigation: │ ├── production-checklist.md │ ├── monitoring.md │ ├── scaling.md -│ └── security-best-practices.md +│ ├── security-best-practices.md +│ └── provider-capabilities-and-rollout.md ├── api-reference/ # API documentation │ ├── client-sdk.md │ ├── cli-commands.md @@ -101,6 +102,7 @@ Development guides for production: - [Monitoring](./guides/monitoring.md) - Set up logging and metrics - [Scaling](./guides/scaling.md) - Scale your application - [Security Best Practices](./guides/security-best-practices.md) - Security hardening +- [Provider Capabilities & Rollout](./guides/provider-capabilities-and-rollout.md) - Provider limitations and implementation plan ## API Reference @@ -202,4 +204,4 @@ bb login --url https://your-instance.com This documentation is part of the BetterBase platform and is licensed under the MIT License. -© 2026 BetterBase LLC. All rights reserved. \ No newline at end of file +© 2026 BetterBase LLC. All rights reserved. diff --git a/docs/guides/provider-capabilities-and-rollout.md b/docs/guides/provider-capabilities-and-rollout.md new file mode 100644 index 0000000..aaf54b8 --- /dev/null +++ b/docs/guides/provider-capabilities-and-rollout.md @@ -0,0 +1,216 @@ +# Provider Capabilities, Limitations, and Rollout Plan + +This guide standardizes how BetterBase should handle every supported database provider in multi-tenant projects. + +It has three goals: + +1. **Make limitations explicit** so users understand tradeoffs before choosing a provider. +2. **Define a consistent implementation plan** so API and Dashboard UX behave predictably. +3. **Enforce API/UI parity** so any capability can be configured by API first and optionally through UI. + +## Source of Truth in Current Codebase + +Current core provider adapters: + +- `neon` +- `turso` +- `planetscale` +- `supabase` +- `postgres` +- `managed` (placeholder, not yet supported) + +See provider resolution and supported-provider list in code: + +- `packages/core/src/providers/index.ts` +- `packages/core/src/providers/types.ts` +- `packages/core/src/config/schema.ts` + +## Capability Matrix (Current Behavior) + +> Important: this matrix reflects the current implementation in the repository. + +| Provider | Connect Requirement | SQL Dialect | RLS | GraphQL | CDC/Event Feed | Branching in `core/branching` | +|---|---|---|---|---|---|---| +| Postgres | `connectionString` | Postgres | ✅ | ✅ | ✅ LISTEN/NOTIFY | ✅ | +| Neon | `connectionString` | Postgres | ✅ | ✅ | ⚠️ Limited/polling fallback | ✅ | +| Supabase | `connectionString` | Postgres | ✅ | ✅ | ✅ LISTEN/NOTIFY | ✅ | +| Turso | `url` + `authToken` | SQLite/libSQL | ❌ | ❌ | ✅ SQL-heuristic wrapper | ❌ | +| PlanetScale | `connectionString` | MySQL | ❌ | ❌ | ❌ (no-op callback) | ❌ | +| Managed | no DB connection | N/A | N/A | N/A | N/A | Placeholder only | + +## Provider-by-Provider Strategy + +### 1) Postgres + +**Status:** Most complete baseline. + +**What to maximize now** +- Use Postgres as the reference implementation for secure multi-tenancy. +- RLS-first design for row isolation and role-based access. +- CDC-backed webhooks/realtime patterns. + +**Known limitations** +- None material in current adapter path. + +### 2) Neon + +**Status:** Production-ready for multi-tenant with serverless posture. + +**What to maximize now** +- Same policy model as Postgres (RLS + SQL policy templates). +- Keep API behavior identical to Postgres provider where possible. + +**Known limitations** +- CDC path is marked as limited and includes polling fallback. +- For higher-fidelity event streams, support external CDC connectors as an optional advanced mode. + +### 3) Supabase + +**Status:** Strong parity with Postgres in current adapter design. + +**What to maximize now** +- Reuse Postgres policy templates. +- Keep auth-context-to-policy mapping explicit in API. + +**Known limitations** +- No major adapter-level gaps in current code. + +### 4) Turso + +**Status:** Good for edge/distributed workloads, but fewer security primitives. + +**What to maximize now** +- Use application-level tenant enforcement middleware (strict owner/tenant filters). +- Add aggressive guardrails for updates/deletes to prevent unscoped writes. + +**Known limitations** +- No native RLS in adapter contract. +- GraphQL support marked false in adapter. +- Branching unsupported in current branching module. + +### 5) PlanetScale + +**Status:** Serverless MySQL path with clear capability gaps. + +**What to maximize now** +- Application-enforced tenant guards (required `tenant_id` filters). +- Strong policy DSL in BetterBase API + generated query constraints. +- Safe SQL access with tenant-context binding only. + +**Known limitations** +- No RLS in adapter contract. +- No GraphQL in adapter contract. +- CDC callback is a no-op placeholder. +- Branching unsupported by current branching module implementation. + +### 6) Managed (Future) + +**Status:** Declared in schema and provider union but intentionally not supported yet. + +**What to maximize now** +- Keep explicit docs stating this is roadmap-only. +- Return deterministic errors and migration guidance. + +## Implementation Blueprint (All Providers) + +### Phase A: Provider Capability Registry (single source) + +Create/maintain a central capability registry consumed by: + +- API validation +- Dashboard forms +- CLI hints +- Docs generation + +Example capability keys: + +- `supportsRLS` +- `supportsGraphQL` +- `supportsBranching` +- `supportsCDC` +- `supportsTenantGuardrails` + +### Phase B: Multi-Tenant Guardrail Engine + +Implement a provider-agnostic guardrail engine for API paths: + +- Require tenant context for configured protected tables. +- Reject unscoped writes in strict mode. +- Auto-inject tenant filters in generated query builders. +- Include bypass scopes for service-role maintenance jobs (audited). + +This is the path to maximum user control while remaining safe on providers without native RLS. + +### Phase C: API-first Contract (UI as client) + +Every configurable behavior must exist in API first: + +- `POST /projects/:id/provider/capabilities` (read-only introspection) +- `POST /projects/:id/security/tenant-mode` +- `POST /projects/:id/security/table-policies` +- `POST /projects/:id/query-governance` +- `POST /projects/:id/branching/config` + +Dashboard should call these APIs directly. No UI-only settings. + +### Phase D: Provider-specific Advanced Integrations + +- PlanetScale: add provider-native branch workflow integration path. +- Neon/Supabase/Postgres: expose optional advanced CDC tuning and replay tooling. +- Turso: expand deterministic CDC mapping and conflict/retry policy controls. + +### Phase E: Queue and Workflow Interop + +- Keep Inngest as the default workflow/queue runtime in BetterBase environments. +- Add provider-aware retry/idempotency defaults for event handlers. +- Document framework bridges (including Laravel apps) via HTTP/webhook/event contracts until a first-class adapter exists. +- Require that queue configuration and visibility are API-driven (Dashboard consumes same APIs). + +## Documentation Requirements (for release readiness) + +For each provider, docs must include: + +1. Setup requirements (required env vars). +2. Capability matrix values. +3. Security model (native RLS vs app-enforced). +4. Branching behavior. +5. Realtime/CDC behavior. +6. Example tenant policy configuration. +7. "Known limitations" and recommended mitigations. + +## API/UI Parity Checklist + +Use this checklist before shipping new provider features: + +- [ ] Capability visible via API. +- [ ] Same capability configurable in Dashboard. +- [ ] CLI has discovery/help command for capability. +- [ ] Docs include exact limitation language. +- [ ] API returns actionable error messages per provider. +- [ ] Audit logs capture policy and governance changes. + +## Suggested External References (Official Docs) + +Use these during implementation and validation: + +- PostgreSQL docs: https://www.postgresql.org/docs/current/ +- Neon docs: https://neon.tech/docs +- Supabase docs: https://supabase.com/docs +- Turso docs: https://docs.turso.tech +- PlanetScale docs: https://planetscale.com/docs +- Drizzle ORM docs: https://orm.drizzle.team/docs/overview + +## Notes for Product and Engineering + +- Be explicit with users when a provider uses **application-enforced** tenancy rather than **database-native** tenancy. +- Keep behavior deterministic: same request should yield same policy enforcement regardless of UI or SDK path. +- Prefer secure defaults (`strict` tenant mode on create). + +## Related Internal Docs + +- `docs/core/providers.md` +- `docs/core/config.md` +- `docs/core/branching.md` +- `docs/core/auto-rest.md` +- `docs/features/database.md` +- `docs/features/rls.md`