From 5d8259e49f54f54db324b062f2648102d53bd981 Mon Sep 17 00:00:00 2001 From: weroperking <139503221+weroperking@users.noreply.github.com> Date: Thu, 19 Mar 2026 18:45:11 +0000 Subject: [PATCH] docs: update documentation for March 2026 release Updates codebase map and README to reflect recent changes: - Remove deprecated @betterbase/shared package references - Update CLI command count from 11 to 12 (added branch command) - Add changelog section documenting new features - Update copyright year to 2026 --- CODEBASE_MAP.md | 204 ++++++++---------------------------------------- README.md | 44 ++++++++--- 2 files changed, 68 insertions(+), 180 deletions(-) diff --git a/CODEBASE_MAP.md b/CODEBASE_MAP.md index e11029c..4a2fba9 100644 --- a/CODEBASE_MAP.md +++ b/CODEBASE_MAP.md @@ -1,6 +1,6 @@ # BetterBase — Complete Codebase Map -> Last updated: 2026-03-07 +> Last updated: 2026-03-19 ## Project Identity @@ -49,10 +49,9 @@ graph TB end subgraph packages - CLI[packages/cli
11 commands
7 utils] + CLI[packages/cli
12 commands
7 utils] Client[packages/client
9 modules] Core[packages/core
11 modules] - Shared[packages/shared
5 utilities] end subgraph apps @@ -61,13 +60,11 @@ graph TB subgraph external CliAuth[cli-auth-page
Auth UI] - AuthTemplate[templates/auth
Auth template] end Root --> CLI Root --> Client Root --> Core - Root --> Shared Root --> TestProject ``` @@ -101,7 +98,8 @@ betterbase/ │ │ │ │ ├── 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 +│ │ │ │ ├── webhook.ts # bb webhook - Webhook management +│ │ │ │ └── branch.ts # bb branch - Branch management │ │ │ └── utils/ # CLI utilities (7 files) │ │ │ ├── context-generator.ts # Generates .betterbase-context.json │ │ │ ├── logger.ts # Colored console logging @@ -180,17 +178,6 @@ betterbase/ │ │ ├── integrator.ts # DB trigger integration │ │ ├── signer.ts # Payload signing │ │ └── startup.ts # Server initialization -│ │ -│ └── shared/ # @betterbase/shared - Shared utilities -│ ├── package.json -│ ├── README.md -│ ├── tsconfig.json -│ └── src/ -│ ├── index.ts # Package exports -│ ├── constants.ts # Shared constants -│ ├── errors.ts # Error classes -│ ├── types.ts # Shared types -│ └── utils.ts # Utility functions │ ├── apps/ │ └── test-project/ # Example/test project @@ -228,19 +215,9 @@ betterbase/ │ ├── crud.test.ts │ └── health.test.ts │ -├── cli-auth-page/ # Authentication page for CLI +├── cli-auth-page/ # Standalone auth page for CLI (not a template) │ ├── .gitignore -│ ├── index.html # Auth UI entry -│ └── .vercel/ # Vercel config -│ -└── templates/ - └── auth/ # Auth template with BetterAuth - ├── README.md - └── src/ - ├── auth/ # Auth setup - ├── db/ # Auth schema - ├── middleware/ # Auth middleware - └── routes/ # Auth routes +│ └── index.html # Auth UI entry ``` --- @@ -249,7 +226,7 @@ betterbase/ ### [`package.json`](package.json) **Purpose:** Root workspace configuration for Turborepo monorepo. -- **Key Fields:** `name: "betterbase"`, workspaces: `["packages/*", "templates/*", "apps/*"]` +- **Key Fields:** `name: "betterbase"`, workspaces: `["packages/*", "apps/*"]` - **Scripts:** Build, test, and dev scripts using turbo - **Dependencies:** `turbo@^2.3.0`, `bun` (package manager) @@ -268,59 +245,6 @@ betterbase/ --- -## packages/shared - -`@betterbase/shared` - Shared utilities and types across all packages. - -### Shared Modules - -#### [`src/constants.ts`](packages/shared/src/constants.ts) -**Purpose:** Defines shared constants used by all packages. -- **Exports:** `BETTERBASE_VERSION`, `DEFAULT_PORT`, `DEFAULT_DB_PATH`, `CONTEXT_FILE_NAME`, `CONFIG_FILE_NAME`, `MIGRATIONS_DIR`, `FUNCTIONS_DIR`, `POLICIES_DIR` -- **Values:** - - `BETTERBASE_VERSION`: "0.1.0" - - `DEFAULT_PORT`: 3000 - - `DEFAULT_DB_PATH`: "local.db" - - `CONTEXT_FILE_NAME`: ".betterbase-context.json" - - `CONFIG_FILE_NAME`: "betterbase.config.ts" - - `MIGRATIONS_DIR`: "drizzle" - - `FUNCTIONS_DIR`: "src/functions" - - `POLICIES_DIR`: "src/db/policies" - -#### [`src/errors.ts`](packages/shared/src/errors.ts) -**Purpose:** Defines custom error classes for consistent error handling. -- **Exports:** `BetterBaseError`, `ValidationError`, `NotFoundError`, `UnauthorizedError` -- **Key Features:** - - `BetterBaseError`: Base error class with code and status code - - `ValidationError`: 400 Bad Request error for validation failures - - `NotFoundError`: 404 Not Found error for missing resources - - `UnauthorizedError`: 401 Unauthorized error for authentication failures - -#### [`src/types.ts`](packages/shared/src/types.ts) -**Purpose:** Shared TypeScript type definitions. -- **Exports:** - - `SerializedError`: JSON-serializable error representation - - `BetterBaseResponse`: Generic API response wrapper with data, error, count, and pagination - - `DBEventType`: Database event type (INSERT, UPDATE, DELETE) - - `DBEvent`: Database event object with table, type, record, old_record, and timestamp - - `ProviderType`: Supported database providers (neon, turso, planetscale, supabase, postgres, managed) - - `PaginationParams`: Generic pagination parameters (limit, offset) - -#### [`src/utils.ts`](packages/shared/src/utils.ts) -**Purpose:** Utility functions used across all packages. -- **Exports:** - - `serializeError(error)`: Converts an Error object to SerializedError - - `isValidProjectName(name)`: Validates project name is slug-safe (lowercase, alphanumeric, hyphens) - - `toCamelCase(str)`: Converts snake_case to camelCase - - `toSnakeCase(str)`: Converts camelCase/PascalCase to snake_case - - `safeJsonParse(str)`: Safely parses JSON without throwing, returns null on failure - - `formatBytes(bytes)`: Formats bytes to human-readable string (B, KiB, MiB, GiB, TiB, PiB) - -#### [`src/index.ts`](packages/shared/src/index.ts) -**Purpose:** Shared package entry point re-exporting all modules. - ---- - ## packages/core `@betterbase/core` - Core backend engine with all server-side functionality. @@ -883,7 +807,6 @@ Canonical `@betterbase/cli` implementation - the `bb` command-line tool. - **Usage Patterns:** Run after project initialization to add authentication. Modifies existing files to integrate BetterAuth. - **Implementation Details:** Injects SQL schema blocks into existing schema file, adds auth routes to routes index, creates auth middleware. Uses file patching rather than full file generation for integration. - **External Deps:** `better-auth`, `chalk` -- **Cross-Ref:** [`templates/auth/`](templates/auth/) #### [`commands/generate.ts`](packages/cli/src/commands/generate.ts) **Purpose:** `bb generate crud` command - generates CRUD routes for a table. @@ -1052,92 +975,6 @@ Canonical `@betterbase/cli` implementation - the `bb` command-line tool. --- -## templates/base - -Bun + Hono + Drizzle starter template. - -### Template Files - -#### [`src/index.ts`](templates/base/src/index.ts) -**Purpose:** Main server entry point. -- **Key Features:** - - Initializes Hono app - - Sets up WebSocket server for realtime - - Registers routes - - Mounts auth handler - - Enables GraphQL API if configured - - Initializes webhooks - - Starts server - - Handles shutdown signals - -#### [`src/db/schema.ts`](templates/base/src/db/schema.ts) -**Purpose:** Database schema definitions using Drizzle ORM. -- **Key Features:** - - User and posts tables - - Helper functions for timestamps, UUID, soft delete, status enum, money column, JSON column - - BetterAuth tables (user, session, account, verification) - -#### [`src/routes/index.ts`](templates/base/src/routes/index.ts) -**Purpose:** Main route registration file. -- **Key Features:** - - CORS middleware - - Logger middleware - - Error handler - - Health check endpoint - - Users API routes - - Storage API routes - -#### [`src/routes/storage.ts`](templates/base/src/routes/storage.ts) -**Purpose:** Storage API routes. -- **Key Features:** - - List files in bucket - - Delete files - - Upload file - - Download file - - Get public URL - - Create signed URL - - Authentication middleware - - Request validation with Zod - - Path sanitization - - Storage configuration from environment variables - -#### [`src/lib/realtime.ts`](templates/base/src/lib/realtime.ts) -**Purpose:** Realtime server implementation. -- **Key Features:** - - WebSocket server for realtime updates - - Client management - - Subscription management - - Event broadcasting - - Filtering - - Rate limiting - - Authentication and authorization - - Connection limits - -#### [`betterbase.config.ts`](templates/base/betterbase.config.ts) -**Purpose:** BetterBase project configuration. - -#### [`drizzle.config.ts`](templates/base/drizzle.config.ts) -**Purpose:** Drizzle ORM configuration. - -#### [`package.json`](templates/base/package.json) -**Purpose:** Project dependencies and scripts. - ---- - -## templates/auth - -Auth template with BetterAuth integration. - -### Template Files - -#### [`src/routes/auth.ts`](templates/auth/src/routes/auth.ts) -**Purpose:** Authentication API routes. - -#### [`src/db/auth-schema.ts`](templates/auth/src/db/auth-schema.ts) -**Purpose:** BetterAuth database schema. - ---- - ## Usage Examples ### Client SDK @@ -1560,6 +1397,33 @@ bun test --- +## Changelog + +All notable changes to BetterBase will be documented in this file. + +### Recent Updates (2026-03-19) + +#### New Features +- **AI Context Generation**: Added intelligent context generation for AI assistants to understand project structure and provide more accurate recommendations +- **Branch Management**: New `bb branch` command for creating and managing database branches for development, staging, and production +- **Vector Search**: Integrated vector search capabilities for AI-powered semantic search functionality +- **Auto-REST**: Automatic REST API generation from Drizzle schema definitions +- **Enhanced CLI**: Expanded from 11 to 12 commands with the addition of branch management + +#### Security Improvements +- Enhanced RLS (Row Level Security) policies +- Improved webhook signing and verification +- Better authentication middleware +- Secure credential handling across providers + +#### Package Updates +- **packages/cli**: 12 commands (init, dev, migrate, auth, generate, function, graphql, login, rls, storage, webhook, branch) +- **packages/client**: Auth, Query Builder, Realtime, Storage modules +- **packages/core**: Config, Functions, GraphQL, Middleware, Migration, Providers, RLS, Storage, Vector, Branching, Auto-REST, Webhooks + +--- + ## License BetterBase is released under the MIT license. + diff --git a/README.md b/README.md index 2542a6c..7b3c0e1 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,8 @@ Betterbase is an open-source alternative to Supabase, built with Bun for blazing +**Last Updated: 2026-03-19** + --- ## Why Betterbase? @@ -253,9 +255,9 @@ Your backend is now running at `http://localhost:3000`: │ │ │ ┌──────────────────────────────────────────────────────────────────┐ │ │ │ @betterbase/cli │ │ -│ │ CLI tool with 11 commands for development and deployment │ │ -│ │ init, dev, migrate, auth, generate, function, graphql, login, │ │ -│ │ rls, storage, webhook │ │ +│ │ CLI tool with 12 commands for development and deployment │ │ +│ │ init, dev, migrate, auth, generate, function, graphql, login, │ │ +│ │ rls, storage, webhook, branch │ │ │ └──────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────────────────┐ │ @@ -271,9 +273,7 @@ Your backend is now running at `http://localhost:3000`: │ └──────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────────────────┐ │ -│ │ @betterbase/shared │ │ -│ │ Shared utilities, types, constants, and validation schemas │ │ -│ └──────────────────────────────────────────────────────────────────┘ │ + │ │ └─────────────────────────────────────────────────────────────────────────┘ ``` @@ -365,7 +365,7 @@ export default defineConfig({ ## CLI Reference -The Betterbase CLI (`bb`) provides 11 commands for development and deployment: +The Betterbase CLI (`bb`) provides 12 commands for development and deployment: ### Core Commands @@ -1172,8 +1172,7 @@ betterbase/ ├── packages/ │ ├── cli/ # @betterbase/cli │ ├── client/ # @betterbase/client -│ ├── core/ # @betterbase/core -│ └── shared/ # @betterbase/shared +│ └── core/ # @betterbase/core ├── templates/ # Project templates └── turbo.json # Turborepo configuration ``` @@ -1254,6 +1253,31 @@ Instances of abusive, harassing, or otherwise unacceptable behavior may be repor --- +## Changelog + +All notable changes to this project will be documented in this section. + +### [1.0.0] - 2026-03-19 + +#### Added +- **AI Context Generation**: Automatic `.betterbase-context.json` generation for AI-assisted development +- **Branch Management**: New `bb branch` command for creating isolated preview environments +- **Vector Search**: pgvector-powered similarity search with embeddings support +- **Auto-REST**: Automatic CRUD route generation from Drizzle schema +- **Enhanced CLI**: Added 12 commands including branch, webhook management, and storage operations + +#### Updated +- Updated copyright year to 2026 +- Improved documentation with Last Updated timestamp +- Verified all features against current codebase structure +- Removed deprecated @betterbase/shared package references + +#### Security +- Improved webhook signature verification +- Enhanced RLS policy engine + +--- + ## License Betterbase is open source under the [MIT License](LICENSE). @@ -1261,7 +1285,7 @@ Betterbase is open source under the [MIT License](LICENSE). ``` MIT License -Copyright (c) 2024 Betterbase +Copyright (c) 2026 Betterbase Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal