From 1999fe32a9ea0bc91900fe133ffd19585dbf2c8e Mon Sep 17 00:00:00 2001 From: weroperking <139503221+weroperking@users.noreply.github.com> Date: Sat, 21 Mar 2026 14:23:40 +0000 Subject: [PATCH 1/2] Updates both README.MD and CODEBASE_MAP.MD files with the latest PR 36 Updates --- CODEBASE_MAP.md | 404 +++++++++++++++++++++++++++++++++++++----------- README.md | 275 ++++++++++++++++++++++---------- 2 files changed, 507 insertions(+), 172 deletions(-) diff --git a/CODEBASE_MAP.md b/CODEBASE_MAP.md index 4a2fba9..bd22432 100644 --- a/CODEBASE_MAP.md +++ b/CODEBASE_MAP.md @@ -1,6 +1,6 @@ # BetterBase — Complete Codebase Map -> Last updated: 2026-03-19 +> Last updated: 2026-03-21 ## Project Identity @@ -49,15 +49,21 @@ graph TB end subgraph packages - CLI[packages/cli
12 commands
7 utils] - Client[packages/client
9 modules] - Core[packages/core
11 modules] + CLI[packages/cli
14 commands
8 utils] + Client[packages/client
7 modules] + Core[packages/core
14 modules] + Shared[packages/shared
5 modules] end subgraph apps TestProject[apps/test-project
Example project] end + subgraph templates + Base[templates/base
Base template] + Auth[templates/auth
Auth template] + end + subgraph external CliAuth[cli-auth-page
Auth UI] end @@ -65,7 +71,10 @@ graph TB Root --> CLI Root --> Client Root --> Core + Root --> Shared Root --> TestProject + Root --> Base + Root --> Auth ``` ``` @@ -86,36 +95,40 @@ betterbase/ │ │ ├── src/ │ │ │ ├── index.ts # Main CLI entry point │ │ │ ├── build.ts # Build script -│ │ │ ├── constants.ts # Shared constants -│ │ │ ├── commands/ # CLI commands (11 files) -│ │ │ │ ├── auth.ts # bb auth setup - BetterAuth integration -│ │ │ │ ├── dev.ts # bb dev - Development server with watch -│ │ │ │ ├── function.ts # bb function - Serverless function management -│ │ │ │ ├── generate.ts # bb generate crud - CRUD route generation -│ │ │ │ ├── graphql.ts # bb graphql - GraphQL management -│ │ │ │ ├── init.ts # bb init - Project initialization -│ │ │ │ ├── login.ts # bb login - Cloud authentication -│ │ │ │ ├── migrate.ts # bb migrate - Database migrations -│ │ │ │ ├── rls.ts # bb rls - Row Level Security management -│ │ │ │ ├── storage.ts # bb storage - Storage bucket management -│ │ │ │ ├── webhook.ts # bb webhook - Webhook management -│ │ │ │ └── branch.ts # bb branch - Branch management -│ │ │ └── utils/ # CLI utilities (7 files) +│ │ │ ├── constants.ts # Shared constants +│ │ │ ├── commands/ # CLI commands (14 files) +│ │ │ │ ├── auth.ts # bb auth setup - BetterAuth integration +│ │ │ │ ├── auth-providers.ts # bb auth add-provider - OAuth provider management +│ │ │ │ ├── dev.ts # bb dev - Development server with watch +│ │ │ │ ├── function.ts # bb function - Edge function management +│ │ │ │ ├── generate.ts # bb generate crud - CRUD route generation +│ │ │ │ ├── graphql.ts # bb graphql - GraphQL management +│ │ │ │ ├── init.ts # bb init - Project initialization +│ │ │ │ ├── login.ts # bb login - Cloud authentication +│ │ │ │ ├── migrate.ts # bb migrate - Database migrations +│ │ │ │ ├── migrate-utils.ts # Migration utilities +│ │ │ │ ├── rls.ts # bb rls - Row Level Security management +│ │ │ │ ├── rls-test.ts # bb rls test - RLS policy testing +│ │ │ │ ├── storage.ts # bb storage - Storage bucket management +│ │ │ │ ├── webhook.ts # bb webhook - Webhook management +│ │ │ │ └── branch.ts # bb branch - Branch management +│ │ │ └── utils/ # CLI utilities (8 files) │ │ │ ├── context-generator.ts # Generates .betterbase-context.json │ │ │ ├── logger.ts # Colored console logging -│ │ │ ├── prompts.ts # Interactive prompts (Inquirer) -│ │ │ ├── provider-prompts.ts # Database provider selection -│ │ │ ├── route-scanner.ts # Hono route scanning -│ │ │ ├── schema-scanner.ts # Drizzle schema scanning -│ │ │ └── scanner.ts # Schema scanner core -│ │ └── test/ # CLI tests (14+ test files) +│ │ │ ├── prompts.ts # Interactive prompts (Inquirer) +│ │ │ ├── provider-prompts.ts # Database provider selection +│ │ │ ├── route-scanner.ts # Hono route scanning +│ │ │ ├── schema-scanner.ts # Drizzle schema scanning +│ │ │ ├── scanner.ts # Schema scanner core +│ │ │ └── migrate-utils.ts # Migration utilities +│ │ └── test/ # CLI tests (20+ test files) │ │ -│ ├── client/ # @betterbase/client - TypeScript SDK +│ ├── client/ # @betterbase/client - TypeScript SDK │ │ ├── package.json │ │ ├── tsconfig.json │ │ ├── tsconfig.test.json │ │ ├── README.md -│ │ ├── src/ # Client SDK source +│ │ ├── src/ # Client SDK source │ │ │ ├── index.ts # Package exports │ │ │ ├── auth.ts # Authentication client │ │ │ ├── build.ts # Build configuration @@ -125,99 +138,173 @@ betterbase/ │ │ │ ├── realtime.ts # Realtime subscription client │ │ │ ├── storage.ts # Storage client │ │ │ └── types.ts # TypeScript definitions -│ │ └── test/ # Client tests (6+ test files) +│ │ └── test/ # Client tests (6+ test files) │ │ -│ ├── core/ # @betterbase/core - Core backend engine +│ ├── core/ # @betterbase/core - Core backend engine │ │ ├── package.json │ │ ├── README.md │ │ ├── tsconfig.json │ │ └── src/ │ │ ├── index.ts # Core exports +│ │ ├── auto-rest.ts # Auto-REST: Automatic CRUD route generation │ │ ├── config/ # Configuration modules -│ │ │ ├── index.ts # Config exports -│ │ │ ├── schema.ts # Project config schema (Zod) +│ │ │ ├── index.ts # Config exports +│ │ │ ├── schema.ts # Project config schema (Zod) │ │ │ └── drizzle-generator.ts # Drizzle config generator │ │ ├── functions/ # Serverless functions -│ │ │ ├── index.ts # Functions exports -│ │ │ ├── bundler.ts # Function bundler (esbuild) -│ │ │ └── deployer.ts # Function deployer +│ │ │ ├── index.ts # Functions exports +│ │ │ ├── bundler.ts # Function bundler (esbuild) +│ │ │ ├── deployer.ts # Function deployer +│ │ │ └── local-runtime.ts # Local functions runtime │ │ ├── graphql/ # GraphQL server -│ │ │ ├── index.ts # GraphQL exports -│ │ │ ├── resolvers.ts # GraphQL resolvers +│ │ │ ├── index.ts # GraphQL exports +│ │ │ ├── resolvers.ts # GraphQL resolvers │ │ │ ├── schema-generator.ts # Schema from DB -│ │ │ ├── sdl-exporter.ts # SDL export -│ │ │ └── server.ts # GraphQL HTTP server +│ │ │ ├── sdl-exporter.ts # SDL export +│ │ │ ├── server.ts # GraphQL HTTP server +│ │ │ └── realtime-bridge.ts # GraphQL subscriptions bridge │ │ ├── middleware/ # Middleware -│ │ │ ├── index.ts # Middleware exports -│ │ │ └── rls-session.ts # RLS session middleware -│ │ ├── migration/ # Database migrations -│ │ │ ├── index.ts # Migration exports +│ │ │ ├── index.ts # Middleware exports +│ │ │ ├── rls-session.ts # RLS session middleware +│ │ │ └── request-logger.ts # Request logging middleware +│ │ ├── migration/ # Database migrations +│ │ │ ├── index.ts # Migration exports │ │ │ └── rls-migrator.ts # RLS policy migration -│ │ ├── providers/ # Database providers -│ │ │ ├── index.ts # Provider exports -│ │ │ ├── types.ts # Provider interfaces -│ │ │ ├── neon.ts # Neon serverless PostgreSQL -│ │ │ ├── planetscale.ts # PlanetScale MySQL -│ │ │ ├── postgres.ts # PostgreSQL -│ │ │ ├── supabase.ts # Supabase-compatible -│ │ │ └── turso.ts # Turso libSQL -│ │ ├── rls/ # Row Level Security -│ │ │ ├── index.ts # RLS exports -│ │ │ ├── types.ts # RLS type definitions -│ │ │ ├── scanner.ts # RLS policy scanner -│ │ │ ├── generator.ts # RLS policy generator -│ │ │ └── auth-bridge.ts # Auth-RLS bridge -│ │ ├── storage/ # Storage adapter -│ │ │ ├── index.ts # Storage exports -│ │ │ ├── types.ts # Storage types -│ │ │ └── s3-adapter.ts # S3-compatible adapter -│ │ └── webhooks/ # Webhook handling -│ │ ├── index.ts # Webhook exports -│ │ ├── types.ts # Webhook types -│ │ ├── dispatcher.ts # Event dispatcher -│ │ ├── integrator.ts # DB trigger integration -│ │ ├── signer.ts # Payload signing -│ │ └── startup.ts # Server initialization -│ +│ │ ├── providers/ # Database providers +│ │ │ ├── index.ts # Provider exports +│ │ │ ├── types.ts # Provider interfaces +│ │ │ ├── neon.ts # Neon serverless PostgreSQL +│ │ │ ├── planetscale.ts # PlanetScale MySQL +│ │ │ ├── postgres.ts # PostgreSQL +│ │ │ ├── supabase.ts # Supabase-compatible +│ │ │ └── turso.ts # Turso libSQL +│ │ ├── rls/ # Row Level Security +│ │ │ ├── index.ts # RLS exports +│ │ │ ├── types.ts # RLS type definitions +│ │ │ ├── scanner.ts # RLS policy scanner +│ │ │ ├── generator.ts # RLS policy generator +│ │ │ ├── evaluator.ts # RLS policy evaluator (SQLite) +│ │ │ └── auth-bridge.ts # Auth-RLS bridge +│ │ ├── storage/ # Storage adapter +│ │ │ ├── index.ts # Storage exports +│ │ │ ├── types.ts # Storage types +│ │ │ ├── s3-adapter.ts # S3-compatible adapter +│ │ │ ├── image-transformer.ts # Image transformations (Sharp) +│ │ │ └── policy-engine.ts # Storage policy engine +│ │ ├── webhooks/ # Webhook handling +│ │ │ ├── index.ts # Webhook exports +│ │ │ ├── types.ts # Webhook types +│ │ │ ├── dispatcher.ts # Event dispatcher +│ │ │ ├── integrator.ts # DB trigger integration +│ │ │ ├── signer.ts # Payload signing +│ │ │ ├── startup.ts # Server initialization +│ │ │ └── schema.sql # Webhook schema +│ │ ├── vector/ # Vector search (pgvector) +│ │ │ ├── index.ts # Vector exports +│ │ │ ├── types.ts # Vector column types +│ │ │ ├── embeddings.ts # Embedding providers (OpenAI, Cohere) +│ │ │ └── search.ts # Vector similarity search +│ │ ├── branching/ # Preview environments +│ │ │ ├── index.ts # Branching exports +│ │ │ ├── types.ts # Branch types +│ │ │ ├── database.ts # Database branching +│ │ │ └── storage.ts # Storage branching +│ │ ├── logger/ # Logging +│ │ │ ├── index.ts # Logger exports +│ │ │ └── file-transport.ts # File transport +│ │ └── realtime/ # Realtime subscriptions +│ │ ├── index.ts # Realtime exports +│ │ └── channel-manager.ts # Channel manager +│ │ +│ ├── shared/ # @betterbase/shared - Shared utilities +│ │ ├── package.json +│ │ ├── tsconfig.json +│ │ └── src/ +│ │ ├── index.ts # Main exports +│ │ ├── types.ts # Shared types +│ │ ├── errors.ts # Shared error classes +│ │ ├── constants.ts # Shared constants +│ │ └── utils.ts # Utility functions +│ │ ├── apps/ │ └── test-project/ # Example/test project -│ ├── betterbase.config.ts # Project configuration +│ ├── betterbase.config.ts # Project configuration │ ├── drizzle.config.ts # Drizzle configuration │ ├── package.json │ ├── tsconfig.json │ ├── README.md │ ├── src/ -│ │ ├── index.ts # App entry point +│ │ ├── index.ts # App entry point (Hono server) │ │ ├── auth/ -│ │ │ ├── index.ts # Auth module -│ │ │ └── types.ts # Auth types +│ │ │ ├── index.ts # Auth module +│ │ │ └── types.ts # Auth types │ │ ├── db/ -│ │ │ ├── index.ts # Database setup -│ │ │ ├── migrate.ts # Migration runner -│ │ │ ├── schema.ts # Database schema +│ │ │ ├── index.ts # Database setup +│ │ │ ├── migrate.ts # Migration runner +│ │ │ ├── schema.ts # Database schema │ │ │ └── policies/ # RLS policies │ │ │ └── .gitkeep -│ │ ├── functions/ # Serverless functions -│ │ │ └── .gitkeep +│ │ ├── functions/ # Serverless functions +│ │ │ └── hello/ # Example function +│ │ │ └── index.ts │ │ ├── lib/ -│ │ │ ├── env.ts # Environment vars -│ │ │ └── realtime.ts # Realtime events +│ │ │ ├── env.ts # Environment vars +│ │ │ └── realtime.ts # Realtime events │ │ ├── middleware/ -│ │ │ ├── auth.ts # Auth middleware -│ │ │ └── validation.ts # Validation middleware +│ │ │ ├── auth.ts # Auth middleware +│ │ │ └── validation.ts # Validation middleware │ │ └── routes/ -│ │ ├── index.ts # Routes registration -│ │ ├── health.ts # Health check -│ │ ├── storage.ts # Storage routes -│ │ ├── users.ts # User CRUD routes -│ │ └── graphql.d.ts # GraphQL types +│ │ ├── index.ts # Routes registration +│ │ ├── health.ts # Health check +│ │ ├── storage.ts # Storage routes +│ │ ├── users.ts # User CRUD routes +│ │ ├── webhooks.ts # Webhook routes +│ │ └── graphql.d.ts # GraphQL types │ └── test/ # Project tests │ ├── crud.test.ts │ └── health.test.ts │ -├── cli-auth-page/ # Standalone auth page for CLI (not a template) +├── templates/ +│ ├── base/ # Base project template +│ │ ├── src/ +│ │ │ ├── index.ts # Main entry point +│ │ │ ├── routes/ # API routes +│ │ │ ├── functions/ # Edge functions +│ │ │ ├── auth/ # Authentication +│ │ │ ├── middleware/ # Middleware +│ │ │ ├── lib/ # Utilities +│ │ │ └── db/ # Database (schema, migrations) +│ │ ├── test/ +│ │ ├── betterbase.config.ts +│ │ ├── drizzle.config.ts +│ │ ├── package.json +│ │ └── README.md +│ │ +│ └── auth/ # Auth project template +│ ├── src/ +│ │ ├── routes/ +│ │ │ ├── auth.ts # Auth routes +│ │ │ └── auth-example.ts +│ │ ├── auth/ +│ │ │ ├── index.ts +│ │ │ └── types.ts +│ │ ├── db/ +│ │ │ ├── schema.ts +│ │ │ ├── auth-schema.ts +│ │ │ └── index.ts +│ │ └── middleware/ +│ │ └── auth.ts +│ ├── README.md +│ └── (template files) +│ +├── cli-auth-page/ # Standalone auth page for CLI (not a template) │ ├── .gitignore -│ └── index.html # Auth UI entry +│ └── index.html # Auth UI entry +│ +├── new-features-docs/ # Documentation for new features +│ └── README_START_HERE.md +│ +└── scripts/ # Build/release scripts ``` --- @@ -511,7 +598,18 @@ betterbase/ - Evaluates storage access policies - Supports path-based access control - Integrates with RLS user context - - New: `evaluateStoragePolicy()` function for policy evaluation + - `evaluateStoragePolicy()` function for policy evaluation + +#### [`storage/image-transformer.ts`](packages/core/src/storage/image-transformer.ts) +**Purpose:** On-the-fly image transformations using Sharp. +- **Exports:** `ImageTransformer`, `createImageTransformer`, `TransformOptions` +- **Key Features:** + - Resize images (width, height, fit modes) + - Crop images to specific dimensions + - Format conversion (JPEG, PNG, WebP, AVIF) + - Quality adjustment + - Auto-optimization + - Lazy transformation (on-demand) ### vector/ @@ -666,6 +764,44 @@ Preview Environments module for creating isolated development branches. - `WebhookConfig`: Webhook configuration (id, table, events, url, secret, enabled) - `WebhookPayload`: Payload sent to webhook endpoint (id, webhook_id, table, type, record, old_record, timestamp) +### logger/ + +Logging module for application-wide logging capabilities. + +#### [`logger/index.ts`](packages/core/src/logger/index.ts) +**Purpose:** Logger module exports. +- **Exports:** `BetterBaseLogger`, `createLogger`, `logLevel`, `LogEntry` +- **Key Features:** + - Configurable log levels (debug, info, warn, error) + - Structured logging with metadata + - File transport support + - Console output with colors + +#### [`logger/file-transport.ts`](packages/core/src/logger/file-transport.ts) +**Purpose:** File-based logging transport. +- **Exports:** `FileTransport`, `createFileTransport` +- **Key Features:** + - Rotating log files + - Configurable file paths + - Log rotation by size or time + +### realtime/ + +Realtime subscriptions module for WebSocket-based live data updates. + +#### [`realtime/index.ts`](packages/core/src/realtime/index.ts) +**Purpose:** Realtime module exports. +- **Exports:** `RealtimeManager`, `createRealtimeManager`, `Channel`, `Subscription` + +#### [`realtime/channel-manager.ts`](packages/core/src/realtime/channel-manager.ts) +**Purpose:** Channel manager for managing WebSocket subscriptions. +- **Exports:** `ChannelManager`, `createChannelManager` +- **Key Features:** + - Subscribe to database changes (INSERT, UPDATE, DELETE) + - Filter by table, schema, or specific records + - Automatic reconnection with exponential backoff + - Presence detection for collaborative features + --- ## packages/client @@ -892,6 +1028,34 @@ Canonical `@betterbase/cli` implementation - the `bb` command-line tool. - **Usage Patterns:** Manage preview environments for development branches. - **External Deps:** `chalk` +#### [`commands/auth-providers.ts`](packages/cli/src/commands/auth-providers.ts) +**Purpose:** `bb auth add-provider` command - OAuth provider management. +- **Exports:** `runAuthProviderCommand(options)` - main function +- **Key Functions:** `addProvider()`, `removeProvider()`, `listProviders()` +- **Supported Providers:** google, github, discord, apple, microsoft, twitter, facebook +- **Internal Deps:** `../utils/logger`, `../utils/prompts` +- **Usage Patterns:** Add or remove OAuth authentication providers. +- **Implementation Details:** Updates BetterAuth configuration with provider credentials. +- **External Deps:** `chalk`, `inquirer` + +#### [`commands/migrate-utils.ts`](packages/cli/src/commands/migrate-utils.ts) +**Purpose:** Migration utilities for the CLI. +- **Exports:** `analyzeMigration()`, `splitStatements()`, `collectChangesFromGenerate()` +- **Key Functions:** Migration analysis and SQL parsing +- **Internal Deps:** `../utils/logger`, `zod` +- **Usage Patterns:** Used by migrate command for migration management. +- **Implementation Details:** Parses SQL files, analyzes changes, supports rollback planning. +- **External Deps:** `zod`, `chalk` + +#### [`commands/rls-test.ts`](packages/cli/src/commands/rls-test.ts) +**Purpose:** `bb rls test` command - Test RLS policies for a table. +- **Exports:** `runRLSTestCommand(projectRoot, tableName)` - main function +- **Key Functions:** `testRLSPolicies()`, `verifyPolicy()`, `simulateQuery()` +- **Internal Deps:** `../utils/logger`, `../utils/schema-scanner` +- **Usage Patterns:** Test RLS policies before deploying to production. +- **Implementation Details:** Simulates queries as different users to verify RLS policy correctness. +- **External Deps:** `chalk`, `drizzle-orm` + ### CLI Utilities #### [`utils/logger.ts`](packages/cli/src/utils/logger.ts) @@ -975,6 +1139,68 @@ Canonical `@betterbase/cli` implementation - the `bb` command-line tool. --- +## packages/shared + +`@betterbase/shared` - Shared utilities and types used across all packages. + +### Shared Modules + +#### [`src/types.ts`](packages/shared/src/types.ts) +**Purpose:** Common TypeScript type definitions. +- **Exports:** `BetterBaseResponse`, `ProviderType`, `DatabaseCredentials`, `StorageConfig`, etc. +- **Key Types:** + - `BetterBaseResponse`: Standard response wrapper { data, error } + - `ProviderType`: "postgres" | "mysql" | "sqlite" | "neon" | "turso" | "planetscale" | "supabase" + - `DatabaseCredentials`: Connection configuration interface + - `StorageConfig`: Storage provider configuration + +#### [`src/errors.ts`](packages/shared/src/errors.ts) +**Purpose:** Shared error classes across all packages. +- **Exports:** `BetterBaseError`, `ValidationError`, `DatabaseError`, `AuthError`, `StorageError` +- **Key Features:** All errors extend base Error class with code, status, and details + +#### [`src/constants.ts`](packages/shared/src/constants.ts) +**Purpose:** Shared constants used across the platform. +- **Exports:** `VERSION`, `DEFAULT_PORT`, `DEFAULT_POOL_SIZE`, `DEFAULT_TIMEOUT`, etc. + +#### [`src/utils.ts`](packages/shared/src/utils.ts) +**Purpose:** Utility functions for validation, formatting, etc. +- **Exports:** `validateEmail()`, `formatDate()`, `slugify()`, `generateId()`, etc. + +--- + +## Templates + +BetterBase provides project templates for quick project initialization. + +### templates/base + +The base template with essential project structure. + +- **Path:** `templates/base/` +- **Purpose:** Starting point for new BetterBase projects +- **Includes:** + - Basic Hono server setup + - Database schema with users example + - Authentication middleware + - Storage routes + - Health check endpoint + +### templates/auth + +The authentication template with full BetterAuth integration. + +- **Path:** `templates/auth/` +- **Purpose:** Projects requiring authentication out of the box +- **Includes:** + - Pre-configured BetterAuth setup + - Email/password authentication + - Social OAuth providers (configurable) + - Session management + - Auth middleware examples + +--- + ## Usage Examples ### Client SDK diff --git a/README.md b/README.md index 7b3c0e1..d0ab651 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ Betterbase is an open-source alternative to Supabase, built with Bun for blazing -**Last Updated: 2026-03-19** +**Last Updated: 2026-03-21** --- @@ -32,22 +32,28 @@ Traditional backend development is slow. You spend weeks setting up databases, a │ BETTERBASE ARCHITECTURE │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ -│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ -│ │ Frontend │────▶│ Betterbase │────▶│ Database │ │ -│ │ (React, │ │ Core │ │ (SQLite, │ │ -│ │ Vue, │ │ │ │ Postgres, │ │ -│ │ Mobile) │ │ ┌────────┐ │ │ MySQL, │ │ -│ └──────────────┘ │ │ Auth │ │ │ Neon...) │ │ -│ │ ├────────┤ │ └──────────────┘ │ -│ ┌──────────────┐ │ │ Realtime│ │ │ -│ │ Serverless │────▶│ ├────────┤ │ ┌──────────────┐ │ -│ │ Functions │ │ │Storage │ │ │ S3 Storage │ │ -│ └──────────────┘ │ ├────────┤ │ └──────────────┘ │ -│ │ │GraphQL │ │ │ -│ ┌──────────────┐ │ ├────────┤ │ ┌──────────────┐ │ -│ │ Webhooks │────▶│ │ RLS │ │ │ External │ │ -│ └──────────────┘ │ └────────┘ │ │ Services │ │ -│ └──────────────┘ └──────────────┘ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ Frontend │──────▶│ Betterbase │──────▶│ Database │ │ +│ │ (React, │ │ Core │ │ (SQLite, │ │ +│ │ Vue, │ │ │ │ Postgres, │ │ +│ │ Mobile) │ │ ┌────────┐ │ │ MySQL, │ │ +│ └──────────────┘ │ │ Auth │ │ │ Neon...) │ │ +│ │ ├────────┤ │ └──────────────┘ │ +│ ┌──────────────┐ │ │ Realtime│ │ │ +│ │ Serverless │──────▶│ ├────────┤ │ ┌──────────────┐ │ +│ │ Functions │ │ │ Storage │ │ │ S3 Storage │ │ +│ └──────────────┘ │ ├────────┤ │ │ (R2, B2, │ │ +│ │ │GraphQL │ │ │ MinIO...) │ │ +│ ┌──────────────┐ │ ├────────┤ │ └──────────────┘ │ +│ │ Webhooks │──────▶│ │ RLS │ │ │ +│ └──────────────┘ │ ├────────┤ │ ┌──────────────┐ │ +│ │ │ Vector │ │ │ External │ │ +│ ┌──────────────┐ │ ├────────┤ │ │ Services │ │ +│ │ Logger │──────▶│ │ Branch │ │ │ (AI APIs, │ │ +│ └──────────────┘ │ ├────────┤ │ │ OAuth...) │ │ +│ │ │ Logger │ │ └──────────────┘ │ +│ │ └────────┘ │ │ +│ └──────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────┘ ``` @@ -70,13 +76,17 @@ Betterbase provides a complete backend solution with enterprise-grade features: | **RLS (Row Level Security)** | Built-in policy engine for fine-grained access control | | **Serverless Functions** | Deploy custom API functions | | **Storage API** | S3-compatible object storage | +| **Image Transformations** | On-the-fly image resizing, cropping, and format conversion | | **Webhooks** | Event-driven architecture with signed payloads | | **Vector Search** | pgvector-powered similarity search with embeddings support | | **Branching/Preview Environments** | Create isolated development environments for each branch | | **Auto-REST** | Automatic CRUD route generation from Drizzle schema | +| **GraphQL** | GraphQL API with schema generation and subscriptions | | **Magic Link Auth** | Passwordless authentication via email magic links | | **MFA** | Multi-factor authentication support | | **Phone Auth** | Phone number verification via SMS/OTP | +| **Project Templates** | Base and Auth templates for quick project initialization | +| **Request Logging** | Built-in request logging with file transport | --- @@ -202,6 +212,42 @@ Your backend is now running at `http://localhost:3000`: --- +## Templates + +BetterBase provides project templates for quick project initialization: + +### Base Template + +The base template includes essential project structure: + +```bash +bb init my-project --template base +``` + +**Includes:** +- Basic Hono server setup +- Database schema with users table +- Authentication middleware +- Storage routes +- Health check endpoint + +### Auth Template + +The authentication template includes full BetterAuth integration: + +```bash +bb init my-project --template auth +``` + +**Includes:** +- Pre-configured BetterAuth setup +- Email/password authentication +- Social OAuth providers (configurable) +- Session management +- Auth middleware examples + +--- + ## Architecture Overview ### System Design @@ -248,6 +294,45 @@ Your backend is now running at `http://localhost:3000`: ### Package Architecture +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ TURBOREPO MONOREPO │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────────────────────────────────────────────────────────┐ │ +│ │ @betterbase/cli │ │ +│ │ CLI tool with 17 commands for development and deployment │ │ +│ │ init, dev, migrate, auth, auth add-provider, generate, │ │ +│ │ function, graphql, login, rls, rls test, storage, │ │ +│ │ webhook, branch │ │ +│ └──────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────────────┐ │ +│ │ @betterbase/client │ │ +│ │ TypeScript SDK for frontend integration │ │ +│ │ Auth, Query Builder, Realtime, Storage, Errors │ │ +│ └──────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────────────┐ │ +│ │ @betterbase/core │ │ +│ │ Core backend engine with all server-side functionality │ │ +│ │ Database, Auth, GraphQL, RLS, Storage, Webhooks, Functions, │ │ +│ │ Vector Search, Branching, Auto-REST, Logger, Realtime │ │ +│ └──────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────────────┐ │ +│ │ @betterbase/shared │ │ +│ │ Shared utilities, types, and constants across all packages │ │ +│ │ Types, Errors, Constants, Utils │ │ +│ └──────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────────────┐ │ +│ │ templates/ │ │ +│ │ Project templates for quick initialization │ │ +│ │ base, auth │ │ +│ └──────────────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ TURBOREPO MONOREPO │ @@ -365,7 +450,7 @@ export default defineConfig({ ## CLI Reference -The Betterbase CLI (`bb`) provides 12 commands for development and deployment: +The Betterbase CLI (`bb`) provides 17 commands for development and deployment: ### Core Commands @@ -415,23 +500,36 @@ bb migrate down # Reset database (warning: destructive) bb migrate reset + +# Preview migration changes +bb migrate preview + +# Run in production mode +bb migrate production ``` ### Authentication -#### `bb auth` +#### `bb auth setup` -Manage authentication configuration. +Setup and configure BetterAuth. ```bash # Setup authentication bb auth setup +``` + +#### `bb auth add-provider` -# Add provider +Add OAuth provider to your project. + +```bash +# Add OAuth provider bb auth add-provider github -# List providers -bb auth list-providers +# Available providers: google, github, discord, apple, microsoft, twitter, facebook +bb auth add-provider google +bb auth add-provider discord ``` ### Code Generation @@ -451,26 +549,6 @@ bb generate crud bb generate all ``` -### Serverless Functions - -#### `bb function` - -Manage serverless functions. - -```bash -# Create new function -bb function create my-function - -# Deploy function -bb function deploy my-function - -# List functions -bb function list - -# Invoke function locally -bb function invoke my-function -``` - ### GraphQL #### `bb graphql` @@ -478,51 +556,37 @@ bb function invoke my-function GraphQL schema management. ```bash -# Start GraphQL server -bb graphql start - -# Export schema -bb graphql schema export - -# Validate schema -bb graphql schema validate -``` - -### Authentication (User Management) - -#### `bb login` - -Manage user authentication. - -```bash -# Login user -bb login --email user@example.com +# Generate GraphQL schema from database +bb graphql generate -# Logout user -bb logout +# Open GraphQL Playground +bb graphql playground -# Get current session -bb login status +# Export schema as SDL +bb graphql export ``` -### Security +### RLS (Row Level Security) #### `bb rls` Manage Row Level Security policies. ```bash -# Add RLS policy -bb rls add --table posts --name users-own-posts --command SELECT --check "user_id = auth.uid()" +# Create new RLS policy +bb rls create --table posts --name users-own-posts --command SELECT -# List policies -bb rls list --table posts +# List all RLS policies +bb rls list -# Disable RLS +# Disable RLS for a table bb rls disable --table posts -# Enable RLS +# Enable RLS for a table bb rls enable --table posts + +# Test RLS policies +bb rls test --table posts ``` ### Storage @@ -532,15 +596,15 @@ bb rls enable --table posts Manage file storage. ```bash -# Setup storage -bb storage setup - -# Create bucket -bb storage create-bucket avatars +# Initialize storage +bb storage init # List buckets bb storage list +# List objects in bucket +bb storage buckets avatars + # Upload file bb storage upload avatars avatar.png ``` @@ -561,10 +625,38 @@ bb webhook list # Test webhook bb webhook test my-webhook -# Delete webhook -bb webhook delete my-webhook +# View webhook logs +bb webhook logs my-webhook +``` + +### Serverless Functions + +#### `bb function` + +Manage serverless functions. + +```bash +# Create new function +bb function create my-function + +# Run function in development mode +bb function dev my-function + +# Build function +bb function build my-function + +# Deploy function +bb function deploy my-function + +# List all functions +bb function list + +# View function logs +bb function logs my-function ``` +### Branching (Preview Environments) + #### `bb branch` Manage preview environments (branches) for isolated development. @@ -573,12 +665,12 @@ Manage preview environments (branches) for isolated development. # Create a new preview environment bb branch create my-feature -# Delete a preview environment -bb branch delete my-feature - # List all preview environments bb branch list +# Delete a preview environment +bb branch delete my-feature + # Check branch status bb branch status my-feature @@ -589,6 +681,23 @@ bb branch wake my-feature bb branch sleep my-feature ``` +### Authentication (User Management) + +#### `bb login` + +Manage user authentication. + +```bash +# Login user +bb login --email user@example.com + +# Logout user +bb logout + +# Get current session +bb login status +``` + --- ## Client SDK From 82e6ebf100d20ff15f6ce69206563c1d0c6c1acb Mon Sep 17 00:00:00 2001 From: weroperking <139503221+weroperking@users.noreply.github.com> Date: Sat, 21 Mar 2026 14:28:54 +0000 Subject: [PATCH 2/2] updates READEME.md with built with weroperking --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d0ab651..cdfdd9d 100644 --- a/README.md +++ b/README.md @@ -1448,7 +1448,7 @@ SOFTWARE.
-**Built with ❤️ using Bun** +**Built with ❤️ using Weroperking** [Website](https://betterbase.io) • [Documentation](https://docs.betterbase.io) • [Discord](https://discord.gg/betterbase) • [Twitter](https://twitter.com/betterbase)