@venizia/ignis-docs 0.0.8 → 0.2.0

package/content/extensions/src-details/mcp-server.md

@@ -1,6 +1,6 @@
 # MCP Docs Server: Deep Dive
 
-This document provides a detailed look into the architecture, features, and internal workings of the Ignis Documentation MCP Server. For a guide on how to use the server, see the [MCP Docs Server Quickstart](/guides/reference/mcp-docs-server).
+This document provides a detailed look into the architecture, features, and internal workings of the IGNIS Documentation MCP Server. For a guide on how to use the server, see the [MCP Docs Server Quickstart](/guides/reference/mcp-docs-server).
 
 ---
 
@@ -98,7 +98,7 @@ sequenceDiagram
     participant Helper as GitHubHelper
     participant API as GitHub API
 
-    AI->>MCP: searchCode("BaseController")
+    AI->>MCP: searchCode("BaseRestController")
     MCP->>Tool: Route to tool handler
     Tool->>Helper: GitHubHelper.searchCode()
     Helper->>API: GET /search/code
@@ -114,7 +114,7 @@ sequenceDiagram
 
 ### 1. Documentation Tools
 
-Tools for accessing the Ignis Framework wiki and guide documentation.
+Tools for accessing the IGNIS Framework wiki and guide documentation.
 
 | Tool | Purpose | Use Case |
 |------|---------|----------|
@@ -158,11 +158,11 @@ Retrieves high-level information about specific framework packages.
 
 ### 2. Code & Project Tools
 
-Tools for exploring the Ignis codebase, searching source code, and verifying dependencies via GitHub.
+Tools for exploring the IGNIS codebase, searching source code, and verifying dependencies via GitHub.
 
 | Tool | Purpose | Use Case |
 |------|---------|----------|
-| `searchCode` | Search source code | "Find usages of BaseController" |
+| `searchCode` | Search source code | "Find usages of BaseRestController" |
 | `listProjectFiles` | List repo files | "Show me files in packages/core" |
 | `viewSourceFile` | Read source code | "Read packages/core/src/index.ts" |
 | `verifyDependencies` | Check package.json | "Check dependencies for @venizia/core" |
@@ -370,23 +370,17 @@ DEBUG=1 ignis-docs-mcp
 All tools extend the `BaseTool` abstract class:
 
 ```typescript
-export abstract class BaseTool<
-  TInputSchema extends z.ZodType,
-  TOutputSchema extends z.ZodType
-> {
-  // Singleton pattern
-  static getInstance<T extends BaseTool>(this: new () => T): T {
-    // Returns cached instance or creates new one
-  }
+import type { Tool } from '@mastra/core/tools';
+import type { z } from 'zod';
 
-  // Required implementations
+export abstract class BaseTool<TInputSchema extends z.ZodType, TOutputSchema extends z.ZodType> {
   abstract readonly id: string;
   abstract readonly description: string;
   abstract readonly inputSchema: TInputSchema;
   abstract readonly outputSchema: TOutputSchema;
 
-  abstract execute(input: z.infer<TInputSchema>): Promise<z.infer<TOutputSchema>>;
-  abstract getTool(): MastraTool;
+  abstract execute(opts: z.infer<TInputSchema>): Promise<z.infer<TOutputSchema>>;
+  abstract getTool(): Tool<z.input<TInputSchema>, z.infer<TOutputSchema>>;
 }
 ```
 
@@ -397,9 +391,9 @@ export abstract class BaseTool<
 Create `tools/my-new-tool.tool.ts`:
 
 ```typescript
+import { createTool } from '@mastra/core/tools';
 import { z } from 'zod';
-import { BaseTool, createTool, type MastraTool } from './base.tool';
-import { DocsHelper } from '../helpers';
+import { BaseTool } from '../base.tool';
 
 // Define schemas
 const InputSchema = z.object({
@@ -417,18 +411,18 @@ export class MyNewTool extends BaseTool<typeof InputSchema, typeof OutputSchema>
   readonly inputSchema = InputSchema;
   readonly outputSchema = OutputSchema;
 
-  async execute(input: z.infer<typeof InputSchema>) {
+  async execute(opts: z.infer<typeof InputSchema>) {
     // Your logic here
     return { result: 'output' };
   }
 
-  getTool(): MastraTool {
+  getTool() {
     return createTool({
       id: this.id,
       description: this.description,
-      inputSchema: InputSchema,
-      outputSchema: OutputSchema,
-      execute: async ({ context }) => this.execute(context),
+      inputSchema: this.inputSchema,
+      outputSchema: this.outputSchema,
+      execute: async input => this.execute(InputSchema.parse(input)),
     });
   }
 }
@@ -611,7 +605,7 @@ DEBUG=docs:cache ignis-docs-mcp
 
 ### Contributing
 
-Want to add features or fix bugs? See the main Ignis repository:
+Want to add features or fix bugs? See the main IGNIS repository:
 
 - **Repository**: https://github.com/venizia-ai/ignis
 - **Issues**: Report bugs or request features

package/content/guides/core-concepts/application/bootstrapping.md

@@ -283,23 +283,18 @@ This ensures dependencies are available when artifacts are constructed.
 
 ## When Boot Runs
 
-### Integrated Boot
+### Explicit Boot (Standard Pattern)
 
-Boot runs as part of `BaseApplication` when `bootOptions` is configured. `BaseApplication.registerBooters()` is called during `initialize()`:
+Boot does NOT run automatically inside `start()`. Call `boot()` explicitly before `start()` - `boot()` calls `registerBooters()` (which registers the four built-in booters plus the `Bootstrapper`) and then runs all boot phases:
 
 ```typescript
-const app = new Application();
-await app.start();  // initialize() → registerBooters() + boot() → start HTTP server
+const app = new Application({ scope: 'Application', config: appConfigs });
+app.init();                        // register core bindings
+const report = await app.boot();   // registerBooters() → configure/discover/load
+await app.start();                 // initialize() → middlewares → HTTP server
 ```
 
-### Manual Boot
-
-Explicitly call `boot()` on the application:
-
-```typescript
-const app = new Application();
-const report = await app.boot();
-```
+This is the pattern used by the production reference app (`examples/vert/src/index.ts`).
 
 ### Using BootMixin (Alternative)
 
@@ -488,10 +483,12 @@ export class MiddlewareBooter extends BaseArtifactBooter {
 
 **Register Custom Booter:**
 
+Register it in `registerBooters()` - NOT in `preConfigure()`. `boot()` runs before `start()`, so `preConfigure()` (which runs during `initialize()` inside `start()`) is too late for the bootstrapper to discover the booter:
+
 ```typescript
 export class Application extends BaseApplication {
-  override preConfigure() {
-    // Register custom booter before boot runs
+  override async registerBooters() {
+    await super.registerBooters(); // built-in booters + bootstrapper
     this.booter(MiddlewareBooter);
   }
 }

package/content/guides/core-concepts/application/index.md

@@ -60,7 +60,7 @@ export class Application extends BaseApplication {
 
 ## Application Lifecycle
 
-The `Ignis` application has a well-defined lifecycle, managed primarily by the `start()` and `initialize()` methods.
+The `IGNIS` application has a well-defined lifecycle, managed primarily by the `start()` and `initialize()` methods.
 
 | Method | Description |
 | :--- | :--- |
@@ -190,10 +190,10 @@ this.controller(UserController, {
 The application detects the runtime automatically via `RuntimeModules.detect()`:
 
 ```typescript
-// Bun (default) — uses Bun.serve
+// Bun (default) - uses Bun.serve
 Bun.serve({ port, hostname, fetch: server.fetch })
 
-// Node.js — requires @hono/node-server
+// Node.js - requires @hono/node-server
 import { serve } from '@hono/node-server'
 serve({ fetch: server.fetch, port, hostname })
 ```

package/content/guides/core-concepts/components.md

@@ -15,31 +15,40 @@ A single component can bundle everything needed for a specific domain--for examp
 
 ## Built-in Components
 
-Ignis includes ready-to-use components for common features. The following are exported from the main barrel (`@venizia/ignis`):
+IGNIS includes ready-to-use components for common features. The following are exported from the main barrel (`@venizia/ignis`):
 
 | Component | Description |
 | :--- | :--- |
 | **Authentication** | JWT + Basic auth strategies, token services, strategy registry |
 | **Authorization** | Casbin-based RBAC, permission mapping, `authorize()` middleware |
-| **HealthCheckComponent** | `GET /health`, `/health/live`, `/health/ready` |
-| **SwaggerComponent** | Swagger UI or Scalar UI for API documentation |
+| **HealthCheckComponent** | `GET /health`, `POST /health/ping` |
+| **ApiReferenceComponent** | Swagger UI or Scalar UI for API documentation |
 | **RequestTrackerComponent** | `x-request-id` header, request body parsing |
 
 The following components require direct subpath imports:
 
 | Component | Import From | Description |
 | :--- | :--- | :--- |
-| **MailComponent** | `@venizia/ignis/components/mail` | Nodemailer/Mailgun transporters with queue executors |
-| **SocketIOComponent** | `@venizia/ignis/components/socket-io` | Socket.IO server with Redis adapter |
-| **StaticAssetComponent** | `@venizia/ignis/components/static-asset` | File upload/download CRUD, MinIO/Disk storage |
-| **WebSocketComponent** | `@venizia/ignis/components/websocket` | Native WebSocket support |
+| **MailComponent** | `@venizia/ignis/mail` | Nodemailer/Mailgun transporters with queue executors |
+| **SocketIOComponent** | `@venizia/ignis/socket-io` | Socket.IO server with Redis adapter |
+| **StaticAssetComponent** | `@venizia/ignis/static-asset` | File upload/download CRUD, MinIO/Disk storage |
+| **WebSocketComponent** | `@venizia/ignis/websocket` | Native WebSocket support |
 
 See the [**Built-in Components Reference**](../../extensions/components/) for detailed documentation.
 
 ## Creating a Simple Component
 
 ```typescript
-import { BaseApplication, BaseComponent, inject, CoreBindings, ValueOrPromise, Binding } from '@venizia/ignis';
+import {
+  BaseApplication,
+  BaseComponent,
+  BaseRestController,
+  Binding,
+  controller,
+  CoreBindings,
+  inject,
+  ValueOrPromise,
+} from '@venizia/ignis';
 
 // Define a service
 class NotificationService {
@@ -98,7 +107,7 @@ Register components in your application's `preConfigure` method:
 export class Application extends BaseApplication {
   preConfigure(): ValueOrPromise<void> {
     this.component(HealthCheckComponent);
-    this.component(SwaggerComponent);
+    this.component(ApiReferenceComponent);
     this.component(NotificationComponent);
   }
 }
@@ -139,7 +148,7 @@ export class Application extends BaseApplication {
   - [BaseComponent API](/references/base/components) - Complete API reference
   - [Authentication Component](/extensions/components/authentication/) - JWT authentication
   - [Health Check Component](/extensions/components/health-check) - Health endpoints
-  - [Swagger Component](/extensions/components/swagger) - API documentation
+  - [Swagger Component](/extensions/components/api-reference) - API documentation
   - [Socket.IO Component](/extensions/components/socket-io/) - WebSocket support
 
 - **Best Practices:**

package/content/guides/core-concepts/dependency-injection.md

@@ -4,7 +4,7 @@ Dependency Injection (DI) enables loosely coupled, testable code by automaticall
 
 > **Deep Dive:** See [DI Reference](../../references/base/dependency-injection.md) for technical details on Container, Binding, and `@inject`.
 
-> **Standalone Package:** The core DI container is available as the standalone `@venizia/ignis-inversion` package for use outside the Ignis framework. See [Inversion Package Reference](/extensions/helpers/inversion/) for details.
+> **Standalone Package:** The core DI container is available as the standalone `@venizia/ignis-inversion` package for use outside the IGNIS framework. See [Inversion Package Reference](/extensions/helpers/inversion/) for details.
 
 ## Core Concepts
 
@@ -46,9 +46,12 @@ graph TD
 
 When the container instantiates a class, it follows a two-phase process:
 
-1. **Constructor injection** -- Reads `@inject` metadata from the class, sorts by parameter index, resolves each dependency from the container, and passes them as constructor arguments.
+1. **Constructor injection** -- Reads `@inject` metadata from the class by parameter index (no sort - the metadata is already index-keyed), resolves each dependency from the container, and passes them as constructor arguments.
 2. **Property injection** -- After construction, reads property metadata and assigns each dependency to the decorated properties.
 
+> [!IMPORTANT]
+> Every constructor parameter of a container-instantiated class must carry `@inject`. Mixing decorated and undecorated parameters is refused - `instantiate()` throws `[ClassName] Constructor parameter N has no @inject`. See the [DI Reference](../../references/base/dependency-injection.md#instantiation-algorithm-two-phase) for the full rule and the `@repository` exception.
+
 ## Binding Dependencies
 
 Before a dependency can be injected, it must be **bound** to the container. This is typically done in the `preConfigure` method of your `Application` class.
@@ -117,7 +120,7 @@ Tags are used by the container's `findByTag()` method to discover bindings by ca
 
 ## Injecting Dependencies
 
-`Ignis` provides the `@inject` decorator to request dependencies from the container.
+`IGNIS` provides the `@inject` decorator to request dependencies from the container.
 
 ### Constructor Injection (Recommended)
 

package/content/guides/core-concepts/grpc-controllers.md

@@ -1,6 +1,6 @@
 # gRPC Controllers
 
-Ignis provides first-class support for gRPC via the [ConnectRPC](https://connectrpc.com/) protocol. gRPC controllers use Protobuf service definitions for strongly-typed RPC methods, and are served over the same Hono HTTP server as REST controllers.
+IGNIS provides first-class support for gRPC via the [ConnectRPC](https://connectrpc.com/) protocol. gRPC controllers use Protobuf service definitions for strongly-typed RPC methods, and are served over the same Hono HTTP server as REST controllers.
 
 > **Deep Dive:** See [gRPC Controllers Reference](../../references/base/grpc-controllers.md) for the complete API.
 
@@ -83,7 +83,7 @@ export class GreeterController extends BaseGrpcController {
 
 ## RPC Method Decorators
 
-Ignis provides a decorator for each gRPC method type:
+IGNIS provides a decorator for each gRPC method type:
 
 - `@unary(opts)` -- Single request, single response. **This is the only supported method type** in the current version.
 - `@serverStream(opts)` -- Decorator exists for metadata, but throws at runtime.
@@ -102,7 +102,7 @@ async sayHello(opts: { request: SayHelloRequest; context: TRouteContext }): Prom
 @unary({
   configs: {
     name: 'getUser',
-    authenticate: { strategies: ['jwt'], mode: 'required' },
+    authenticate: { strategies: ['jwt'], mode: 'any' },
   },
 })
 async getUser(opts: { request: GetUserRequest; context: TRouteContext }): Promise<GetUserResponse> { ... }
@@ -112,7 +112,7 @@ async getUser(opts: { request: GetUserRequest; context: TRouteContext }): Promis
   configs: {
     name: 'deleteUser',
     authenticate: { strategies: ['jwt'] },
-    authorize: { resource: 'user', scopes: ['delete'] },
+    authorize: { action: 'delete', resource: 'user' },
   },
 })
 async deleteUser(opts: { request: DeleteUserRequest; context: TRouteContext }): Promise<DeleteUserResponse> { ... }
@@ -255,7 +255,8 @@ plugins:
 ```
 
 ```bash
-npx buf generate src/controllers/greeter/proto
+bun add -d @bufbuild/buf @bufbuild/protoc-gen-es
+node_modules/.bin/buf generate src/controllers/greeter/proto
 ```
 
 ### 3. Use the generated types in your controller

package/content/guides/core-concepts/persistent/datasources.md

@@ -2,19 +2,19 @@
 
 A DataSource manages database connections and supports **schema auto-discovery** from repositories.
 
-> [!NOTE] PostgreSQL First
-> IGNIS currently focuses on **PostgreSQL** as the primary database. Support for other database systems (MySQL, SQLite, etc.) is planned for future releases.
+> [!NOTE] Connectors
+> This guide covers the **PostgreSQL connector** (`BasePostgresDataSource`, aliased as `BaseDataSource` for backward compatibility) - the primary relational engine and the one used by most applications. IGNIS also ships a **typesense connector** for full-text/vector search (see [Search & Typesense](./search-typesense)). Both implement the same engine-neutral `AbstractDataSource` contract - see [Connectors](/references/base/connectors) for the architecture.
 
 ## Creating a DataSource
 
 ```typescript
 // src/datasources/postgres.datasource.ts
 import {
-  BaseDataSource,
+  BasePostgresDataSource,
   datasource,
   ValueOrPromise,
 } from '@venizia/ignis';
-import { drizzle } from 'drizzle-orm/node-postgres';
+import { NodePostgresDriver } from '@venizia/ignis/postgres/node-postgres';
 import { Pool } from 'pg';
 
 interface IDSConfigs {
@@ -25,8 +25,8 @@ interface IDSConfigs {
   password: string;
 }
 
-@datasource({ driver: 'node-postgres' })
-export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
+@datasource({ driver: NodePostgresDriver })
+export class PostgresDataSource extends BasePostgresDataSource<IDSConfigs> {
   constructor() {
     super({
       name: PostgresDataSource.name,
@@ -42,16 +42,11 @@ export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   }
 
   override configure(): ValueOrPromise<void> {
-    // getSchema() auto-discovers models from @repository bindings
-    const schema = this.getSchema();
+    const schema = Object.keys(this.getSchema());
+    this.logger.debug('[configure] Auto-discovered schema | Keys: %o', schema);
 
-    this.logger.debug(
-      '[configure] Auto-discovered schema | Keys: %o',
-      Object.keys(schema),
-    );
-
-    this.pool = new Pool(this.settings);
-    this.connector = drizzle({ client: this.pool, schema });
+    // That is all - naming NodePostgresDriver above is what wires the driver and connector.
+    this.client = new Pool(this.settings);
   }
 
   override getConnectionString(): ValueOrPromise<string> {
@@ -61,21 +56,24 @@ export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
 }
 ```
 
+> [!NOTE] Driver seam: the raw client goes on `this.client`
+> `this.client = new Pool(...)` is the short path: `configure()` builds only the client, and `getConnector()`/`beginTransaction()` lazily instantiate the class named in `@datasource({ driver })` over it - `NodePostgresDriver` here. There is no `pool` field - the raw-client slot is `client`, whatever the client happens to be. Naming the driver class (rather than a driver-name string) is what carries `pg` into the app's bundle - a bundler only packages a real value reference, never text. The alternative is to wire a driver yourself for a custom or third-party driver: `configure()` calls `this.useDriver({ driver, schema? })`, which assigns `this.driver` **and** builds `this.connector` in one step (so the half-wired state cannot exist), bypassing `@datasource({ driver })` entirely. See [Postgres Drivers & Supabase](./postgres-drivers) for `postgres-js` and Supabase.
+
 **How auto-discovery works:**
 
 1. `@repository` decorators register model-datasource bindings in the `MetadataRegistry`
-2. When `configure()` is called, `getSchema()` invokes `discoverSchema()` which calls `MetadataRegistry.buildSchema({ dataSource })` to collect all bound models and their relations
-3. Drizzle is initialized with the complete schema (tables + Drizzle relations)
+2. `getSchema()` invokes `discoverSchema()` which calls `MetadataRegistry.buildSchema({ dataSource })` to collect all bound models and their relations
+3. The lazily-built Drizzle connector is initialized with the complete schema (tables + Drizzle relations)
 
-You can disable auto-discovery per datasource via `@datasource({ driver: 'node-postgres', autoDiscovery: false })`.
+You can disable auto-discovery per datasource via `@datasource({ driver: NodePostgresDriver, autoDiscovery: false })`.
 
 ## Manual Schema (Optional)
 
 If you need explicit control, you can still provide schema manually:
 
 ```typescript
-@datasource({ driver: 'node-postgres' })
-export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
+@datasource({ driver: NodePostgresDriver })
+export class PostgresDataSource extends BasePostgresDataSource<IDSConfigs> {
   constructor() {
     super({
       name: PostgresDataSource.name,
@@ -93,16 +91,18 @@ export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
 ## DataSource Hierarchy
 
 ```
-AbstractDataSource extends BaseHelper
-  └── BaseDataSource
-        ├── configure()               # Setup pool + Drizzle connector (abstract)
-        ├── getConnectionString()     # Build connection URL (abstract)
-        ├── getSchema()               # Auto-discover from @repository bindings
-        ├── discoverSchema()          # Internal: reads MetadataRegistry
-        ├── hasDiscoverableModels()   # Check if any repos reference this DS
-        ├── beginTransaction(opts?)   # Start transaction with isolation level
-        ├── getConnector()            # Get Drizzle connector
-        └── getSettings()            # Get connection config
+AbstractDataSource extends BaseHelper        # engine-neutral, src/base - no pool, no Drizzle
+  └── AbstractPostgresDataSource              # connectors/postgres - adds pool, connector
+        └── BasePostgresDataSource (alias: BaseDataSource)
+              ├── configure()               # Assign this.client (abstract) - base wires driver + connector
+              ├── getConnectionString()     # Build connection URL (abstract)
+              ├── getSchema()               # Auto-discover from @repository bindings
+              ├── discoverSchema()          # Internal: reads MetadataRegistry
+              ├── hasDiscoverableModels()   # Check if any repos reference this DS
+              ├── getCapabilities()         # Returns { transactions: true }
+              ├── beginTransaction(opts?)   # Start transaction with isolation level
+              ├── getConnector()            # Get Drizzle connector
+              └── getSettings()            # Get connection config
 ```
 
 ## Registering a DataSource
@@ -118,19 +118,19 @@ export class Application extends BaseApplication {
 
 DataSources are bound as **singletons** to ensure connection pool sharing across the application.
 
-## Supported Drivers
+## Supported Engines
 
-| Driver | Package | Status |
-|--------|---------|--------|
-| `node-postgres` | `pg` | Supported |
-| `mysql2` | `mysql2` | Planned |
-| `better-sqlite3` | `better-sqlite3` | Planned |
+| Engine | Driver/Package | Import | Status |
+|--------|---------|--------|--------|
+| PostgreSQL | `node-postgres` (`pg`) | `@venizia/ignis` or `@venizia/ignis/postgres` | Supported, transactions + 3 isolation levels |
+| Typesense (search) | `typesense` (optional peer) | `@venizia/ignis/typesense` (subpath-only) | Supported, no transactions/locks |
+| MySQL / SQLite | - | - | Not planned; would be a new connector under `src/connectors/` |
 
 ## DataSource Template
 
 ```typescript
-import { BaseDataSource, datasource, ValueOrPromise } from '@venizia/ignis';
-import { drizzle } from 'drizzle-orm/node-postgres';
+import { BasePostgresDataSource, datasource, ValueOrPromise } from '@venizia/ignis';
+import { NodePostgresDriver } from '@venizia/ignis/postgres/node-postgres';
 import { Pool } from 'pg';
 
 interface IDSConfigs {
@@ -141,8 +141,8 @@ interface IDSConfigs {
   password: string;
 }
 
-@datasource({ driver: 'node-postgres' })
-export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
+@datasource({ driver: NodePostgresDriver })
+export class PostgresDataSource extends BasePostgresDataSource<IDSConfigs> {
   constructor() {
     super({
       name: PostgresDataSource.name,
@@ -157,9 +157,7 @@ export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   }
 
   override configure(): ValueOrPromise<void> {
-    const schema = this.getSchema();
-    this.pool = new Pool(this.settings);
-    this.connector = drizzle({ client: this.pool, schema });
+    this.client = new Pool(this.settings);
   }
 
   override getConnectionString(): ValueOrPromise<string> {
@@ -177,6 +175,7 @@ export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   - [Repositories](/guides/core-concepts/persistent/repositories) - Use DataSources for database access
   - [Models](/guides/core-concepts/persistent/models) - Entity schemas loaded by DataSource
   - [Transactions](/guides/core-concepts/persistent/transactions) - Multi-operation database transactions
+  - [Search & Typesense](/guides/core-concepts/persistent/search-typesense) - The typesense connector
   - [Application](/guides/core-concepts/application/) - Registering DataSources
 
 - **References:**

package/content/guides/core-concepts/persistent/index.md

@@ -2,6 +2,9 @@
 
 The persistent layer manages data using [Drizzle ORM](https://orm.drizzle.team/) for type-safe database access and the Repository pattern for data abstraction.
 
+> [!NOTE] Connectors
+> This page and the ones below it focus on the **PostgreSQL connector** (Drizzle + relational tables), the default and most common engine. The persistence layer also ships a **typesense connector** for search (see [Search & Typesense](./search-typesense)). Both share the same engine-neutral `AbstractRepository`/`AbstractDataSource`/`AbstractEntity` contracts - see [Connectors](/references/base/connectors) for the architecture.
+
 ## Architecture Overview
 
 ```
@@ -27,14 +30,15 @@ The persistent layer manages data using [Drizzle ORM](https://orm.drizzle.team/)
 | **Models** | Define data structure with Drizzle schemas and relations | [Models Guide](./models.md) |
 | **DataSources** | Manage database connections with auto-discovery | [DataSources Guide](./datasources.md) |
 | **Repositories** | Provide type-safe CRUD operations | [Repositories Guide](./repositories.md) |
-| **Transactions** | Handle atomic multi-step operations | [Transactions Guide](./transactions.md) |
+| **Transactions** | Handle atomic multi-step operations (PostgreSQL connector only) | [Transactions Guide](./transactions.md) |
+| **Search & Typesense** | Full-text/faceted search over documents | [Search & Typesense Guide](./search-typesense.md) |
 
 ## Quick Example
 
 ```typescript
 // 1. Define a Model
 @model({ type: 'entity' })
-export class User extends BaseEntity<typeof User.schema> {
+export class User extends BasePostgresEntity<typeof User.schema> {
   static override schema = pgTable('User', {
     ...generateIdColumnDefs({ id: { dataType: 'string' } }),
     name: text('name').notNull(),
@@ -45,8 +49,8 @@ export class User extends BaseEntity<typeof User.schema> {
 }
 
 // 2. Create a DataSource
-@datasource({ driver: 'node-postgres' })
-export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
+@datasource({ driver: NodePostgresDriver })
+export class PostgresDataSource extends BasePostgresDataSource<IDSConfigs> {
   constructor() {
     super({
       name: PostgresDataSource.name,
@@ -61,9 +65,12 @@ export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   }
 
   override configure(): ValueOrPromise<void> {
-    const schema = this.getSchema();
-    this.pool = new Pool(this.settings);
-    this.connector = drizzle({ client: this.pool, schema });
+    this.client = new Pool(this.settings); // NodePostgresDriver above wires the driver + connector
+  }
+
+  override getConnectionString(): ValueOrPromise<string> {
+    const { host, port, user, password, database } = this.settings;
+    return `postgresql://${user}:${password}@${host}:${port}/${database}`;
   }
 }
 
@@ -100,12 +107,14 @@ export class Application extends BaseApplication {
   - [DataSources](./datasources) - Database connections
   - [Repositories](./repositories) - Data access layer
   - [Transactions](./transactions) - Atomic operations
+  - [Search & Typesense](./search-typesense) - The typesense connector
 
 - **Related Concepts:**
   - [Services](/guides/core-concepts/services) - Use repositories for business logic
   - [Application](/guides/core-concepts/application/) - Registering persistent resources
 
 - **References:**
+  - [Connectors API](/references/base/connectors) - Base-vs-connectors architecture
   - [Models API](/references/base/models) - Complete models reference
   - [DataSources API](/references/base/datasources) - Complete datasources reference
   - [Repositories API](/references/base/repositories/) - Complete repositories reference