@venizia/ignis-docs 0.0.8 → 0.2.0

package/content/references/base/filter-system/logical-operators.md

@@ -105,9 +105,38 @@ Combine AND and OR for complex logic:
 ```
 
 
+## Empty Groups
+
+An empty `and`/`or` array is not a no-op -- each empty case resolves to what the operator means with zero conditions:
+
+```typescript
+// Empty AND is vacuously TRUE - dropped from the query entirely
+{ where: { and: [] } }
+// SQL: (no condition added)
+
+// Empty OR is vacuously FALSE - compiles to a condition that matches nothing
+{ where: { or: [] } }
+// SQL: WHERE false
+```
+
+This matters when the array is built from a caller-supplied list, e.g. `{ or: permittedOrgIds.map(id => ({ orgId: id })) }`: an empty permission list must return zero rows, not every row, so `or: []` matching nothing is the safe default.
+
+
 ## NOT Logic
 
-Ignis does not have a standalone `not` logical operator. Instead, use negation operators for NOT conditions:
+IGNIS has a general-purpose `not` operator that negates whatever condition it wraps - a bare value negates `eq`, and a nested operator object negates that operator. It is supported on the PostgreSQL connector:
+
+```typescript
+// NOT equal (bare value negates eq)
+{ where: { status: { not: 'archived' } } }
+// SQL: WHERE NOT ("status" = 'archived')
+
+// Negate a nested operator condition
+{ where: { views: { not: { gt: 100 } } } }
+// SQL: WHERE NOT ("views" > 100)
+```
+
+The dedicated negation operators remain available and are often clearer for a single condition:
 
 ```typescript
 // NOT equal
@@ -131,6 +160,9 @@ Ignis does not have a standalone `not` logical operator. Instead, use negation o
 { where: { score: { notBetween: [40, 60] } } }
 ```
 
+> [!NOTE]
+> `ne`/`neq`/`nin` follow SQL three-valued logic - a row whose field is `NULL` never matches them (`NULL <> value` is UNKNOWN, not TRUE). Use `exists`/`notExists` or an explicit `{ field: null }` branch when you need NULL rows in the result.
+
 
 ## Complex Example
 

package/content/references/base/filter-system/null-operators.md

@@ -71,6 +71,30 @@ The simplest way to check for NULL:
 ```
 
 
+## exists / notExists - Presence Check
+
+`exists` and `notExists` are presence operators - they take a boolean rather than a value, and read more naturally than `is`/`isn` against `null`. They work on the PostgreSQL connector, and `exists` also works over JSON paths there.
+
+```typescript
+// Field is present (IS NOT NULL)
+{ where: { deletedAt: { exists: false } } }  // no deletedAt -> IS NULL
+{ where: { verifiedAt: { exists: true } } }  // has verifiedAt -> IS NOT NULL
+
+// notExists is the inverse
+{ where: { verifiedAt: { notExists: true } } }  // IS NULL
+
+// exists over a JSON path (PostgreSQL)
+{ where: { 'metadata.score': { exists: true } } }
+```
+
+| Syntax | SQL | Description |
+|--------|-----|-------------|
+| `{ field: { exists: true } }` | `IS NOT NULL` | Field is present |
+| `{ field: { exists: false } }` | `IS NULL` | Field is missing/null |
+| `{ field: { notExists: true } }` | `IS NULL` | Inverse of exists |
+| `{ field: { notExists: false } }` | `IS NOT NULL` | Inverse of exists |
+
+
 ## Null Check Summary
 
 | Syntax | SQL | Description |
@@ -78,11 +102,16 @@ The simplest way to check for NULL:
 | `{ field: null }` | `IS NULL` | Direct null check |
 | `{ field: { eq: null } }` | `IS NULL` | Explicit null equality |
 | `{ field: { is: null } }` | `IS NULL` | IS operator with null |
+| `{ field: { exists: false } }` | `IS NULL` | Presence check (false = missing) |
 | `{ field: { ne: null } }` | `IS NOT NULL` | Not-equal null check |
 | `{ field: { neq: null } }` | `IS NOT NULL` | Alias for ne with null |
 | `{ field: { isn: null } }` | `IS NOT NULL` | IS NOT operator with null |
+| `{ field: { exists: true } }` | `IS NOT NULL` | Presence check (true = present) |
+
+All the IS NULL / IS NOT NULL syntaxes above are equivalent -- use whichever reads best in context.
 
-All six syntaxes for IS NULL / IS NOT NULL are equivalent -- use whichever reads best in context.
+> [!NOTE]
+> `ne`/`neq` follow SQL three-valued logic: a row whose field is `NULL` never matches `{ field: { neq: value } }`. This is intentional (`NULL <> value` is UNKNOWN, not TRUE). Reach for `exists`/`notExists` or an explicit `{ field: null }` branch when you want NULL rows included.
 
 
 ## Common Patterns

package/content/references/base/filter-system/quick-reference.md

@@ -21,6 +21,9 @@ Complete single-page reference for all IGNIS filter operators. For detailed expl
 | `lt` | `<` | `{ price: { lt: 100 } }` | Less than |
 | `lte` | `<=` | `{ price: { lte: 100 } }` | Less than or equal |
 
+> [!NOTE]
+> `ne`/`neq` follow SQL three-valued logic: a row whose field is `NULL` **never** matches `{ field: { neq: value } }` (`NULL <> value` evaluates to UNKNOWN, not TRUE). To include NULL rows, add `{ or: [{ field: { neq: value } }, { field: null }] }`.
+
 **See:** [Comparison Operators Guide](./comparison-operators.md)
 
 
@@ -88,12 +91,27 @@ Complete single-page reference for all IGNIS filter operators. For detailed expl
 **See:** [Null Operators Guide](./null-operators.md)
 
 
+## Presence & Negation Operators
+
+| Operator | SQL | TypeScript Example | Description |
+|----------|-----|-------------------|-------------|
+| `exists` | `IS NOT NULL` / `IS NULL` | `{ deletedAt: { exists: false } }` | `exists: true` -> IS NOT NULL, `exists: false` -> IS NULL |
+| `notExists` | `IS NULL` / `IS NOT NULL` | `{ verifiedAt: { notExists: true } }` | Inverse of `exists` (`notExists: true` -> IS NULL) |
+| `not` | `NOT (...)` | `{ status: { not: 'archived' } }` / `{ views: { not: { gt: 100 } } }` | Negates the nested condition; a bare value negates `eq` |
+
+`exists`/`notExists`/`not` are supported on the PostgreSQL connector. `not` recurses: `{ not: { gt: 100 } }` becomes `NOT (col > 100)`, and `{ not: 5 }` becomes `NOT (col = 5)`. `exists` also works over JSON paths on PostgreSQL (`{ 'metadata.score': { exists: true } }`).
+
+**See:** [Null Operators Guide](./null-operators.md)
+
+
 ## Logical Operators
 
 | Operator | SQL | TypeScript Example | Description |
 |----------|-----|-------------------|-------------|
 | `and` | `AND` | `{ and: [{ age: { gt: 18 } }, { status: 'active' }] }` | All conditions must be true |
 | `or` | `OR` | `{ or: [{ role: 'admin' }, { role: 'moderator' }] }` | At least one condition must be true |
+| `and: []` | (dropped) | `{ and: [] }` | Vacuously true - no condition added to the query |
+| `or: []` | `false` | `{ or: [] }` | Vacuously false - matches no rows |
 
 **Implicit AND:**
 ```typescript
@@ -106,7 +124,7 @@ Complete single-page reference for all IGNIS filter operators. For detailed expl
 // WHERE status = 'active' AND age >= 18 AND role = 'user'
 ```
 
-**NOT logic** is expressed via negation operators (`ne`, `neq`, `nin`, `nlike`, `nilike`, `notBetween`, `isn`).
+**NOT logic** is expressed via the general-purpose `not` operator (`{ field: { not: <value | operatorObject> } }`) or the dedicated negation operators (`ne`, `neq`, `nin`, `nlike`, `nilike`, `notBetween`, `isn`).
 
 **See:** [Logical Operators Guide](./logical-operators.md)
 
@@ -170,6 +188,7 @@ All comparison operators work with JSON path queries:
 - `between`, `notBetween`
 - `regexp`, `iregexp`
 - `is`, `isn`
+- `exists`, `notExists`, `not`
 
 Numeric operators (`gt`, `gte`, `lt`, `lte`, `between`, `notBetween`) use safe numeric casting to handle mixed JSON value types.
 
@@ -181,7 +200,7 @@ Numeric operators (`gt`, `gte`, `lt`, `lte`, `between`, `notBetween`) use safe n
 ### Select Specific Fields
 
 ```typescript
-const users = await userRepo.find({
+const users = await userRepository.find({
   filter: {
     where: { isActive: true },
     fields: ['id', 'name', 'email'], // Only return these fields
@@ -242,11 +261,11 @@ export class User extends BaseEntity<typeof User.schema> {
 }
 
 // All queries automatically include the default filter
-await userRepo.find({ filter: {} });
+await userRepository.find({ filter: {} });
 // WHERE isDeleted = false LIMIT 100
 
 // Skip default filter for admin operations
-await userRepo.find({
+await userRepository.find({
   filter: {},
   options: { shouldSkipDefaultFilter: true },
 });

package/content/references/base/filter-system/tips.md

@@ -65,7 +65,7 @@ const chunkSize = 500;
 const results = [];
 for (let i = 0; i < allIds.length; i += chunkSize) {
   const chunk = allIds.slice(i, i + chunkSize);
-  const chunkResults = await repo.find({
+  const chunkResults = await repository.find({
     filter: { where: { id: { in: chunk } } }
   });
   results.push(...chunkResults);
@@ -89,7 +89,7 @@ for (let i = 0; i < allIds.length; i += chunkSize) {
 
 ```typescript
 // Enable logging to see generated SQL
-const result = await repo.find({
+const result = await repository.find({
   filter: complexFilter,
   options: {
     log: { use: true, level: 'debug' },
@@ -97,7 +97,7 @@ const result = await repo.find({
 });
 
 // Or use buildQuery to inspect without executing
-const queryOptions = repo.buildQuery({ filter: complexFilter });
+const queryOptions = repository.buildQuery({ filter: complexFilter });
 console.log('Generated query options:', queryOptions);
 ```
 
@@ -124,7 +124,7 @@ console.log('Generated query options:', queryOptions);
 ## Tip 8: Combining Multiple Array Conditions
 
 ```typescript
-await productRepo.find({
+await productRepository.find({
   filter: {
     where: {
       // Must have ALL these categories
@@ -181,7 +181,7 @@ const createPaginationFilter = (page: number, size: number = 20) => ({
 });
 
 // Usage
-const products = await productRepo.find({
+const products = await productRepository.find({
   filter: {
     where: {
       ...createActiveFilter(),

package/content/references/base/filter-system/use-cases.md

@@ -12,7 +12,7 @@ Real-world examples of filter usage with corresponding SQL.
 ## E-commerce Product Search
 
 ```typescript
-const products = await productRepo.find({
+const products = await productRepository.find({
   filter: {
     where: {
       category: 'electronics',
@@ -44,7 +44,7 @@ const products = await productRepo.find({
 const thirtyDaysAgo = new Date();
 thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);
 
-const recentUsers = await userRepo.find({
+const recentUsers = await userRepository.find({
   filter: {
     where: {
       createdAt: { gte: thirtyDaysAgo },
@@ -71,7 +71,7 @@ const recentUsers = await userRepo.find({
 ## Task Management: Priority Tags
 
 ```typescript
-const priorityTasks = await taskRepo.find({
+const priorityTasks = await taskRepository.find({
   filter: {
     where: {
       status: { nin: ['completed', 'cancelled'] },
@@ -100,7 +100,7 @@ const priorityTasks = await taskRepo.find({
 
 ```typescript
 // Find active records (soft delete pattern)
-const activeRecords = await repo.find({
+const activeRecords = await repository.find({
   filter: {
     where: { deletedAt: { is: null } },
   }
@@ -112,7 +112,7 @@ const activeRecords = await repo.find({
 
 ```typescript
 // Find ONLY soft-deleted records
-const deletedRecords = await repo.find({
+const deletedRecords = await repository.find({
   filter: {
     where: { deletedAt: { isn: null } },
   }
@@ -142,7 +142,7 @@ const getAuthorizedFilter = (user: User): TWhere<TDocumentSchema> => {
   };
 };
 
-const documents = await documentRepo.find({
+const documents = await documentRepository.find({
   filter: {
     where: getAuthorizedFilter(currentUser),
     order: ['updatedAt DESC'],
@@ -206,7 +206,7 @@ const searchProducts = async (query: string, filters: {
     where.categories = { contains: filters.categories };
   }
 
-  return productRepo.find({
+  return productRepository.find({
     filter: {
       where,
       order: ['rating DESC', 'createdAt DESC'],
@@ -281,7 +281,7 @@ const massiveFilter: TFilter<TProductSchema> = {
   ],
 };
 
-const products = await productRepo.find({ filter: massiveFilter });
+const products = await productRepository.find({ filter: massiveFilter });
 
 // SQL:
 // SELECT "id", "name", "price", "rating", "tags", "metadata"
@@ -334,7 +334,7 @@ const products = await productRepo.find({ filter: massiveFilter });
 const startOfWeek = new Date('2024-12-29');
 const endOfWeek = new Date('2025-01-04');
 
-const weekEvents = await eventRepo.find({
+const weekEvents = await eventRepository.find({
   filter: {
     where: {
       eventDate: { between: [startOfWeek, endOfWeek] }
@@ -355,7 +355,7 @@ const weekEvents = await eventRepo.find({
 const sevenDaysAgo = new Date();
 sevenDaysAgo.setDate(sevenDaysAgo.getDate() - 7);
 
-const recentOrders = await orderRepo.find({
+const recentOrders = await orderRepository.find({
   filter: {
     where: {
       createdAt: { gte: sevenDaysAgo },
@@ -382,7 +382,7 @@ const recentOrders = await orderRepo.find({
 
 ```typescript
 const getTenantProducts = async (tenantId: string, filter: TFilter<TProductSchema>) => {
-  return productRepo.find({
+  return productRepository.find({
     filter: {
       ...filter,
       where: {
@@ -415,7 +415,7 @@ await getTenantProducts('tenant-abc', {
 ## Inventory Low Stock Alert
 
 ```typescript
-const lowStockProducts = await productRepo.find({
+const lowStockProducts = await productRepository.find({
   filter: {
     where: {
       status: 'active',

package/content/references/base/grpc-controllers.md

@@ -6,9 +6,9 @@ difficulty: intermediate
 
 # Deep Dive: gRPC Controllers
 
-Technical reference for gRPC controller classes -- the foundation for building gRPC services in Ignis, powered by [ConnectRPC](https://connectrpc.com/).
+Technical reference for gRPC controller classes -- the foundation for building gRPC services in IGNIS, powered by [ConnectRPC](https://connectrpc.com/).
 
-Ignis gRPC controllers follow the same patterns as REST controllers (decorator-based routing, `binding()` method, DI integration) while bridging to ConnectRPC's universal handler system. REST and gRPC controllers coexist in the same application, sharing the same DI container, middleware pipeline, and lifecycle.
+IGNIS gRPC controllers follow the same patterns as REST controllers (decorator-based routing, `binding()` method, DI integration) while bridging to ConnectRPC's universal handler system. REST and gRPC controllers coexist in the same application, sharing the same DI container, middleware pipeline, and lifecycle.
 
 **Files:**
 - `packages/core/src/base/controllers/grpc/abstract.ts`
@@ -25,7 +25,7 @@ Ignis gRPC controllers follow the same patterns as REST controllers (decorator-b
 |------|-------------|
 | **AbstractGrpcController** | Abstract base class with RPC registration, ConnectRPC adapter mounting, idempotent `configure()` |
 | **BaseGrpcController** | Recommended concrete base class with `bindRoute()` and `defineRoute()` implementations |
-| **GrpcRequestAdapter** | Internal bridge from Ignis handlers to ConnectRPC universal handlers via `AsyncLocalStorage` |
+| **GrpcRequestAdapter** | Internal bridge from IGNIS handlers to ConnectRPC universal handlers via `AsyncLocalStorage` |
 | **GrpcComponent** | Auto-discovers gRPC controllers and mounts them on the application router |
 | **@controller** | Class decorator with `transport: ControllerTransports.GRPC` and `service` field |
 | **@unary** | Method decorator for unary RPCs |
@@ -57,7 +57,7 @@ bun add @connectrpc/connect-web
 ```
 
 > [!NOTE]
-> These are **optional** peer dependencies. They are only loaded at runtime when a gRPC controller is configured, via `createRequire` from the application's `node_modules`. If the deps are missing, `GrpcRequestAdapter.build()` throws a clear error at startup via `validateModule()`.
+> `@connectrpc/connect` is an **optional** peer dependency of `@venizia/ignis` - it is only loaded at runtime when a gRPC controller is configured, via `createRequire` from the application's `node_modules`. If it is missing, `GrpcRequestAdapter.build()` throws a clear error at startup via `validateModule()`. `@bufbuild/protobuf` is required by your generated protobuf code (e.g. `create()`), not by the framework itself.
 
 ### Protobuf Code Generation
 
@@ -335,7 +335,7 @@ type TRpcHandler<
 ```
 
 > [!NOTE]
-> When using decorator-based RPCs, the handler method signature is `(opts: { request: RequestType }) => Promise<ResponseType>`. The `context` parameter is injected internally by the adapter and is not passed to the decorator-based handler method directly. The full `TRpcHandler` signature (with `context`) applies when using `defineRoute()` or `bindRoute()`.
+> The adapter always calls handlers with `{ request, context }` - decorator-based handlers included. If your handler does not need the Hono context, declare only `(opts: { request: RequestType }) => Promise<ResponseType>` and ignore the `context` property.
 
 ### `IGrpcControllerOptions`
 
@@ -411,11 +411,11 @@ interface IConnectAdapterResult<
 
 ## `GrpcRequestAdapter`
 
-Internal bridge between Ignis gRPC controllers and ConnectRPC's universal handler system. You do not interact with this class directly -- it is created automatically during `configure()`.
+Internal bridge between IGNIS gRPC controllers and ConnectRPC's universal handler system. You do not interact with this class directly -- it is created automatically during `configure()`.
 
 ### Architecture
 
-The adapter solves a key challenge: ConnectRPC handlers have their own `(request, context) => response` signature, but Ignis controllers need access to the Hono `Context` for middleware, auth, and request-scoped state. The adapter uses `AsyncLocalStorage` to provide request-scoped context isolation, ensuring concurrent requests never share state.
+The adapter solves a key challenge: ConnectRPC handlers have their own `(request, context) => response` signature, but IGNIS controllers need access to the Hono `Context` for middleware, auth, and request-scoped state. The adapter uses `AsyncLocalStorage` to provide request-scoped context isolation, ensuring concurrent requests never share state.
 
 ```
 Hono Request
@@ -423,7 +423,7 @@ Hono Request
     -> AsyncLocalStorage.run(honoContext, ...)
       -> Pre-built auth middlewares (authenticate -> authorize)
         -> ConnectRPC universal handler
-          -> Ignis TRpcHandler (reads context from AsyncLocalStorage)
+          -> IGNIS TRpcHandler (reads context from AsyncLocalStorage)
             -> Response
 ```
 
@@ -449,7 +449,7 @@ The optional `interceptors` array is passed to ConnectRPC's `createConnectRouter
 
 ### Internal Flow
 
-1. **`buildConnectHandlers()`** -- Wraps each Ignis `TRpcHandler` into ConnectRPC's `(request, context) => response` signature. The wrapper reads the Hono context from `AsyncLocalStorage`, runs pre-built auth middlewares (built by `AbstractGrpcController.buildRpcMiddlewares()`), then passes `{ request, context }` to the Ignis handler.
+1. **`buildConnectHandlers()`** -- Wraps each IGNIS `TRpcHandler` into ConnectRPC's `(request, context) => response` signature. The wrapper reads the Hono context from `AsyncLocalStorage`, runs pre-built auth middlewares (built by `AbstractGrpcController.buildRpcMiddlewares()`), then passes `{ request, context }` to the IGNIS handler.
 
 2. **`registerService()`** -- Bridges the opaque `ServiceType` from `@controller` metadata to ConnectRPC's `router.service()` call, registering all handlers for the service.
 
@@ -839,7 +839,7 @@ import { GreeterService, SayHelloRequestSchema } from './controllers/greeter/def
 const transport = createConnectTransport({ baseUrl: 'http://localhost:3000/grpc' });
 const client = createClient(GreeterService, transport);
 
-const response = await client.sayHello(create(SayHelloRequestSchema, { name: 'Ignis' }));
+const response = await client.sayHello(create(SayHelloRequestSchema, { name: 'IGNIS' }));
 console.log(response.message);
 ```
 
@@ -928,7 +928,7 @@ Per-RPC authentication and authorization are configured via the `authenticate` a
     name: 'sayHello',
     authenticate: {
       strategies: ['jwt'],
-      mode: 'required',
+      mode: 'any',
     },
   },
 })
@@ -941,7 +941,7 @@ async sayHello(opts: { request: SayHelloRequest }): Promise<SayHelloResponse> {
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
 | `strategies` | `TAuthStrategy[]` | `[]` | Authentication strategies to apply (e.g., `['jwt']`, `['basic']`) |
-| `mode` | `TAuthMode` | `'any'` | `'required'` \| `'optional'` \| `'any'` \| `'all'` (defaults to `AuthenticationModes.ANY`) |
+| `mode` | `TAuthMode` | `'any'` | `'any'` \| `'all'` (defaults to `AuthenticationModes.ANY`) |
 
 ### Per-RPC Authorization
 
@@ -949,7 +949,7 @@ async sayHello(opts: { request: SayHelloRequest }): Promise<SayHelloResponse> {
 @unary({
   configs: {
     name: 'deleteUser',
-    authenticate: { strategies: ['jwt'], mode: 'required' },
+    authenticate: { strategies: ['jwt'], mode: 'any' },
     authorize: { action: 'delete', resource: 'user' },
   },
 })

package/content/references/base/index.md

@@ -1,6 +1,9 @@
 # Base Abstractions
 
-Core classes that power every Ignis application - from the Application entry point to Repositories for data access.
+Core classes that power every IGNIS application - from the Application entry point to Repositories for data access.
+
+> [!IMPORTANT] Base vs. Connectors
+> The persistence layer (`BaseDataSource`/`BaseEntity`/CRUD repositories) is split into an engine-neutral root (`src/base`) and per-engine connectors (`src/connectors/{postgres,typesense}`). `BaseDataSource` and `BaseEntity` below refer to the **PostgreSQL connector**'s canonical `BasePostgresDataSource`/`BasePostgresEntity` (re-exported under these compatibility names) - see [Connectors](./connectors) for the full picture, and [Search & Typesense](/guides/core-concepts/persistent/search-typesense) for the other engine.
 
 ## Quick Reference
 
@@ -12,10 +15,10 @@ Core classes that power every Ignis application - from the Application entry poi
 | `BaseService` | Business logic layer | - |
 | `BaseProvider` | Factory pattern for runtime instantiation | `BaseHelper` |
 | `BaseComponent` | Pluggable feature modules | - |
-| `BaseDataSource` | Database connections | - |
-| `BaseEntity` | Model definitions | - |
-| `DefaultCRUDRepository` | Full CRUD operations | `PersistableRepository` |
-| `ReadableRepository` | Read-only operations | `AbstractRepository` |
+| `BaseDataSource` (alias of `BasePostgresDataSource`) | PostgreSQL connections | `AbstractPostgresDataSource` -> `AbstractDataSource` |
+| `BaseEntity` (alias of `BasePostgresEntity`) | Drizzle model definitions | `AbstractEntity` |
+| `DefaultCRUDRepository` | Full CRUD operations (PostgreSQL connector) | `PersistableRepository` -> ... -> `AbstractRepository` |
+| `ReadableRepository` | Read-only operations (PostgreSQL connector) | `PostgresBaseRepository` -> `AbstractRepository` |
 
 ## Architecture
 
@@ -67,6 +70,7 @@ Core classes that power every Ignis application - from the Application entry poi
 - [Components](./components.md) - Pluggable modules, component lifecycle
 
 ### Data Layer
+- [Connectors](./connectors.md) - Base-vs-connectors architecture, dual-door exports, adding an engine
 - [Models & Enrichers](./models.md) - `BaseEntity`, schema definitions, enrichers
 - [DataSources](./datasources.md) - Database connections, auto-discovery
 - [Repositories](./repositories/) - CRUD operations, filtering, relations
@@ -78,11 +82,14 @@ Core classes that power every Ignis application - from the Application entry poi
 AbstractApplication
 └── BaseApplication ──────► Your Application
 
-AbstractRepository
-├── ReadableRepository
-│   └── PersistableRepository
-│       └── DefaultCRUDRepository ──────► Your Repository
-│
+AbstractRepository (engine-neutral, src/base)
+├── PostgresBaseRepository (connectors/postgres)
+│   ├── ReadableRepository
+│   │   └── PersistableRepository
+│   │       └── DefaultCRUDRepository ──────► Your Repository
+└── TypesenseBaseRepository (connectors/typesense)
+    └── ReadableSearchRepository -> ... -> DefaultSearchRepository
+
 AbstractRestController
 └── BaseRestController ──────► Your REST Controller
 
@@ -91,8 +98,13 @@ AbstractGrpcController
 BaseService ──────► Your Service
 BaseProvider ──────► Your Provider
 BaseComponent ──────► Your Component
-BaseDataSource ──────► Your DataSource
-BaseEntity ──────► Your Model
+
+AbstractDataSource (engine-neutral, src/base)
+├── AbstractPostgresDataSource -> BasePostgresDataSource (alias: BaseDataSource) ──────► Your DataSource
+└── AbstractSearchDataSource -> BaseSearchDataSource -> TypesenseDataSource
+
+AbstractEntity (engine-neutral, src/base)
+└── BasePostgresEntity (alias: BaseEntity) ──────► Your Model
 ```
 
 > **Related:** [Core Concepts Guide](../../guides/core-concepts/application/) | [Persistent Layer Guide](../../guides/core-concepts/persistent/)