diff --git a/.github/instructions/adapters.instructions.md b/.github/instructions/adapters.instructions.md
new file mode 100644
index 0000000..ffad981
--- /dev/null
+++ b/.github/instructions/adapters.instructions.md
@@ -0,0 +1,275 @@
+# Database Adapter Implementation Guide
+
+Instructions for implementing or modifying database adapters in DatabaseKit.
+
+---
+
+## 🎯 Adapter Purpose
+
+Adapters translate the unified `Repository<T>` interface to database-specific operations.
+Each adapter encapsulates ALL database-specific logic.
+
+---
+
+## 📐 Adapter Structure
+
+Every adapter MUST implement these components:
+
+```typescript
+class DatabaseAdapter {
+  // 1. Connection Management
+  connect(uri: string, options?: ConnectionOptions): Promise<void>;
+  disconnect(): Promise<void>;
+  isConnected(): boolean;
+
+  // 2. Repository Factory
+  createRepository<T>(options: RepositoryOptions<T>): Repository<T>;
+
+  // 3. Transaction Support
+  withTransaction<R>(fn: (ctx: TransactionContext) => Promise<R>): Promise<R>;
+
+  // 4. Health Check
+  healthCheck(): Promise<HealthCheckResult>;
+}
+```
+
+---
+
+## ✅ Implementation Checklist
+
+When creating or modifying an adapter:
+
+### Connection
+
+- [ ] Implement connection with retry logic
+- [ ] Handle connection pooling via `PoolConfig`
+- [ ] Implement graceful disconnect
+- [ ] Add connection state tracking
+
+### Repository Methods (ALL required)
+
+- [ ] `create(data)` - Insert single document
+- [ ] `findById(id)` - Find by primary key
+- [ ] `findOne(filter)` - Find first match
+- [ ] `findAll(filter)` - Find all matches
+- [ ] `findPage(options)` - Paginated query
+- [ ] `updateById(id, data)` - Update by primary key
+- [ ] `deleteById(id)` - Delete by primary key
+- [ ] `count(filter)` - Count matches
+- [ ] `exists(filter)` - Check existence
+- [ ] `insertMany(data[])` - Bulk insert
+- [ ] `updateMany(filter, data)` - Bulk update
+- [ ] `deleteMany(filter)` - Bulk delete
+- [ ] `upsert(filter, data)` - Update or insert
+- [ ] `distinct(field, filter)` - Unique values
+- [ ] `select(filter, fields)` - Field projection
+
+### Optional Features
+
+- [ ] `softDelete(id)` - When `softDelete: true`
+- [ ] `restore(id)` - When `softDelete: true`
+- [ ] `findWithDeleted(filter)` - When `softDelete: true`
+
+### Cross-Cutting
+
+- [ ] Timestamps (`createdAt`, `updatedAt`)
+- [ ] Hooks (`beforeCreate`, `afterCreate`, etc.)
+- [ ] Transaction context repositories
+- [ ] Health check with connection details
+
+---
+
+## 🔧 MongoDB Adapter Patterns
+
+### Model Registration
+
+```typescript
+// Use Mongoose schema
+const schema = new Schema<T>(definition, { timestamps: true });
+const model = mongoose.model<T>(name, schema);
+```
+
+### Query Translation
+
+```typescript
+// MongoDB operators are native
+{
+  age: {
+    $gte: 18;
+  }
+} // Direct pass-through
+{
+  status: {
+    $in: ["active", "pending"];
+  }
+}
+```
+
+### Transactions
+
+```typescript
+// Use ClientSession
+const session = await mongoose.startSession();
+session.startTransaction();
+try {
+  await model.create([data], { session });
+  await session.commitTransaction();
+} catch (e) {
+  await session.abortTransaction();
+  throw e;
+} finally {
+  session.endSession();
+}
+```
+
+### ID Handling
+
+```typescript
+// MongoDB uses ObjectId
+import { Types } from "mongoose";
+const objectId = new Types.ObjectId(id);
+```
+
+---
+
+## 🔧 PostgreSQL Adapter Patterns
+
+### Table Configuration
+
+```typescript
+// Use Knex table name
+const table = knex<T>(tableName);
+```
+
+### Query Translation
+
+```typescript
+// Convert operators to SQL
+{ price: { gt: 100 } }       → .where('price', '>', 100)
+{ status: { in: [...] } }    → .whereIn('status', [...])
+{ name: { like: '%john%' } } → .whereILike('name', '%john%')
+{ deleted: { isNull: true }} → .whereNull('deleted')
+```
+
+### Transactions
+
+```typescript
+// Use Knex transaction
+await knex.transaction(async (trx) => {
+  await trx("users").insert(data);
+  await trx("orders").insert(orderData);
+});
+```
+
+### ID Handling
+
+```typescript
+// PostgreSQL uses auto-increment or UUID
+// Return inserted row to get ID
+const [inserted] = await knex("users").insert(data).returning("*");
+```
+
+---
+
+## 🪝 Hook Implementation
+
+All adapters must support lifecycle hooks:
+
+```typescript
+interface RepositoryHooks<T> {
+  beforeCreate?(ctx: HookContext<T>): Partial<T> | Promise<Partial<T>>;
+  afterCreate?(entity: T): void | Promise<void>;
+  beforeUpdate?(ctx: HookContext<T>): Partial<T> | Promise<Partial<T>>;
+  afterUpdate?(entity: T | null): void | Promise<void>;
+  beforeDelete?(id: string | number): void | Promise<void>;
+  afterDelete?(success: boolean): void | Promise<void>;
+}
+```
+
+### Hook Execution Order
+
+1. `beforeCreate` → modify data → `create()` → `afterCreate`
+2. `beforeUpdate` → modify data → `updateById()` → `afterUpdate`
+3. `beforeDelete` → `deleteById()` → `afterDelete`
+
+### Hook Context
+
+```typescript
+interface HookContext<T> {
+  data: Partial<T>; // The data being created/updated
+  repository: Repository<T>; // Self-reference for lookups
+}
+```
+
+---
+
+## ⏱️ Timestamp Implementation
+
+When `timestamps: true`:
+
+```typescript
+// On create
+data.createdAt = new Date();
+data.updatedAt = new Date();
+
+// On update
+data.updatedAt = new Date();
+// Never modify createdAt on update!
+```
+
+---
+
+## 🗑️ Soft Delete Implementation
+
+When `softDelete: true`:
+
+```typescript
+// softDelete() - Set deletedAt
+await repo.updateById(id, { deletedAt: new Date() });
+
+// restore() - Clear deletedAt
+await repo.updateById(id, { deletedAt: null });
+
+// findAll/findOne - Exclude deleted
+filter.deletedAt = { isNull: true }; // or { $eq: null } for Mongo
+
+// findWithDeleted - Include deleted
+// Skip the deletedAt filter
+```
+
+---
+
+## 🧪 Testing Requirements
+
+Every adapter must have tests for:
+
+1. **Connection** - Connect, disconnect, reconnect
+2. **CRUD** - All basic operations
+3. **Bulk** - insertMany, updateMany, deleteMany
+4. **Queries** - Filters, pagination, sorting
+5. **Transactions** - Commit, rollback, nested
+6. **Hooks** - All 6 hooks fire correctly
+7. **Timestamps** - createdAt/updatedAt auto-set
+8. **Soft Delete** - delete, restore, findWithDeleted
+9. **Health Check** - Returns correct status
+
+---
+
+## 📝 Adding a New Adapter
+
+To add a new database (e.g., SQLite, MySQL):
+
+1. Create `src/adapters/sqlite.adapter.ts`
+2. Implement `DatabaseAdapter` interface
+3. Add to `DatabaseService`:
+   ```typescript
+   createSqliteRepository<T>(opts): Repository<T>
+   ```
+4. Add connection config type to `DatabaseConfig`
+5. Add comprehensive tests
+6. Export from `index.ts` if public
+7. Document in README
+
+---
+
+_Last updated: February 2026_
diff --git a/.github/instructions/bugfix.instructions.md b/.github/instructions/bugfix.instructions.md
new file mode 100644
index 0000000..f1c3e98
--- /dev/null
+++ b/.github/instructions/bugfix.instructions.md
@@ -0,0 +1,380 @@
+# Bug Fix Instructions
+
+Guidelines for diagnosing and fixing bugs in DatabaseKit.
+
+---
+
+## 🔍 Bug Investigation Process
+
+### 1. Reproduce the Issue
+
+```bash
+# Create a minimal test case
+npm test -- -t "bug description"
+
+# Or create a new test
+describe('Bug #123', () => {
+  it('should reproduce the issue', async () => {
+    // Minimal reproduction steps
+  });
+});
+```
+
+### 2. Identify the Root Cause
+
+- Check the adapter implementation (MongoDB vs PostgreSQL)
+- Trace the call stack
+- Check for edge cases in input
+- Review recent changes in git history
+
+### 3. Understand the Expected Behavior
+
+- Check the interface definition in contracts
+- Review existing tests
+- Check documentation
+
+---
+
+## 🐛 Common Bug Categories
+
+### Connection Issues
+
+**Symptoms:** Connection timeout, "not connected" errors
+
+**Check:**
+
+```typescript
+// Is connection properly awaited?
+await adapter.connect(uri);
+
+// Is connection state tracked?
+if (!this.isConnected()) {
+  throw new Error('Not connected');
+}
+
+// Is pool configured correctly?
+pool: { min: 2, max: 10 }
+```
+
+### Query Filter Issues
+
+**Symptoms:** Wrong results, missing data, too many results
+
+**Check:**
+
+```typescript
+// MongoDB - Is the filter format correct?
+{
+  status: {
+    $eq: "active";
+  }
+}
+
+// PostgreSQL - Are operators translated?
+{
+  status: {
+    eq: "active";
+  }
+} // → .where('status', '=', 'active')
+
+// Soft delete - Are deleted records excluded?
+if (this.softDelete) {
+  filter[this.softDeleteField] = { isNull: true };
+}
+```
+
+### Transaction Issues
+
+**Symptoms:** Data inconsistency, partial commits
+
+**Check:**
+
+```typescript
+// Is session/transaction passed to all operations?
+await model.create([data], { session }); // MongoDB
+await trx("table").insert(data); // PostgreSQL
+
+// Is rollback called on error?
+try {
+  await commit();
+} catch (e) {
+  await rollback();
+  throw e;
+}
+```
+
+### Type Issues
+
+**Symptoms:** TypeScript errors, runtime type mismatches
+
+**Check:**
+
+```typescript
+// Are generics properly propagated?
+createRepository<T>(opts): Repository<T>
+
+// Are return types correct?
+async findById(id: string): Promise<T | null>  // Can return null!
+
+// Are optional fields marked?
+interface Options {
+  required: string;
+  optional?: string;
+}
+```
+
+### Hook Issues
+
+**Symptoms:** Hooks not firing, data not modified
+
+**Check:**
+
+```typescript
+// Is hook called at the right time?
+if (this.hooks?.beforeCreate) {
+  data = await this.hooks.beforeCreate({ data, repository: this });
+}
+
+// Is modified data used?
+const result = await this.model.create(data); // Use modified data!
+
+// Is async hook awaited?
+await this.hooks.afterCreate(result);
+```
+
+---
+
+## 🔧 Bug Fix Workflow
+
+### Step 1: Create Failing Test
+
+```typescript
+describe("Bug #123: Description", () => {
+  it("should handle the edge case correctly", async () => {
+    // This test should FAIL initially
+    const result = await repo.findById("");
+    expect(result).toBeNull(); // Currently throws
+  });
+});
+```
+
+### Step 2: Fix the Bug
+
+```typescript
+// Add proper handling
+async findById(id: string): Promise<T | null> {
+  if (!id) {
+    return null; // Handle empty ID
+  }
+  return this.model.findById(id).lean().exec();
+}
+```
+
+### Step 3: Verify Test Passes
+
+```bash
+npm test -- -t "should handle the edge case"
+# ✓ should handle the edge case correctly
+```
+
+### Step 4: Check for Regressions
+
+```bash
+npm test
+# All tests should still pass
+```
+
+### Step 5: Apply Fix to Both Adapters
+
+If the bug exists in one adapter, check if it exists in the other:
+
+```typescript
+// mongo.adapter.ts
+async findById(id: string): Promise<T | null> {
+  if (!id) return null;
+  // ...
+}
+
+// postgres.adapter.ts
+async findById(id: string | number): Promise<T | null> {
+  if (!id) return null;
+  // ...
+}
+```
+
+---
+
+## 📋 Bug Fix Checklist
+
+- [ ] Reproduced the bug with a failing test
+- [ ] Identified root cause
+- [ ] Fixed in MongoAdapter (if applicable)
+- [ ] Fixed in PostgresAdapter (if applicable)
+- [ ] All existing tests still pass
+- [ ] New test for the bug passes
+- [ ] Edge cases covered
+- [ ] CHANGELOG updated
+- [ ] Commit message references issue
+
+---
+
+## 💬 Commit Message Format
+
+```
+fix: brief description of the fix
+
+Fixes #123
+
+- Root cause: explanation of why the bug occurred
+- Solution: explanation of the fix
+- Impact: what areas are affected
+```
+
+---
+
+## ⚠️ Common Pitfalls
+
+### Don't Fix Symptoms, Fix Causes
+
+```typescript
+// BAD - Hiding the error
+try {
+  return await this.query();
+} catch (e) {
+  return null; // Silently failing!
+}
+
+// GOOD - Fix the actual issue
+async query() {
+  if (!this.isValidInput(input)) {
+    throw new BadRequestException('Invalid input');
+  }
+  return await this.performQuery();
+}
+```
+
+### Don't Break Backwards Compatibility
+
+```typescript
+// BAD - Changing return type
+// Was: findById(id): Promise<T | null>
+// Now: findById(id): Promise<T>  // Breaking change!
+
+// GOOD - Keep contract, fix implementation
+async findById(id: string): Promise<T | null> {
+  // Fix the bug without changing the signature
+}
+```
+
+### Don't Skip Tests
+
+```typescript
+// BAD
+it.skip("should handle edge case", () => {
+  // "I'll fix this later"
+});
+
+// GOOD
+it("should handle edge case", async () => {
+  expect(await repo.findById("")).toBeNull();
+});
+```
+
+---
+
+## 🧪 Debugging Tips
+
+### Enable Debug Logging
+
+```typescript
+// Add to adapter
+private debug(message: string, data?: unknown): void {
+  if (process.env.DEBUG === 'true') {
+    console.log(`[${this.constructor.name}] ${message}`, data);
+  }
+}
+
+// Use in methods
+async findById(id: string): Promise<T | null> {
+  this.debug('findById called', { id });
+  const result = await this.model.findById(id);
+  this.debug('findById result', { found: !!result });
+  return result;
+}
+```
+
+### Inspect Database State
+
+```typescript
+// In test
+it("debug test", async () => {
+  // Check actual database state
+  const allRecords = await repo.findAll({});
+  console.log("Current records:", allRecords);
+
+  // Check what query returns
+  const result = await repo.findById("123");
+  console.log("Query result:", result);
+});
+```
+
+### Check Mongoose/Knex Debug
+
+```typescript
+// MongoDB - Enable Mongoose debug
+mongoose.set("debug", true);
+
+// PostgreSQL - Knex debug
+const knex = require("knex")({
+  client: "pg",
+  debug: true,
+  // ...
+});
+```
+
+---
+
+## 📝 Example Bug Fix
+
+**Bug:** `updateById` doesn't return updated entity on PostgreSQL
+
+```typescript
+// 1. Create failing test
+it('should return updated entity', async () => {
+  const created = await repo.create({ name: 'original' });
+  const updated = await repo.updateById(created.id, { name: 'updated' });
+  expect(updated?.name).toBe('updated'); // Currently 'original'!
+});
+
+// 2. Identify root cause
+async updateById(id, data) {
+  await this.knex(this.table).where('id', id).update(data);
+  return this.findById(id); // Missing returning('*')
+}
+
+// 3. Fix
+async updateById(id, data) {
+  const [updated] = await this.knex(this.table)
+    .where('id', id)
+    .update(data)
+    .returning('*');  // Return updated row
+  return updated ?? null;
+}
+
+// 4. Verify fix
+npm test -- -t "should return updated entity"
+# ✓ should return updated entity
+
+// 5. Commit
+git commit -m "fix: updateById now returns updated entity on PostgreSQL
+
+Fixes #456
+
+- Root cause: Missing .returning('*') in Knex update query
+- Solution: Added .returning('*') to get updated row
+- Impact: PostgresAdapter.updateById now correctly returns updated entity"
+```
+
+---
+
+_Last updated: February 2026_
diff --git a/.github/instructions/features.instructions.md b/.github/instructions/features.instructions.md
new file mode 100644
index 0000000..547a133
--- /dev/null
+++ b/.github/instructions/features.instructions.md
@@ -0,0 +1,379 @@
+# Feature Implementation Guide
+
+Instructions for adding new features to DatabaseKit.
+
+---
+
+## 🎯 Before You Start
+
+1. **Check existing issues** - Is this already requested/planned?
+2. **Understand the scope** - Does it fit the library's purpose?
+3. **Consider both adapters** - Will it work for MongoDB AND PostgreSQL?
+4. **Plan the API** - What will the interface look like?
+
+---
+
+## 📋 Feature Implementation Checklist
+
+### 1. Design Phase
+
+- [ ] Define the public API (method signatures)
+- [ ] Update `Repository` interface in contracts
+- [ ] Consider backwards compatibility
+- [ ] Document expected behavior
+
+### 2. Implementation Phase
+
+- [ ] Implement in `MongoAdapter`
+- [ ] Implement in `PostgresAdapter`
+- [ ] Add to `DatabaseService` if needed
+- [ ] Handle edge cases
+
+### 3. Testing Phase
+
+- [ ] Unit tests for MongoDB implementation
+- [ ] Unit tests for PostgreSQL implementation
+- [ ] Integration tests if applicable
+- [ ] Edge case tests
+
+### 4. Documentation Phase
+
+- [ ] Update README with usage examples
+- [ ] Update CHANGELOG
+- [ ] Add JSDoc comments
+- [ ] Update type exports in index.ts
+
+---
+
+## 🏗️ Adding a New Repository Method
+
+### Step 1: Define the Interface
+
+```typescript
+// src/contracts/database.contracts.ts
+export interface Repository<T> {
+  // ... existing methods
+
+  /**
+   * New method description
+   * @param param1 - Description
+   * @returns Description of return value
+   */
+  newMethod(param1: Type1): Promise<ReturnType>;
+}
+```
+
+### Step 2: Implement in MongoAdapter
+
+```typescript
+// src/adapters/mongo.adapter.ts
+class MongoRepository<T> implements Repository<T> {
+  // ... existing methods
+
+  async newMethod(param1: Type1): Promise<ReturnType> {
+    // MongoDB-specific implementation
+    return this.model.someMongooseMethod(param1).lean().exec();
+  }
+}
+```
+
+### Step 3: Implement in PostgresAdapter
+
+```typescript
+// src/adapters/postgres.adapter.ts
+class PostgresRepository<T> implements Repository<T> {
+  // ... existing methods
+
+  async newMethod(param1: Type1): Promise<ReturnType> {
+    // PostgreSQL-specific implementation using Knex
+    return this.knex(this.table).someKnexMethod(param1);
+  }
+}
+```
+
+### Step 4: Add Tests
+
+```typescript
+// src/adapters/mongo.adapter.spec.ts
+describe("newMethod", () => {
+  it("should perform expected behavior", async () => {
+    // Test implementation
+  });
+
+  it("should handle edge cases", async () => {
+    // Edge case tests
+  });
+});
+```
+
+### Step 5: Export Types
+
+```typescript
+// src/index.ts
+export {
+  // ... existing exports
+  NewReturnType, // If you added new types
+} from "./contracts/database.contracts";
+```
+
+---
+
+## 🔧 Adding a New Configuration Option
+
+### Step 1: Add to Config Interface
+
+```typescript
+// src/contracts/database.contracts.ts
+export interface RepositoryOptions<T> {
+  // ... existing options
+
+  /**
+   * Description of new option
+   * @default defaultValue
+   */
+  newOption?: boolean;
+}
+```
+
+### Step 2: Handle in Adapter
+
+```typescript
+// src/adapters/mongo.adapter.ts
+createRepository<T>(options: RepositoryOptions<T>): Repository<T> {
+  const newOption = options.newOption ?? false; // Default value
+
+  return {
+    // Use newOption in method implementations
+    async create(data) {
+      if (newOption) {
+        // Special behavior
+      }
+      // Normal behavior
+    },
+  };
+}
+```
+
+### Step 3: Document in README
+
+```markdown
+### New Option
+
+Enable the new feature:
+
+\`\`\`typescript
+const repo = db.createMongoRepository({
+model: UserModel,
+newOption: true, // Enable the feature
+});
+\`\`\`
+```
+
+---
+
+## 🪝 Adding a New Hook
+
+### Step 1: Add to Hooks Interface
+
+```typescript
+// src/contracts/database.contracts.ts
+export interface RepositoryHooks<T> {
+  // ... existing hooks
+
+  /**
+   * Called before/after the action
+   */
+  beforeNewAction?(context: HookContext<T>): Partial<T> | Promise<Partial<T>>;
+  afterNewAction?(result: ResultType): void | Promise<void>;
+}
+```
+
+### Step 2: Implement Hook Calls
+
+```typescript
+// In both adapters
+async newAction(params): Promise<Result> {
+  // Call before hook
+  let data = params;
+  if (this.hooks?.beforeNewAction) {
+    data = await this.hooks.beforeNewAction({ data, repository: this });
+  }
+
+  // Perform action
+  const result = await this.performAction(data);
+
+  // Call after hook
+  if (this.hooks?.afterNewAction) {
+    await this.hooks.afterNewAction(result);
+  }
+
+  return result;
+}
+```
+
+---
+
+## 🛡️ Adding Query Operators
+
+### MongoDB (Usually Native)
+
+MongoDB operators are typically passed through directly:
+
+```typescript
+// No changes needed - Mongoose handles it
+{
+  field: {
+    $newOperator: value;
+  }
+}
+```
+
+### PostgreSQL (Requires Translation)
+
+```typescript
+// src/adapters/postgres.adapter.ts
+private applyFilter(query: Knex.QueryBuilder, filter: Filter): Knex.QueryBuilder {
+  for (const [key, value] of Object.entries(filter)) {
+    if (typeof value === 'object' && value !== null) {
+      // Handle operators
+      if ('newOperator' in value) {
+        query = query.whereRaw('?? NEW_SQL_OP ?', [key, value.newOperator]);
+      }
+      // ... existing operators
+    }
+  }
+  return query;
+}
+```
+
+---
+
+## 📦 Adding a New Utility Function
+
+### Step 1: Create/Update Utility File
+
+```typescript
+// src/utils/new.utils.ts or existing file
+
+/**
+ * Description of function
+ * @param input - Input description
+ * @returns Output description
+ * @example
+ * const result = newUtility('input');
+ * // result: 'output'
+ */
+export function newUtility(input: string): string {
+  // Implementation
+  return processed;
+}
+```
+
+### Step 2: Export from Index
+
+```typescript
+// src/index.ts
+export { newUtility } from "./utils/new.utils";
+```
+
+### Step 3: Add Tests
+
+```typescript
+// src/utils/new.utils.spec.ts
+describe("newUtility", () => {
+  it("should transform input correctly", () => {
+    expect(newUtility("input")).toBe("expected");
+  });
+
+  it("should handle edge cases", () => {
+    expect(newUtility("")).toBe("");
+    expect(newUtility(null as any)).toBeNull();
+  });
+});
+```
+
+---
+
+## ⚠️ Feature Guidelines
+
+### DO ✅
+
+- **Keep both adapters in sync** - If MongoDB has it, PostgreSQL needs it
+- **Maintain backwards compatibility** - Don't break existing APIs
+- **Use optional parameters** - New options should have defaults
+- **Write comprehensive tests** - Cover happy path and edge cases
+- **Document everything** - JSDoc, README, CHANGELOG
+
+### DON'T ❌
+
+- **Add database-specific features** - Must work on both adapters
+- **Change existing method signatures** - Add new methods instead
+- **Add required new parameters** - Use optional with defaults
+- **Skip tests** - Untested features will break
+- **Forget exports** - Check index.ts
+
+---
+
+## 🔄 Deprecation Process
+
+When replacing a feature:
+
+```typescript
+/**
+ * @deprecated Use `newMethod` instead. Will be removed in v2.0.0
+ */
+oldMethod(): Promise<Result> {
+  console.warn('oldMethod is deprecated, use newMethod instead');
+  return this.newMethod();
+}
+```
+
+1. Mark as `@deprecated` with migration path
+2. Log deprecation warning
+3. Keep working for at least one minor version
+4. Document in CHANGELOG
+5. Remove in next major version
+
+---
+
+## 📝 Example: Adding `aggregate()` Method
+
+```typescript
+// 1. Interface
+interface Repository<T> {
+  aggregate<R>(pipeline: AggregationStage[]): Promise<R[]>;
+}
+
+// 2. MongoDB (native support)
+async aggregate<R>(pipeline: AggregationStage[]): Promise<R[]> {
+  return this.model.aggregate(pipeline).exec();
+}
+
+// 3. PostgreSQL (raw SQL)
+async aggregate<R>(pipeline: AggregationStage[]): Promise<R[]> {
+  // Convert pipeline to SQL
+  const sql = this.pipelineToSql(pipeline);
+  return this.knex.raw(sql);
+}
+
+// 4. Tests
+describe('aggregate', () => {
+  it('should execute aggregation pipeline', async () => {
+    const result = await repo.aggregate([
+      { $match: { status: 'active' } },
+      { $group: { _id: '$category', count: { $sum: 1 } } },
+    ]);
+    expect(result).toHaveLength(3);
+  });
+});
+
+// 5. Export (if new types)
+export { AggregationStage } from './contracts/database.contracts';
+
+// 6. CHANGELOG
+- Added `aggregate()` method for custom aggregation pipelines
+```
+
+---
+
+_Last updated: February 2026_
diff --git a/.github/instructions/general.instructions.md b/.github/instructions/general.instructions.md
new file mode 100644
index 0000000..7e9a8af
--- /dev/null
+++ b/.github/instructions/general.instructions.md
@@ -0,0 +1,503 @@
+# GitHub Copilot Instructions for DatabaseKit
+
+This document provides guidelines for AI assistants (GitHub Copilot, Claude, etc.)
+when working on the DatabaseKit codebase.
+
+---
+
+## 📦 Module Overview
+
+**DatabaseKit** is a NestJS-friendly, OOP-style database library providing a unified
+repository API for MongoDB and PostgreSQL.
+
+### Key Characteristics
+
+- **Type:** NestJS Module (reusable library)
+- **Purpose:** Provide consistent CRUD operations across databases
+- **Pattern:** Repository pattern with adapter abstraction
+- **Target:** NestJS applications needing database abstraction
+
+---
+
+## 🏗️ Architecture
+
+### 4-Layer Clean Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    PUBLIC API (index.ts)                     │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
+│  │   Services   │──│   Adapters   │──│   Contracts  │       │
+│  └──────────────┘  └──────────────┘  └──────────────┘       │
+│         │                │                   │               │
+│         ▼                ▼                   ▼               │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
+│  │   Filters    │  │   Middleware │  │    Utils     │       │
+│  └──────────────┘  └──────────────┘  └──────────────┘       │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Layer Responsibilities
+
+| Layer          | Directory         | Responsibility                    |
+| -------------- | ----------------- | --------------------------------- |
+| **Services**   | `src/services/`   | Business logic, orchestration     |
+| **Adapters**   | `src/adapters/`   | Database-specific implementations |
+| **Contracts**  | `src/contracts/`  | TypeScript interfaces, types      |
+| **Filters**    | `src/filters/`    | Exception handling                |
+| **Middleware** | `src/middleware/` | Decorators, guards                |
+| **Utils**      | `src/utils/`      | Helper functions                  |
+| **Config**     | `src/config/`     | Constants, configuration helpers  |
+
+---
+
+## 📁 File Structure
+
+```
+src/
+├── index.ts                           # PUBLIC API - exports only
+├── database-kit.module.ts             # NestJS module definition
+│
+├── adapters/                          # Database-specific implementations
+│   ├── mongo.adapter.ts               # MongoDB via Mongoose
+│   └── postgres.adapter.ts            # PostgreSQL via Knex
+│
+├── config/                            # Configuration
+│   ├── database.config.ts             # Config helpers
+│   └── database.constants.ts          # Tokens, constants
+│
+├── contracts/                         # TypeScript contracts
+│   └── database.contracts.ts          # All interfaces & types
+│
+├── filters/                           # Exception filters
+│   └── database-exception.filter.ts   # Global error handler
+│
+├── middleware/                        # Decorators
+│   └── database.decorators.ts         # @InjectDatabase()
+│
+├── services/                          # Business logic
+│   ├── database.service.ts            # Main facade service
+│   └── logger.service.ts              # Logging service
+│
+└── utils/                             # Utility functions
+    ├── pagination.utils.ts            # Pagination helpers
+    └── validation.utils.ts            # Validation helpers
+```
+
+---
+
+## 📝 Naming Conventions
+
+### Files
+
+- **Pattern:** `kebab-case.suffix.ts`
+- **Suffixes:** `.adapter.ts`, `.service.ts`, `.filter.ts`, `.contracts.ts`, `.utils.ts`
+
+| Type       | Example                        |
+| ---------- | ------------------------------ |
+| Adapter    | `mongo.adapter.ts`             |
+| Service    | `database.service.ts`          |
+| Filter     | `database-exception.filter.ts` |
+| Contracts  | `database.contracts.ts`        |
+| Utils      | `pagination.utils.ts`          |
+| Decorators | `database.decorators.ts`       |
+| Module     | `database-kit.module.ts`       |
+
+### Classes, Interfaces, Types
+
+- **Classes:** `PascalCase` → `MongoAdapter`, `DatabaseService`
+- **Interfaces:** `PascalCase` → `Repository`, `PageOptions`
+- **Types:** `PascalCase` → `DatabaseType`, `PageResult`
+
+### Functions & Methods
+
+- **Functions:** `camelCase` → `createRepository`, `findById`
+- **Async functions:** same, but return `Promise<T>`
+
+### Constants
+
+- **Pattern:** `UPPER_SNAKE_CASE`
+- **Examples:** `DATABASE_TOKEN`, `DEFAULT_PAGE_SIZE`, `ENV_KEYS`
+
+---
+
+## ✅ Code Patterns to Follow
+
+### 1. Dependency Injection
+
+```typescript
+// ✅ Constructor injection
+@Injectable()
+export class DatabaseService {
+  constructor(
+    private readonly config: DatabaseConfig,
+  ) {}
+}
+
+// ✅ @InjectModel for Mongoose
+constructor(@InjectModel(User.name) private model: Model<User>) {}
+
+// ✅ Custom injection tokens
+constructor(@Inject(DATABASE_TOKEN) private db: DatabaseService) {}
+```
+
+### 2. Error Handling
+
+```typescript
+// ✅ Use specific NestJS exceptions
+throw new NotFoundException("User not found");
+throw new BadRequestException("Invalid input");
+throw new ConflictException("Email already exists");
+throw new InternalServerErrorException("Database error");
+
+// ✅ Log errors with context
+try {
+  await this.operation();
+} catch (error) {
+  this.logger.error("Operation failed", error);
+  throw error;
+}
+
+// ❌ Never swallow errors silently
+try {
+  await this.operation();
+} catch (e) {
+  // BAD - silent failure
+}
+```
+
+### 3. Configuration
+
+```typescript
+// ✅ Environment-driven configuration
+const uri = process.env.MONGO_URI;
+if (!uri) {
+  throw new Error("MONGO_URI not configured");
+}
+
+// ❌ Never hardcode values
+const uri = "mongodb://localhost:27017/mydb";
+```
+
+### 4. Type Safety
+
+```typescript
+// ✅ Explicit return types
+async findById(id: string): Promise<User | null> {
+  return this.model.findById(id).lean().exec();
+}
+
+// ✅ Use generics for flexibility
+createRepository<T>(options: RepositoryOptions<T>): Repository<T> {
+  // ...
+}
+
+// ✅ Use unknown over any
+function parseInput(data: unknown): ParsedData {
+  // validate and parse
+}
+
+// ❌ Avoid any
+function parseInput(data: any): any {
+  return data;
+}
+```
+
+### 5. Repository Pattern
+
+```typescript
+// ✅ Repository returns simple promises
+interface Repository<T> {
+  create(data: Partial<T>): Promise<T>;
+  findById(id: string): Promise<T | null>;
+  findAll(filter?: Filter): Promise<T[]>;
+  // ...
+}
+
+// ✅ Repository has no business logic
+// ❌ Repository should NOT validate, transform, or apply business rules
+```
+
+### 6. Service Pattern
+
+```typescript
+// ✅ Services orchestrate and apply business logic
+@Injectable()
+export class UserService {
+  constructor(
+    private readonly users: UserRepository,
+    private readonly logger: LoggerService,
+  ) {}
+
+  async getUser(id: string): Promise<User> {
+    const user = await this.users.findById(id);
+    if (!user) {
+      throw new NotFoundException("User not found");
+    }
+    return user;
+  }
+}
+```
+
+---
+
+## 🚫 Anti-Patterns to Avoid
+
+### 1. Business Logic in Adapters
+
+```typescript
+// ❌ BAD - Adapter doing business logic
+class MongoAdapter {
+  async createUser(data: CreateUserDto) {
+    if (await this.exists({ email: data.email })) {
+      throw new ConflictException("Email exists"); // Business logic!
+    }
+    return this.model.create(data);
+  }
+}
+
+// ✅ GOOD - Keep adapter simple
+class MongoAdapter {
+  createRepository<T>(opts: Options): Repository<T> {
+    // Only data access, no business logic
+  }
+}
+```
+
+### 2. Hardcoded Configuration
+
+```typescript
+// ❌ BAD
+const poolSize = 10;
+const timeout = 5000;
+
+// ✅ GOOD
+const poolSize = parseInt(process.env.POOL_SIZE || "10", 10);
+const timeout = parseInt(process.env.TIMEOUT || "5000", 10);
+```
+
+### 3. Leaking Internal Types
+
+```typescript
+// ❌ BAD - Exporting internal implementation
+export { MongoAdapter } from "./adapters/mongo.adapter";
+
+// ✅ GOOD - Only export public API
+export { DatabaseService } from "./services/database.service";
+export { Repository } from "./contracts/database.contracts";
+```
+
+### 4. Direct Model Access in Services
+
+```typescript
+// ❌ BAD - Service accessing model directly
+@Injectable()
+export class UserService {
+  constructor(@InjectModel(User.name) private model: Model<User>) {}
+}
+
+// ✅ GOOD - Service uses repository
+@Injectable()
+export class UserService {
+  constructor(private readonly users: UserRepository) {}
+}
+```
+
+---
+
+## 🧪 Testing Requirements
+
+### Coverage Target
+
+- **Minimum:** 80% code coverage
+- **Critical paths:** 100% coverage
+
+### Test Location
+
+- Place tests next to source: `*.spec.ts`
+- Example: `database.service.spec.ts`
+
+### Test Structure
+
+```typescript
+describe("DatabaseService", () => {
+  let service: DatabaseService;
+  let mockAdapter: jest.Mocked<MongoAdapter>;
+
+  beforeEach(async () => {
+    mockAdapter = {
+      connect: jest.fn(),
+      createRepository: jest.fn(),
+    };
+
+    const module = await Test.createTestingModule({
+      providers: [
+        DatabaseService,
+        { provide: MongoAdapter, useValue: mockAdapter },
+      ],
+    }).compile();
+
+    service = module.get(DatabaseService);
+  });
+
+  describe("connect", () => {
+    it("should connect to database", async () => {
+      await service.connect();
+      expect(mockAdapter.connect).toHaveBeenCalled();
+    });
+  });
+});
+```
+
+---
+
+## 📤 Export Rules
+
+### ✅ DO Export
+
+```typescript
+// index.ts - Only these should be exported
+
+// Module (primary)
+export { DatabaseKitModule } from "./database-kit.module";
+
+// Services (for direct injection)
+export { DatabaseService } from "./services/database.service";
+
+// Decorators (for DI)
+export { InjectDatabase } from "./middleware/database.decorators";
+
+// Filters (for app-wide use)
+export { DatabaseExceptionFilter } from "./filters/database-exception.filter";
+
+// Types (for consumers)
+export {
+  Repository,
+  PageResult,
+  DatabaseConfig,
+} from "./contracts/database.contracts";
+
+// Utilities (for convenience)
+export { isValidMongoId } from "./utils/validation.utils";
+```
+
+### ❌ DON'T Export
+
+```typescript
+// These should NOT be in index.ts
+export { MongoAdapter } from "./adapters/mongo.adapter"; // Internal
+export { PostgresAdapter } from "./adapters/postgres.adapter"; // Internal
+```
+
+---
+
+## 🔒 Security Practices
+
+### 1. Parameterized Queries
+
+All queries MUST use parameterization. Never interpolate user input.
+
+### 2. Column Whitelisting
+
+PostgreSQL repositories should whitelist allowed columns.
+
+### 3. Error Sanitization
+
+Never expose internal database errors to clients.
+
+### 4. Credential Management
+
+Never log or expose connection strings.
+
+---
+
+## 🔄 Version Management
+
+### Semantic Versioning
+
+| Type  | Version | When                                |
+| ----- | ------- | ----------------------------------- |
+| Patch | x.x.X   | Bug fixes                           |
+| Minor | x.X.0   | New features (backwards compatible) |
+| Major | X.0.0   | Breaking changes                    |
+
+### Breaking Changes
+
+Before making breaking changes:
+
+1. Discuss in GitHub issue
+2. Document migration path
+3. Update CHANGELOG
+4. Consider deprecation period
+
+---
+
+## 📋 Release Checklist
+
+Before releasing a new version:
+
+- [ ] All tests pass (`npm test`)
+- [ ] Coverage >= 80% (`npm run test:cov`)
+- [ ] Linting passes (`npm run lint`)
+- [ ] Build succeeds (`npm run build`)
+- [ ] CHANGELOG updated
+- [ ] README updated if needed
+- [ ] Version bumped in package.json
+- [ ] No console.log statements (use Logger)
+- [ ] No hardcoded values
+- [ ] Dependencies audited (`npm audit`)
+
+---
+
+## 🛠️ Development Commands
+
+```bash
+# Build
+npm run build
+
+# Watch mode
+npm run build:watch
+
+# Test
+npm test
+npm run test:cov
+npm run test:watch
+
+# Lint
+npm run lint
+npm run lint:fix
+
+# Clean
+npm run clean
+```
+
+---
+
+## 💡 AI Assistant Guidelines
+
+When generating code for this project:
+
+1. **Follow naming conventions** - kebab-case files, PascalCase classes
+2. **Use dependency injection** - Constructor injection, NestJS patterns
+3. **Handle errors properly** - Use NestJS exceptions, always log
+4. **Write type-safe code** - Explicit return types, no `any`
+5. **Include JSDoc comments** - Document all public APIs
+6. **Write tests** - Include spec files for new code
+7. **Keep layers separate** - Don't mix responsibilities
+8. **Use environment variables** - No hardcoded config
+
+---
+
+## 📚 Reference Documentation
+
+- [NestJS Documentation](https://docs.nestjs.com/)
+- [Mongoose Documentation](https://mongoosejs.com/docs/)
+- [Knex.js Documentation](https://knexjs.org/)
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/)
+
+---
+
+_Last updated: February 2026_
diff --git a/.github/instructions/testing.instructions.md b/.github/instructions/testing.instructions.md
new file mode 100644
index 0000000..83d3437
--- /dev/null
+++ b/.github/instructions/testing.instructions.md
@@ -0,0 +1,439 @@
+# Testing Instructions for DatabaseKit
+
+Comprehensive testing guidelines for the DatabaseKit codebase.
+
+---
+
+## 🎯 Testing Philosophy
+
+- **Test behavior, not implementation**
+- **Mock external dependencies, not internal logic**
+- **Every public API must have tests**
+- **Tests are documentation**
+
+---
+
+## 📊 Coverage Requirements
+
+| Category   | Minimum | Target |
+| ---------- | ------- | ------ |
+| Statements | 80%     | 90%+   |
+| Branches   | 75%     | 85%+   |
+| Functions  | 80%     | 90%+   |
+| Lines      | 80%     | 90%+   |
+
+**Critical paths (adapters, services) require 100% coverage.**
+
+---
+
+## 📁 Test File Organization
+
+```
+src/
+├── adapters/
+│   ├── mongo.adapter.ts
+│   ├── mongo.adapter.spec.ts      # ← Test next to source
+│   ├── postgres.adapter.ts
+│   └── postgres.adapter.spec.ts
+├── services/
+│   ├── database.service.ts
+│   └── database.service.spec.ts
+└── utils/
+    ├── pagination.utils.ts
+    └── pagination.utils.spec.ts
+```
+
+**Rule:** Every `.ts` file should have a corresponding `.spec.ts` file.
+
+---
+
+## 🧪 Test Structure
+
+### Standard Test Template
+
+```typescript
+import { Test, TestingModule } from "@nestjs/testing";
+
+describe("ClassName", () => {
+  let instance: ClassName;
+  let mockDependency: jest.Mocked<DependencyType>;
+
+  beforeEach(async () => {
+    // Create mocks
+    mockDependency = {
+      method: jest.fn(),
+    } as unknown as jest.Mocked<DependencyType>;
+
+    // Build test module
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        ClassName,
+        { provide: DependencyType, useValue: mockDependency },
+      ],
+    }).compile();
+
+    instance = module.get<ClassName>(ClassName);
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe("methodName", () => {
+    it("should do expected behavior", async () => {
+      // Arrange
+      mockDependency.method.mockResolvedValue(expectedData);
+
+      // Act
+      const result = await instance.methodName(input);
+
+      // Assert
+      expect(result).toEqual(expectedOutput);
+      expect(mockDependency.method).toHaveBeenCalledWith(expectedArgs);
+    });
+
+    it("should throw when condition fails", async () => {
+      // Arrange
+      mockDependency.method.mockRejectedValue(new Error("fail"));
+
+      // Act & Assert
+      await expect(instance.methodName(input)).rejects.toThrow("fail");
+    });
+  });
+});
+```
+
+---
+
+## 🎭 Mocking Patterns
+
+### Mock Repository
+
+```typescript
+const mockRepository = {
+  create: jest.fn(),
+  findById: jest.fn(),
+  findOne: jest.fn(),
+  findAll: jest.fn(),
+  findPage: jest.fn(),
+  updateById: jest.fn(),
+  deleteById: jest.fn(),
+  count: jest.fn(),
+  exists: jest.fn(),
+  insertMany: jest.fn(),
+  updateMany: jest.fn(),
+  deleteMany: jest.fn(),
+  upsert: jest.fn(),
+  distinct: jest.fn(),
+  select: jest.fn(),
+  softDelete: jest.fn(),
+  restore: jest.fn(),
+};
+```
+
+### Mock Mongoose Model
+
+```typescript
+const mockModel = {
+  create: jest.fn(),
+  findById: jest.fn().mockReturnThis(),
+  findOne: jest.fn().mockReturnThis(),
+  find: jest.fn().mockReturnThis(),
+  findByIdAndUpdate: jest.fn().mockReturnThis(),
+  findByIdAndDelete: jest.fn().mockReturnThis(),
+  countDocuments: jest.fn(),
+  distinct: jest.fn(),
+  lean: jest.fn().mockReturnThis(),
+  exec: jest.fn(),
+  skip: jest.fn().mockReturnThis(),
+  limit: jest.fn().mockReturnThis(),
+  sort: jest.fn().mockReturnThis(),
+  select: jest.fn().mockReturnThis(),
+  session: jest.fn().mockReturnThis(),
+};
+```
+
+### Mock Knex Instance
+
+```typescript
+const mockKnex = jest.fn().mockReturnValue({
+  insert: jest.fn().mockReturnThis(),
+  update: jest.fn().mockReturnThis(),
+  delete: jest.fn().mockReturnThis(),
+  select: jest.fn().mockReturnThis(),
+  where: jest.fn().mockReturnThis(),
+  whereIn: jest.fn().mockReturnThis(),
+  whereNull: jest.fn().mockReturnThis(),
+  whereNotNull: jest.fn().mockReturnThis(),
+  first: jest.fn(),
+  returning: jest.fn().mockReturnThis(),
+  count: jest.fn().mockReturnThis(),
+  distinct: jest.fn().mockReturnThis(),
+  orderBy: jest.fn().mockReturnThis(),
+  offset: jest.fn().mockReturnThis(),
+  limit: jest.fn().mockReturnThis(),
+});
+mockKnex.raw = jest.fn();
+mockKnex.transaction = jest.fn();
+mockKnex.destroy = jest.fn();
+```
+
+### Mock DatabaseService
+
+```typescript
+const mockDatabaseService = {
+  createMongoRepository: jest.fn().mockReturnValue(mockRepository),
+  createPostgresRepository: jest.fn().mockReturnValue(mockRepository),
+  getMongoAdapter: jest.fn(),
+  getPostgresAdapter: jest.fn(),
+};
+```
+
+---
+
+## ✅ What to Test
+
+### Repository Methods
+
+```typescript
+describe("Repository", () => {
+  describe("create", () => {
+    it("should create and return entity");
+    it("should set createdAt when timestamps enabled");
+    it("should call beforeCreate hook");
+    it("should call afterCreate hook");
+    it("should throw on duplicate key");
+  });
+
+  describe("findById", () => {
+    it("should return entity when found");
+    it("should return null when not found");
+    it("should exclude soft-deleted records");
+  });
+
+  describe("findPage", () => {
+    it("should return paginated results");
+    it("should apply default page and limit");
+    it("should apply sorting");
+    it("should apply filters");
+    it("should calculate total pages correctly");
+  });
+
+  // ... test all 20+ methods
+});
+```
+
+### Error Scenarios
+
+```typescript
+describe("Error Handling", () => {
+  it("should throw NotFoundException when entity not found");
+  it("should throw ConflictException on duplicate");
+  it("should throw BadRequestException on invalid input");
+  it("should handle database connection errors");
+  it("should rollback transaction on error");
+});
+```
+
+### Edge Cases
+
+```typescript
+describe("Edge Cases", () => {
+  it("should handle empty array for insertMany");
+  it("should handle empty filter for findAll");
+  it("should handle page 0 (treat as page 1)");
+  it("should handle negative limit");
+  it("should handle very large page numbers");
+  it("should handle special characters in filters");
+  it("should handle null values correctly");
+});
+```
+
+---
+
+## 🔄 Transaction Testing
+
+```typescript
+describe("Transactions", () => {
+  it("should commit on success", async () => {
+    const result = await adapter.withTransaction(async (ctx) => {
+      const repo = ctx.createRepository({ model });
+      return repo.create({ name: "test" });
+    });
+    expect(result).toBeDefined();
+  });
+
+  it("should rollback on error", async () => {
+    await expect(
+      adapter.withTransaction(async (ctx) => {
+        const repo = ctx.createRepository({ model });
+        await repo.create({ name: "test" });
+        throw new Error("Intentional failure");
+      }),
+    ).rejects.toThrow("Intentional failure");
+
+    // Verify rollback - entity should not exist
+    const count = await adapter.createRepository({ model }).count({});
+    expect(count).toBe(0);
+  });
+
+  it("should retry on transient errors", async () => {
+    // Test retry logic
+  });
+});
+```
+
+---
+
+## 🪝 Hook Testing
+
+```typescript
+describe("Hooks", () => {
+  it("should call beforeCreate and modify data", async () => {
+    const beforeCreate = jest.fn((ctx) => ({
+      ...ctx.data,
+      normalized: true,
+    }));
+
+    const repo = adapter.createRepository({
+      model,
+      hooks: { beforeCreate },
+    });
+
+    const result = await repo.create({ name: "test" });
+
+    expect(beforeCreate).toHaveBeenCalled();
+    expect(result.normalized).toBe(true);
+  });
+
+  it("should call afterCreate with created entity", async () => {
+    const afterCreate = jest.fn();
+    const repo = adapter.createRepository({
+      model,
+      hooks: { afterCreate },
+    });
+
+    await repo.create({ name: "test" });
+
+    expect(afterCreate).toHaveBeenCalledWith(
+      expect.objectContaining({ name: "test" }),
+    );
+  });
+
+  // Test all 6 hooks...
+});
+```
+
+---
+
+## 🏃 Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run with coverage
+npm run test:cov
+
+# Run specific file
+npm test -- mongo.adapter.spec.ts
+
+# Run specific test
+npm test -- -t "should create and return entity"
+
+# Watch mode
+npm run test:watch
+
+# Run only changed tests
+npm test -- --onlyChanged
+
+# Verbose output
+npm test -- --verbose
+```
+
+---
+
+## 📋 Test Naming Convention
+
+```typescript
+// Pattern: should [expected behavior] when [condition]
+it("should return null when entity not found");
+it("should throw NotFoundException when id is invalid");
+it("should set updatedAt when updating entity");
+it("should exclude soft-deleted records when softDelete enabled");
+```
+
+---
+
+## ⚠️ Common Mistakes
+
+### ❌ Don't Test Implementation Details
+
+```typescript
+// BAD - Testing internal method calls
+expect(model.lean).toHaveBeenCalled();
+
+// GOOD - Testing behavior
+expect(result).toEqual(expectedEntity);
+```
+
+### ❌ Don't Share State Between Tests
+
+```typescript
+// BAD - Shared mutable state
+let counter = 0;
+it("test 1", () => {
+  counter++;
+});
+it("test 2", () => {
+  expect(counter).toBe(1);
+}); // Fragile!
+
+// GOOD - Independent tests
+beforeEach(() => {
+  /* reset state */
+});
+```
+
+### ❌ Don't Forget Async/Await
+
+```typescript
+// BAD - Missing await
+it("should create", () => {
+  repo.create({ name: "test" }); // Promise not awaited!
+  expect(mock).toHaveBeenCalled(); // May fail randomly
+});
+
+// GOOD
+it("should create", async () => {
+  await repo.create({ name: "test" });
+  expect(mock).toHaveBeenCalled();
+});
+```
+
+---
+
+## 🔧 Jest Configuration
+
+```javascript
+// jest.config.js
+module.exports = {
+  preset: "ts-jest",
+  testEnvironment: "node",
+  roots: ["<rootDir>/src"],
+  testMatch: ["**/*.spec.ts"],
+  collectCoverageFrom: ["src/**/*.ts", "!src/**/*.spec.ts", "!src/index.ts"],
+  coverageThreshold: {
+    global: {
+      branches: 75,
+      functions: 80,
+      lines: 80,
+      statements: 80,
+    },
+  },
+};
+```
+
+---
+
+_Last updated: February 2026_
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9add896..b6adbbd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
 ## [Unreleased]
 
 ### Planned
@@ -14,16 +19,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - MySQL adapter support
 - Redis caching layer
 - Query builder interface
-- Soft delete built-in support
+- Aggregation pipeline support
 - Audit logging
 
 ---
 
-## [1.0.0] - 2026-01-31
+## [1.0.0] - 2026-02-01
 
-### 🎉 Initial Release
+### 🎉 Production-Ready Release
 
-Complete refactoring following CISCODE AuthKit patterns and best practices.
+Complete refactoring following CISCODE AuthKit patterns and best practices, with advanced features for production use.
 
 ### Added
 
@@ -32,12 +37,53 @@ Complete refactoring following CISCODE AuthKit patterns and best practices.
 - **Unified Repository API** - Same interface for MongoDB and PostgreSQL
   - `create(data)` - Create new records
   - `findById(id)` - Find by primary key
+  - `findOne(filter)` - Find single record by filter _(NEW)_
   - `findAll(filter)` - Find all matching records
   - `findPage(options)` - Paginated queries
   - `updateById(id, data)` - Update by primary key
   - `deleteById(id)` - Delete by primary key
   - `count(filter)` - Count matching records
   - `exists(filter)` - Check if records exist
+  - `upsert(filter, data)` - Update or insert _(NEW)_
+  - `distinct(field, filter)` - Get distinct values _(NEW)_
+  - `select(filter, fields)` - Projection/field selection _(NEW)_
+
+- **Transaction Support** - ACID transactions with session management
+  - `withTransaction(callback, options)` - Execute callback in transaction
+  - Configurable retry logic for transient errors
+  - Automatic session handling
+
+- **Bulk Operations** - Efficient batch processing
+  - `insertMany(data)` - Bulk insert
+  - `updateMany(filter, update)` - Bulk update
+  - `deleteMany(filter)` - Bulk delete
+
+- **Soft Delete** - Non-destructive deletion
+  - `softDelete(id)` - Mark as deleted
+  - `restore(id)` - Restore deleted record
+  - `findWithDeleted(filter)` - Include deleted records
+  - Configurable field name (default: `deletedAt`/`deleted_at`)
+
+- **Timestamps** - Automatic created/updated tracking
+  - `createdAt`/`created_at` field on create
+  - `updatedAt`/`updated_at` field on update
+  - Configurable field names
+
+- **Health Checks** - Database monitoring
+  - `healthCheck()` - Connection status, response time, pool info
+
+- **Connection Pool Configuration** - Performance tuning _(NEW)_
+  - `PoolConfig` interface with min, max, idle timeout, acquire timeout
+  - MongoDB: maxPoolSize, minPoolSize, serverSelectionTimeoutMS, socketTimeoutMS
+  - PostgreSQL: min, max, idleTimeoutMillis, acquireTimeoutMillis
+
+- **Repository Hooks** - Lifecycle event callbacks _(NEW)_
+  - `beforeCreate(context)` - Called before insert, can modify data
+  - `afterCreate(entity)` - Called after insert
+  - `beforeUpdate(context)` - Called before update, can modify data
+  - `afterUpdate(entity)` - Called after update
+  - `beforeDelete(id)` - Called before delete
+  - `afterDelete(success)` - Called after delete
 
 #### NestJS Integration
 
diff --git a/CHANGELOG_NEW.md b/CHANGELOG_NEW.md
new file mode 100644
index 0000000..e69de29
diff --git a/CODE_OF_CONDUCT b/CODE_OF_CONDUCT
index c482d82..7110a79 100644
--- a/CODE_OF_CONDUCT
+++ b/CODE_OF_CONDUCT
@@ -45,7 +45,7 @@ It also applies when individuals are representing the project in public spaces.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainers at:
 
-**info@ciscode.com**
+**info@ciscod.com**
 
 All complaints will be reviewed and investigated promptly and fairly.
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6a0e6b5..dd63def 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -410,7 +410,7 @@ Contributors are recognized in:
 ## 📞 Questions?
 
 - 💬 [GitHub Discussions](https://github.com/CISCODE-MA/DatabaseKit/discussions)
-- 📧 Email: info@ciscode.com
+- 📧 Email: info@ciscod.com
 
 ---
 
diff --git a/CONTRIBUTING_NEW.md b/CONTRIBUTING_NEW.md
new file mode 100644
index 0000000..e69de29
diff --git a/README.md b/README.md
index df47c0e..2af7635 100644
--- a/README.md
+++ b/README.md
@@ -5,18 +5,82 @@ A NestJS-friendly, OOP-style database library providing a unified repository API
 [![npm version](https://img.shields.io/npm/v/@ciscode/database-kit.svg)](https://www.npmjs.com/package/@ciscode/database-kit)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js Version](https://img.shields.io/node/v/@ciscode/database-kit.svg)](https://nodejs.org)
+[![Tests](https://img.shields.io/badge/tests-133%20passed-brightgreen.svg)]()
+
+---
+
+## 🎯 How It Works
+
+**DatabaseKit** provides a unified abstraction layer over MongoDB and PostgreSQL, allowing you to write database operations once and run them on either database system. Here's how the architecture works:
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                        Your NestJS Application                       │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│   ┌─────────────┐    inject    ┌─────────────────────────────────┐  │
+│   │   Service   │ ──────────── │  DatabaseService                │  │
+│   └─────────────┘              │  ├── createMongoRepository()    │  │
+│                                │  └── createPostgresRepository() │  │
+│                                └───────────────┬─────────────────┘  │
+│                                                │                    │
+│                          ┌─────────────────────┴─────────────────┐  │
+│                          │                                       │  │
+│                ┌─────────▼─────────┐               ┌─────────────▼─┐│
+│                │   MongoAdapter    │               │ PostgresAdapter│
+│                │   (Mongoose)      │               │   (Knex.js)   ││
+│                └─────────┬─────────┘               └───────┬───────┘│
+│                          │                                 │        │
+└──────────────────────────┼─────────────────────────────────┼────────┘
+                           │                                 │
+                   ┌───────▼───────┐                 ┌───────▼───────┐
+                   │   MongoDB     │                 │  PostgreSQL   │
+                   └───────────────┘                 └───────────────┘
+```
+
+### The Repository Pattern
+
+Every repository (MongoDB or PostgreSQL) implements the **same interface**:
+
+```typescript
+const user = await repo.create({ name: "John" }); // Works on both!
+const found = await repo.findById("123"); // Works on both!
+const page = await repo.findPage({ page: 1 }); // Works on both!
+```
+
+This means you can:
+
+- **Switch databases** without changing your service code
+- **Test with MongoDB** and deploy with PostgreSQL (or vice versa)
+- **Use the same mental model** regardless of database
 
 ---
 
 ## ✨ Features
 
+### Core Features
+
 - ✅ **Unified Repository API** - Same interface for MongoDB and PostgreSQL
 - ✅ **NestJS Integration** - First-class support with `DatabaseKitModule`
 - ✅ **TypeScript First** - Full type safety and IntelliSense
 - ✅ **Pagination Built-in** - Consistent pagination across databases
-- ✅ **Environment-Driven** - Zero hardcoding, all config from env vars
-- ✅ **Exception Handling** - Global exception filter for database errors
-- ✅ **Clean Architecture** - Follows CISCODE standards and best practices
+
+### Advanced Features
+
+- ✅ **Transactions** - ACID transactions with automatic retry logic
+- ✅ **Bulk Operations** - `insertMany`, `updateMany`, `deleteMany`
+- ✅ **Soft Delete** - Non-destructive deletion with restore capability
+- ✅ **Timestamps** - Automatic `createdAt`/`updatedAt` tracking
+- ✅ **Health Checks** - Database monitoring and connection status
+- ✅ **Connection Pool Config** - Fine-tune pool settings for performance
+- ✅ **Event Hooks** - Lifecycle callbacks (beforeCreate, afterUpdate, etc.)
+
+### Query Features
+
+- ✅ **findOne** - Find single record by filter
+- ✅ **upsert** - Update or insert in one operation
+- ✅ **distinct** - Get unique values for a field
+- ✅ **select** - Field projection (return only specific fields)
 
 ---
 
@@ -28,22 +92,18 @@ npm install @ciscode/database-kit
 
 ### Peer Dependencies
 
-Make sure you have NestJS installed:
-
 ```bash
 npm install @nestjs/common @nestjs/core reflect-metadata
 ```
 
 ### Database Drivers
 
-Install the driver for your database:
-
 ```bash
 # For MongoDB
 npm install mongoose
 
 # For PostgreSQL
-npm install pg
+npm install pg knex
 ```
 
 ---
@@ -70,7 +130,7 @@ import { DatabaseKitModule } from "@ciscode/database-kit";
 export class AppModule {}
 ```
 
-### 2. Inject and Use
+### 2. Create a Repository and Use It
 
 ```typescript
 // users.service.ts
@@ -86,6 +146,7 @@ interface User {
   _id: string;
   name: string;
   email: string;
+  createdAt: Date;
 }
 
 @Injectable()
@@ -93,172 +154,360 @@ export class UsersService {
   private readonly usersRepo: Repository<User>;
 
   constructor(@InjectDatabase() private readonly db: DatabaseService) {
-    this.usersRepo = db.createMongoRepository<User>({ model: UserModel });
+    // For MongoDB
+    this.usersRepo = db.createMongoRepository<User>({
+      model: UserModel,
+      timestamps: true, // Auto createdAt/updatedAt
+      softDelete: true, // Enable soft delete
+      hooks: {
+        // Lifecycle hooks
+        beforeCreate: (ctx) => {
+          console.log("Creating user:", ctx.data);
+          return ctx.data; // Can modify data
+        },
+        afterCreate: (user) => {
+          console.log("User created:", user._id);
+        },
+      },
+    });
   }
 
+  // CREATE
   async createUser(data: Partial<User>): Promise<User> {
     return this.usersRepo.create(data);
   }
 
+  // READ
   async getUser(id: string): Promise<User | null> {
     return this.usersRepo.findById(id);
   }
 
+  async getUserByEmail(email: string): Promise<User | null> {
+    return this.usersRepo.findOne({ email });
+  }
+
   async listUsers(page = 1, limit = 10) {
-    return this.usersRepo.findPage({ page, limit });
+    return this.usersRepo.findPage({
+      page,
+      limit,
+      sort: "-createdAt",
+    });
+  }
+
+  // UPDATE
+  async updateUser(id: string, data: Partial<User>): Promise<User | null> {
+    return this.usersRepo.updateById(id, data);
+  }
+
+  // UPSERT (update or create)
+  async upsertByEmail(email: string, data: Partial<User>): Promise<User> {
+    return this.usersRepo.upsert({ email }, data);
+  }
+
+  // DELETE (soft delete if enabled)
+  async deleteUser(id: string): Promise<boolean> {
+    return this.usersRepo.deleteById(id);
+  }
+
+  // RESTORE (only with soft delete)
+  async restoreUser(id: string): Promise<User | null> {
+    return this.usersRepo.restore!(id);
+  }
+
+  // BULK OPERATIONS
+  async createManyUsers(users: Partial<User>[]): Promise<User[]> {
+    return this.usersRepo.insertMany(users);
+  }
+
+  // DISTINCT VALUES
+  async getUniqueEmails(): Promise<string[]> {
+    return this.usersRepo.distinct("email");
+  }
+
+  // SELECT SPECIFIC FIELDS
+  async getUserNames(): Promise<Pick<User, "name" | "email">[]> {
+    return this.usersRepo.select({}, ["name", "email"]);
   }
 }
 ```
 
 ---
 
-## ⚙️ Configuration
+## 📖 Complete Repository API
 
-### Environment Variables
+```typescript
+interface Repository<T> {
+  // ─────────────────────────────────────────────────────────────
+  // CRUD Operations
+  // ─────────────────────────────────────────────────────────────
+  create(data: Partial<T>): Promise<T>;
+  findById(id: string | number): Promise<T | null>;
+  findOne(filter: Filter): Promise<T | null>;
+  findAll(filter?: Filter): Promise<T[]>;
+  findPage(options?: PageOptions): Promise<PageResult<T>>;
+  updateById(id: string | number, update: Partial<T>): Promise<T | null>;
+  deleteById(id: string | number): Promise<boolean>;
+  count(filter?: Filter): Promise<number>;
+  exists(filter?: Filter): Promise<boolean>;
+
+  // ─────────────────────────────────────────────────────────────
+  // Bulk Operations
+  // ─────────────────────────────────────────────────────────────
+  insertMany(data: Partial<T>[]): Promise<T[]>;
+  updateMany(filter: Filter, update: Partial<T>): Promise<number>;
+  deleteMany(filter: Filter): Promise<number>;
+
+  // ─────────────────────────────────────────────────────────────
+  // Advanced Queries
+  // ─────────────────────────────────────────────────────────────
+  upsert(filter: Filter, data: Partial<T>): Promise<T>;
+  distinct<K extends keyof T>(field: K, filter?: Filter): Promise<T[K][]>;
+  select<K extends keyof T>(filter: Filter, fields: K[]): Promise<Pick<T, K>[]>;
+
+  // ─────────────────────────────────────────────────────────────
+  // Soft Delete (when enabled)
+  // ─────────────────────────────────────────────────────────────
+  softDelete?(id: string | number): Promise<boolean>;
+  softDeleteMany?(filter: Filter): Promise<number>;
+  restore?(id: string | number): Promise<T | null>;
+  restoreMany?(filter: Filter): Promise<number>;
+  findWithDeleted?(filter?: Filter): Promise<T[]>;
+}
+```
+
+---
 
-| Variable                      | Description                              | Required       |
-| ----------------------------- | ---------------------------------------- | -------------- |
-| `DATABASE_TYPE`               | Database type (`mongo` or `postgres`)    | Yes            |
-| `MONGO_URI`                   | MongoDB connection string                | For MongoDB    |
-| `DATABASE_URL`                | PostgreSQL connection string             | For PostgreSQL |
-| `DATABASE_POOL_SIZE`          | Connection pool size (default: 10)       | No             |
-| `DATABASE_CONNECTION_TIMEOUT` | Connection timeout in ms (default: 5000) | No             |
+## ⚡ Advanced Features
 
-### Synchronous Configuration
+### Transactions
+
+Execute multiple operations atomically:
 
 ```typescript
-DatabaseKitModule.forRoot({
-  config: {
-    type: "postgres",
-    connectionString: "postgresql://user:pass@localhost:5432/mydb",
+// MongoDB Transaction
+const result = await db.getMongoAdapter().withTransaction(
+  async (ctx) => {
+    const userRepo = ctx.createRepository<User>({ model: UserModel });
+    const orderRepo = ctx.createRepository<Order>({ model: OrderModel });
+
+    const user = await userRepo.create({ name: "John" });
+    const order = await orderRepo.create({ userId: user._id, total: 99.99 });
+
+    return { user, order };
   },
-  autoConnect: true, // default: true
-});
+  {
+    maxRetries: 3, // Retry on transient errors
+    retryDelayMs: 100,
+  },
+);
+
+// PostgreSQL Transaction
+const result = await db.getPostgresAdapter().withTransaction(
+  async (ctx) => {
+    const userRepo = ctx.createRepository<User>({ table: "users" });
+    const orderRepo = ctx.createRepository<Order>({ table: "orders" });
+
+    const user = await userRepo.create({ name: "John" });
+    const order = await orderRepo.create({ user_id: user.id, total: 99.99 });
+
+    return { user, order };
+  },
+  {
+    isolationLevel: "serializable",
+  },
+);
 ```
 
-### Async Configuration (Recommended)
+### Event Hooks
+
+React to repository lifecycle events:
 
 ```typescript
-import { ConfigModule, ConfigService } from "@nestjs/config";
+const repo = db.createMongoRepository<User>({
+  model: UserModel,
+  hooks: {
+    // Before create - can modify data
+    beforeCreate: (context) => {
+      console.log("Creating:", context.data);
+      return {
+        ...context.data,
+        normalizedEmail: context.data.email?.toLowerCase(),
+      };
+    },
 
-DatabaseKitModule.forRootAsync({
-  imports: [ConfigModule],
-  useFactory: (config: ConfigService) => ({
-    config: {
-      type: config.get("DATABASE_TYPE") as "mongo" | "postgres",
-      connectionString: config.get("DATABASE_URL")!,
+    // After create - for side effects
+    afterCreate: (user) => {
+      sendWelcomeEmail(user.email);
     },
-  }),
-  inject: [ConfigService],
+
+    // Before update - can modify data
+    beforeUpdate: (context) => {
+      return { ...context.data, updatedBy: "system" };
+    },
+
+    // After update
+    afterUpdate: (user) => {
+      if (user) invalidateCache(user._id);
+    },
+
+    // Before delete - for validation
+    beforeDelete: (id) => {
+      console.log("Deleting user:", id);
+    },
+
+    // After delete
+    afterDelete: (success) => {
+      if (success) console.log("User deleted");
+    },
+  },
 });
 ```
 
-### Multiple Databases
+### Connection Pool Configuration
+
+Fine-tune database connection pooling:
 
 ```typescript
-@Module({
-  imports: [
-    // Primary database
-    DatabaseKitModule.forRoot({
-      config: { type: "mongo", connectionString: process.env.MONGO_URI! },
-    }),
-    // Analytics database
-    DatabaseKitModule.forFeature("ANALYTICS_DB", {
-      type: "postgres",
-      connectionString: process.env.ANALYTICS_DB_URL!,
-    }),
-  ],
-})
-export class AppModule {}
+// MongoDB
+DatabaseKitModule.forRoot({
+  config: {
+    type: "mongo",
+    connectionString: process.env.MONGO_URI!,
+    pool: {
+      min: 5,
+      max: 50,
+      idleTimeoutMs: 30000,
+      acquireTimeoutMs: 60000,
+    },
+    // MongoDB-specific
+    serverSelectionTimeoutMS: 5000,
+    socketTimeoutMS: 45000,
+  },
+});
 
-// Usage
-@Injectable()
-export class AnalyticsService {
-  constructor(
-    @InjectDatabaseByToken("ANALYTICS_DB")
-    private readonly analyticsDb: DatabaseService,
-  ) {}
-}
+// PostgreSQL
+DatabaseKitModule.forRoot({
+  config: {
+    type: "postgres",
+    connectionString: process.env.DATABASE_URL!,
+    pool: {
+      min: 2,
+      max: 20,
+      idleTimeoutMs: 30000,
+      acquireTimeoutMs: 60000,
+    },
+  },
+});
 ```
 
----
-
-## 📖 Repository API
+### Health Checks
 
-Both MongoDB and PostgreSQL repositories expose the same interface:
+Monitor database health in production:
 
 ```typescript
-interface Repository<T> {
-  create(data: Partial<T>): Promise<T>;
-  findById(id: string | number): Promise<T | null>;
-  findAll(filter?: Filter): Promise<T[]>;
-  findPage(options?: PageOptions): Promise<PageResult<T>>;
-  updateById(id: string | number, update: Partial<T>): Promise<T | null>;
-  deleteById(id: string | number): Promise<boolean>;
-  count(filter?: Filter): Promise<number>;
-  exists(filter?: Filter): Promise<boolean>;
+@Controller("health")
+export class HealthController {
+  constructor(@InjectDatabase() private readonly db: DatabaseService) {}
+
+  @Get()
+  async check() {
+    const mongoHealth = await this.db.getMongoAdapter().healthCheck();
+    // Returns:
+    // {
+    //   healthy: true,
+    //   responseTimeMs: 12,
+    //   type: 'mongo',
+    //   details: {
+    //     version: 'MongoDB 6.0',
+    //     activeConnections: 5,
+    //     poolSize: 10,
+    //   }
+    // }
+
+    return {
+      status: mongoHealth.healthy ? "healthy" : "unhealthy",
+      database: mongoHealth,
+    };
+  }
 }
 ```
 
-### Pagination
+### Soft Delete
+
+Non-destructive deletion with restore capability:
 
 ```typescript
-const result = await repo.findPage({
-  filter: { status: "active" },
-  page: 1,
-  limit: 20,
-  sort: "-createdAt", // or { createdAt: -1 }
+const repo = db.createMongoRepository<User>({
+  model: UserModel,
+  softDelete: true, // Enable soft delete
+  softDeleteField: "deletedAt", // Default field name
 });
 
-// Result:
-// {
-//   data: [...],
-//   page: 1,
-//   limit: 20,
-//   total: 150,
-//   pages: 8
-// }
+// "Delete" - sets deletedAt timestamp
+await repo.deleteById("123");
+
+// Regular queries exclude deleted records
+await repo.findAll(); // Only non-deleted users
+
+// Include deleted records
+await repo.findWithDeleted!(); // All users including deleted
+
+// Restore a deleted record
+await repo.restore!("123");
 ```
 
-### MongoDB Repository
+### Timestamps
+
+Automatic created/updated tracking:
 
 ```typescript
-import { Model } from "mongoose";
+const repo = db.createMongoRepository<User>({
+  model: UserModel,
+  timestamps: true, // Enable timestamps
+  createdAtField: "createdAt", // Default
+  updatedAtField: "updatedAt", // Default
+});
 
-// Create your Mongoose model as usual
-const usersRepo = db.createMongoRepository<User>({ model: UserModel });
+// create() automatically sets createdAt
+const user = await repo.create({ name: "John" });
+// user.createdAt = 2026-02-01T12:00:00.000Z
+
+// updateById() automatically sets updatedAt
+await repo.updateById(user._id, { name: "Johnny" });
+// user.updatedAt = 2026-02-01T12:01:00.000Z
 ```
 
-### PostgreSQL Repository
+---
 
-```typescript
-interface Order {
-  id: string;
-  user_id: string;
-  total: number;
-  created_at: Date;
-}
+## 🔍 Query Operators
+
+### MongoDB Queries
 
-const ordersRepo = db.createPostgresRepository<Order>({
-  table: "orders",
-  primaryKey: "id",
-  columns: ["id", "user_id", "total", "created_at", "is_deleted"],
-  defaultFilter: { is_deleted: false }, // Soft delete support
+Standard MongoDB query syntax:
+
+```typescript
+await repo.findAll({
+  age: { $gte: 18, $lt: 65 },
+  status: { $in: ["active", "pending"] },
+  name: { $regex: /john/i },
 });
 ```
 
-### PostgreSQL Advanced Filters
+### PostgreSQL Queries
+
+Structured query operators:
 
 ```typescript
-// Comparison operators
+// Comparison
 await repo.findAll({
-  price: { gt: 100, lte: 500 },
-  status: { ne: "cancelled" },
+  price: { gt: 100, lte: 500 }, // > 100 AND <= 500
+  status: { ne: "cancelled" }, // != 'cancelled'
 });
 
 // IN / NOT IN
 await repo.findAll({
   category: { in: ["electronics", "books"] },
+  brand: { nin: ["unknown"] },
 });
 
 // LIKE (case-insensitive)
@@ -269,34 +518,91 @@ await repo.findAll({
 // NULL checks
 await repo.findAll({
   deleted_at: { isNull: true },
+  email: { isNotNull: true },
+});
+
+// Sorting
+await repo.findPage({
+  sort: "-created_at,name", // DESC created_at, ASC name
+  // or: { created_at: -1, name: 1 }
 });
 ```
 
 ---
 
-## 🛡️ Error Handling
+## ⚙️ Configuration
 
-### Global Exception Filter
+### Environment Variables
+
+| Variable            | Description                  | Required           |
+| ------------------- | ---------------------------- | ------------------ |
+| `DATABASE_TYPE`     | `mongo` or `postgres`        | Yes                |
+| `MONGO_URI`         | MongoDB connection string    | For MongoDB        |
+| `DATABASE_URL`      | PostgreSQL connection string | For PostgreSQL     |
+| `DATABASE_POOL_MIN` | Min pool connections         | No (default: 0)    |
+| `DATABASE_POOL_MAX` | Max pool connections         | No (default: 10)   |
+| `DATABASE_TIMEOUT`  | Connection timeout (ms)      | No (default: 5000) |
 
-Register the filter globally to catch and format database errors:
+### Async Configuration (Recommended)
 
 ```typescript
-// main.ts
-import { DatabaseExceptionFilter } from "@ciscode/database-kit";
+import { ConfigModule, ConfigService } from "@nestjs/config";
 
-app.useGlobalFilters(new DatabaseExceptionFilter());
+DatabaseKitModule.forRootAsync({
+  imports: [ConfigModule],
+  useFactory: (config: ConfigService) => ({
+    config: {
+      type: config.get("DATABASE_TYPE") as "mongo" | "postgres",
+      connectionString: config.get("DATABASE_URL")!,
+      pool: {
+        min: config.get("DATABASE_POOL_MIN", 0),
+        max: config.get("DATABASE_POOL_MAX", 10),
+      },
+    },
+  }),
+  inject: [ConfigService],
+});
 ```
 
-Or in a module:
+### Multiple Databases
 
 ```typescript
-import { APP_FILTER } from "@nestjs/core";
-import { DatabaseExceptionFilter } from "@ciscode/database-kit";
-
 @Module({
-  providers: [{ provide: APP_FILTER, useClass: DatabaseExceptionFilter }],
+  imports: [
+    // Primary database
+    DatabaseKitModule.forRoot({
+      config: { type: "mongo", connectionString: process.env.MONGO_URI! },
+    }),
+    // Analytics database (PostgreSQL)
+    DatabaseKitModule.forFeature("ANALYTICS_DB", {
+      type: "postgres",
+      connectionString: process.env.ANALYTICS_DB_URL!,
+    }),
+  ],
 })
 export class AppModule {}
+
+// Usage
+@Injectable()
+export class AnalyticsService {
+  constructor(
+    @InjectDatabaseByToken("ANALYTICS_DB")
+    private readonly analyticsDb: DatabaseService,
+  ) {}
+}
+```
+
+---
+
+## 🛡️ Error Handling
+
+### Global Exception Filter
+
+```typescript
+// main.ts
+import { DatabaseExceptionFilter } from "@ciscode/database-kit";
+
+app.useGlobalFilters(new DatabaseExceptionFilter());
 ```
 
 ### Error Response Format
@@ -306,7 +612,7 @@ export class AppModule {}
   "statusCode": 409,
   "message": "A record with this value already exists",
   "error": "DuplicateKeyError",
-  "timestamp": "2026-01-31T12:00:00.000Z",
+  "timestamp": "2026-02-01T12:00:00.000Z",
   "path": "/api/users"
 }
 ```
@@ -322,10 +628,15 @@ import {
   normalizePaginationOptions,
   parseSortString,
   calculateOffset,
+  createPageResult,
 } from "@ciscode/database-kit";
 
 const normalized = normalizePaginationOptions({ page: 1 });
+// { page: 1, limit: 10, filter: {}, sort: undefined }
+
 const sortObj = parseSortString("-createdAt,name");
+// { createdAt: -1, name: 1 }
+
 const offset = calculateOffset(2, 10); // 10
 ```
 
@@ -337,6 +648,7 @@ import {
   isValidUuid,
   sanitizeFilter,
   pickFields,
+  omitFields,
 } from "@ciscode/database-kit";
 
 isValidMongoId("507f1f77bcf86cd799439011"); // true
@@ -345,7 +657,8 @@ isValidUuid("550e8400-e29b-41d4-a716-446655440000"); // true
 const clean = sanitizeFilter({ name: "John", age: undefined });
 // { name: 'John' }
 
-const picked = pickFields(data, ["name", "email"]);
+const picked = pickFields(user, ["name", "email"]);
+const safe = omitFields(user, ["password", "secret"]);
 ```
 
 ---
@@ -358,17 +671,31 @@ npm test
 
 # Run with coverage
 npm run test:cov
+
+# Run specific test file
+npm test -- --testPathPattern=mongo.adapter.spec
 ```
 
 ### Mocking in Tests
 
 ```typescript
+import { Test } from "@nestjs/testing";
+import { DATABASE_TOKEN } from "@ciscode/database-kit";
+
+const mockRepository = {
+  create: jest.fn().mockResolvedValue({ id: "1", name: "Test" }),
+  findById: jest.fn().mockResolvedValue({ id: "1", name: "Test" }),
+  findAll: jest.fn().mockResolvedValue([]),
+  findPage: jest
+    .fn()
+    .mockResolvedValue({ data: [], total: 0, page: 1, limit: 10, pages: 0 }),
+  updateById: jest.fn().mockResolvedValue({ id: "1", name: "Updated" }),
+  deleteById: jest.fn().mockResolvedValue(true),
+};
+
 const mockDb = {
-  createMongoRepository: jest.fn().mockReturnValue({
-    create: jest.fn(),
-    findById: jest.fn(),
-    // ...
-  }),
+  createMongoRepository: jest.fn().mockReturnValue(mockRepository),
+  createPostgresRepository: jest.fn().mockReturnValue(mockRepository),
 };
 
 const module = await Test.createTestingModule({
@@ -382,30 +709,42 @@ const module = await Test.createTestingModule({
 
 ```
 src/
-├── index.ts                       # Public API exports
-├── database-kit.module.ts         # NestJS module
-├── adapters/                      # Database adapters
-│   ├── mongo.adapter.ts
-│   └── postgres.adapter.ts
-├── config/                        # Configuration
-│   ├── database.config.ts
-│   └── database.constants.ts
-├── contracts/                     # TypeScript contracts
-│   └── database.contracts.ts
-├── filters/                       # Exception filters
-│   └── database-exception.filter.ts
-├── middleware/                    # Decorators
-│   └── database.decorators.ts
-├── services/                      # Business logic
-│   ├── database.service.ts
-│   └── logger.service.ts
-└── utils/                         # Utilities
-    ├── pagination.utils.ts
-    └── validation.utils.ts
+├── index.ts                         # Public API exports
+├── database-kit.module.ts           # NestJS module
+├── adapters/
+│   ├── mongo.adapter.ts             # MongoDB implementation
+│   └── postgres.adapter.ts          # PostgreSQL implementation
+├── config/
+│   ├── database.config.ts           # Configuration helper
+│   └── database.constants.ts        # Constants
+├── contracts/
+│   └── database.contracts.ts        # TypeScript interfaces
+├── filters/
+│   └── database-exception.filter.ts # Error handling
+├── middleware/
+│   └── database.decorators.ts       # DI decorators
+├── services/
+│   ├── database.service.ts          # Main service
+│   └── logger.service.ts            # Logging
+└── utils/
+    ├── pagination.utils.ts          # Pagination helpers
+    └── validation.utils.ts          # Validation helpers
 ```
 
 ---
 
+## 📊 Package Stats
+
+| Metric           | Value                        |
+| ---------------- | ---------------------------- |
+| **Version**      | 1.0.0                        |
+| **Tests**        | 133 passing                  |
+| **Total LOC**    | ~5,200 lines                 |
+| **TypeScript**   | 100%                         |
+| **Dependencies** | Minimal (mongoose, knex, pg) |
+
+---
+
 ## 🔒 Security
 
 See [SECURITY.md](SECURITY.md) for:
@@ -435,12 +774,12 @@ See [CHANGELOG.md](CHANGELOG.md) for version history.
 
 ## 📄 License
 
-MIT © [C International Service](https://ciscode.com)
+MIT © [C International Service](https://ciscode.co.uk)
 
 ---
 
 ## 🙋 Support
 
-- 📧 Email: info@ciscode.com
+- 📧 Email: info@ciscod.com
 - 🐛 Issues: [GitHub Issues](https://github.com/CISCODE-MA/DatabaseKit/issues)
 - 📖 Docs: [GitHub Wiki](https://github.com/CISCODE-MA/DatabaseKit/wiki)
diff --git a/SECURITY.md b/SECURITY.md
index caa29c1..d65cf88 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -25,7 +25,7 @@ If you discover a security vulnerability, **please do NOT file a public issue**.
 
 Instead, report it privately to our security team:
 
-📧 **security@ciscode.com**
+📧 **info@ciscod.com**
 
 Or use GitHub's private vulnerability reporting:
 
@@ -232,7 +232,7 @@ We appreciate security researchers who help keep DatabaseKit secure:
 
 ## 📞 Security Contact
 
-**Email:** security@ciscode.com
+**Email:** info@ciscod.com
 
 **PGP Key:** Available upon request for encrypted communications.
 
diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md
index 5e07e27..4c53db2 100644
--- a/TROUBLESHOOTING.md
+++ b/TROUBLESHOOTING.md
@@ -474,7 +474,7 @@ When creating an issue, include:
 
 - 🐛 **Bug Reports:** [GitHub Issues](https://github.com/CISCODE-MA/DatabaseKit/issues)
 - 💬 **Questions:** [GitHub Discussions](https://github.com/CISCODE-MA/DatabaseKit/discussions)
-- 📧 **Email:** info@ciscode.com
+- 📧 **Email:** info@ciscod.com
 
 ---
 
diff --git a/package.json b/package.json
index e4c9014..308e5fe 100644
--- a/package.json
+++ b/package.json
@@ -5,7 +5,7 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "license": "MIT",
-  "author": "C International Service <info@ciscode.com>",
+  "author": "C International Service <info@ciscod.com>",
   "repository": {
     "type": "git",
     "url": "https://github.com/CISCODE-MA/DatabaseKit.git"
diff --git a/src/adapters/mongo.adapter.spec.ts b/src/adapters/mongo.adapter.spec.ts
new file mode 100644
index 0000000..e727a03
--- /dev/null
+++ b/src/adapters/mongo.adapter.spec.ts
@@ -0,0 +1,569 @@
+import { MongoAdapter } from './mongo.adapter';
+import { MongoDatabaseConfig, MongoTransactionContext } from '../contracts/database.contracts';
+
+// Mock mongoose
+jest.mock('mongoose', () => {
+    const mockSession = {
+        startTransaction: jest.fn(),
+        commitTransaction: jest.fn().mockResolvedValue(undefined),
+        abortTransaction: jest.fn().mockResolvedValue(undefined),
+        endSession: jest.fn().mockResolvedValue(undefined),
+    };
+
+    const mockConnection = {
+        readyState: 0,
+        on: jest.fn(),
+    };
+
+    return {
+        connect: jest.fn().mockResolvedValue({}),
+        disconnect: jest.fn().mockResolvedValue(undefined),
+        startSession: jest.fn().mockResolvedValue(mockSession),
+        connection: mockConnection,
+        set: jest.fn(),
+    };
+});
+
+describe('MongoAdapter', () => {
+    let adapter: MongoAdapter;
+    const mockConfig: MongoDatabaseConfig = {
+        type: 'mongo',
+        connectionString: 'mongodb://localhost:27017/testdb',
+    };
+
+    beforeEach(() => {
+        adapter = new MongoAdapter(mockConfig);
+        jest.clearAllMocks();
+    });
+
+    afterEach(async () => {
+        await adapter.disconnect();
+    });
+
+    describe('constructor', () => {
+        it('should create adapter instance', () => {
+            expect(adapter).toBeDefined();
+            expect(adapter).toBeInstanceOf(MongoAdapter);
+        });
+    });
+
+    describe('isConnected', () => {
+        it('should return false when not connected', () => {
+            expect(adapter.isConnected()).toBe(false);
+        });
+    });
+
+    describe('connect', () => {
+        it('should connect to MongoDB', async () => {
+            const mongoose = await import('mongoose');
+            await adapter.connect();
+            expect(mongoose.connect).toHaveBeenCalledWith(
+                mockConfig.connectionString,
+                expect.objectContaining({
+                    maxPoolSize: 10,
+                    serverSelectionTimeoutMS: 5000,
+                }),
+            );
+        });
+
+        it('should reuse existing connection', async () => {
+            const mongoose = await import('mongoose');
+            await adapter.connect();
+            await adapter.connect();
+            expect(mongoose.connect).toHaveBeenCalledTimes(1);
+        });
+    });
+
+    describe('disconnect', () => {
+        it('should disconnect from MongoDB', async () => {
+            const mongoose = await import('mongoose');
+            await adapter.connect();
+            await adapter.disconnect();
+            expect(mongoose.disconnect).toHaveBeenCalled();
+        });
+    });
+
+    describe('createRepository', () => {
+        it('should create a repository with all CRUD methods', () => {
+            const mockModel = {
+                create: jest.fn(),
+                findById: jest.fn().mockReturnThis(),
+                find: jest.fn().mockReturnThis(),
+                findByIdAndUpdate: jest.fn().mockReturnThis(),
+                findByIdAndDelete: jest.fn().mockReturnThis(),
+                countDocuments: jest.fn().mockReturnThis(),
+                exists: jest.fn(),
+                insertMany: jest.fn(),
+                updateMany: jest.fn().mockReturnThis(),
+                deleteMany: jest.fn().mockReturnThis(),
+                lean: jest.fn().mockReturnThis(),
+                exec: jest.fn(),
+                skip: jest.fn().mockReturnThis(),
+                limit: jest.fn().mockReturnThis(),
+                sort: jest.fn().mockReturnThis(),
+            };
+
+            const repo = adapter.createRepository({ model: mockModel });
+
+            expect(repo).toBeDefined();
+            expect(typeof repo.create).toBe('function');
+            expect(typeof repo.findById).toBe('function');
+            expect(typeof repo.findAll).toBe('function');
+            expect(typeof repo.findPage).toBe('function');
+            expect(typeof repo.updateById).toBe('function');
+            expect(typeof repo.deleteById).toBe('function');
+            expect(typeof repo.count).toBe('function');
+            expect(typeof repo.exists).toBe('function');
+            // Bulk operations
+            expect(typeof repo.insertMany).toBe('function');
+            expect(typeof repo.updateMany).toBe('function');
+            expect(typeof repo.deleteMany).toBe('function');
+        });
+
+        it('should insertMany documents', async () => {
+            const mockDocs = [
+                { _id: '1', name: 'John', toObject: () => ({ _id: '1', name: 'John' }) },
+                { _id: '2', name: 'Jane', toObject: () => ({ _id: '2', name: 'Jane' }) },
+            ];
+            const mockModel = {
+                insertMany: jest.fn().mockResolvedValue(mockDocs),
+            };
+
+            const repo = adapter.createRepository({ model: mockModel });
+            const result = await repo.insertMany([{ name: 'John' }, { name: 'Jane' }]);
+
+            expect(mockModel.insertMany).toHaveBeenCalledWith([{ name: 'John' }, { name: 'Jane' }]);
+            expect(result).toHaveLength(2);
+            expect(result[0]).toEqual({ _id: '1', name: 'John' });
+        });
+
+        it('should return empty array when insertMany with empty data', async () => {
+            const mockModel = {
+                insertMany: jest.fn(),
+            };
+
+            const repo = adapter.createRepository({ model: mockModel });
+            const result = await repo.insertMany([]);
+
+            expect(result).toEqual([]);
+            expect(mockModel.insertMany).not.toHaveBeenCalled();
+        });
+
+        it('should updateMany documents', async () => {
+            const mockModel = {
+                updateMany: jest.fn().mockReturnValue({
+                    exec: jest.fn().mockResolvedValue({ modifiedCount: 5 }),
+                }),
+            };
+
+            const repo = adapter.createRepository({ model: mockModel });
+            const result = await repo.updateMany({ status: 'active' }, { status: 'inactive' });
+
+            expect(mockModel.updateMany).toHaveBeenCalledWith(
+                { status: 'active' },
+                { status: 'inactive' },
+                {},
+            );
+            expect(result).toBe(5);
+        });
+
+        it('should deleteMany documents', async () => {
+            const mockModel = {
+                deleteMany: jest.fn().mockReturnValue({
+                    exec: jest.fn().mockResolvedValue({ deletedCount: 3 }),
+                }),
+            };
+
+            const repo = adapter.createRepository({ model: mockModel });
+            const result = await repo.deleteMany({ status: 'deleted' });
+
+            expect(mockModel.deleteMany).toHaveBeenCalledWith({ status: 'deleted' }, {});
+            expect(result).toBe(3);
+        });
+    });
+
+    describe('withTransaction', () => {
+        it('should execute callback within transaction', async () => {
+            const mongoose = await import('mongoose');
+            const mockCallback = jest.fn().mockResolvedValue({ success: true });
+
+            // Need to connect first
+            await adapter.connect();
+
+            await adapter.withTransaction(mockCallback);
+
+            expect(mongoose.startSession).toHaveBeenCalled();
+            expect(mockCallback).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    transaction: expect.any(Object),
+                    createRepository: expect.any(Function),
+                }),
+            );
+        });
+
+        it('should commit transaction on success', async () => {
+            const mongoose = await import('mongoose');
+            await adapter.connect();
+
+            const mockSession = await mongoose.startSession();
+            await adapter.withTransaction(async () => 'result');
+
+            expect(mockSession.commitTransaction).toHaveBeenCalled();
+            expect(mockSession.endSession).toHaveBeenCalled();
+        });
+
+        it('should abort transaction on error', async () => {
+            const mongoose = await import('mongoose');
+            await adapter.connect();
+
+            const mockSession = await mongoose.startSession();
+            const error = new Error('Test error');
+
+            await expect(
+                adapter.withTransaction(async () => {
+                    throw error;
+                }),
+            ).rejects.toThrow('Test error');
+
+            expect(mockSession.abortTransaction).toHaveBeenCalled();
+            expect(mockSession.endSession).toHaveBeenCalled();
+        });
+
+        it('should provide transaction context with createRepository', async () => {
+            await adapter.connect();
+            let capturedContext: MongoTransactionContext | undefined;
+
+            await adapter.withTransaction(async (ctx) => {
+                capturedContext = ctx;
+                return 'done';
+            });
+
+            expect(capturedContext).toBeDefined();
+            expect(capturedContext!.transaction).toBeDefined();
+            expect(typeof capturedContext!.createRepository).toBe('function');
+        });
+
+        it('should respect transaction options', async () => {
+            const mongoose = await import('mongoose');
+            await adapter.connect();
+
+            const mockSession = await mongoose.startSession();
+
+            await adapter.withTransaction(
+                async () => 'result',
+                { timeout: 10000, retries: 0 },
+            );
+
+            expect(mockSession.startTransaction).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    maxCommitTimeMS: 10000,
+                }),
+            );
+        });
+    });
+
+    describe('healthCheck', () => {
+        it('should return unhealthy when not connected', async () => {
+            const result = await adapter.healthCheck();
+
+            expect(result.healthy).toBe(false);
+            expect(result.type).toBe('mongo');
+            expect(result.error).toBe('Not connected to MongoDB');
+            expect(result.responseTimeMs).toBeGreaterThanOrEqual(0);
+        });
+
+        it('should have healthCheck method', () => {
+            expect(typeof adapter.healthCheck).toBe('function');
+        });
+
+        it('should return response time in result', async () => {
+            const result = await adapter.healthCheck();
+
+            expect(typeof result.responseTimeMs).toBe('number');
+            expect(result.responseTimeMs).toBeGreaterThanOrEqual(0);
+        });
+    });
+
+    describe('Soft Delete', () => {
+        it('should not have soft delete methods when softDelete is disabled', () => {
+            const mockModel = {
+                find: jest.fn().mockReturnThis(),
+                lean: jest.fn().mockReturnThis(),
+                exec: jest.fn(),
+            };
+
+            const repo = adapter.createRepository({ model: mockModel, softDelete: false });
+
+            expect(repo.softDelete).toBeUndefined();
+            expect(repo.softDeleteMany).toBeUndefined();
+            expect(repo.restore).toBeUndefined();
+            expect(repo.restoreMany).toBeUndefined();
+            expect(repo.findAllWithDeleted).toBeUndefined();
+            expect(repo.findDeleted).toBeUndefined();
+        });
+
+        it('should have soft delete methods when softDelete is enabled', () => {
+            const mockModel = {
+                find: jest.fn().mockReturnThis(),
+                findById: jest.fn().mockReturnThis(),
+                updateOne: jest.fn().mockReturnThis(),
+                updateMany: jest.fn().mockReturnThis(),
+                findOneAndUpdate: jest.fn().mockReturnThis(),
+                lean: jest.fn().mockReturnThis(),
+                exec: jest.fn(),
+            };
+
+            const repo = adapter.createRepository({ model: mockModel, softDelete: true });
+
+            expect(typeof repo.softDelete).toBe('function');
+            expect(typeof repo.softDeleteMany).toBe('function');
+            expect(typeof repo.restore).toBe('function');
+            expect(typeof repo.restoreMany).toBe('function');
+            expect(typeof repo.findAllWithDeleted).toBe('function');
+            expect(typeof repo.findDeleted).toBe('function');
+        });
+
+        it('should soft delete a record by setting deletedAt', async () => {
+            const mockModel = {
+                find: jest.fn().mockReturnThis(),
+                updateOne: jest.fn().mockReturnValue({
+                    exec: jest.fn().mockResolvedValue({ modifiedCount: 1 }),
+                }),
+                lean: jest.fn().mockReturnThis(),
+                exec: jest.fn(),
+            };
+
+            const repo = adapter.createRepository({ model: mockModel, softDelete: true });
+            const result = await repo.softDelete!('123');
+
+            expect(result).toBe(true);
+            expect(mockModel.updateOne).toHaveBeenCalledWith(
+                { _id: '123', deletedAt: { $eq: null } },
+                expect.objectContaining({ deletedAt: expect.any(Date) }),
+                {},
+            );
+        });
+
+        it('should use custom softDeleteField', async () => {
+            const mockModel = {
+                find: jest.fn().mockReturnThis(),
+                updateOne: jest.fn().mockReturnValue({
+                    exec: jest.fn().mockResolvedValue({ modifiedCount: 1 }),
+                }),
+                lean: jest.fn().mockReturnThis(),
+                exec: jest.fn(),
+            };
+
+            const repo = adapter.createRepository({
+                model: mockModel,
+                softDelete: true,
+                softDeleteField: 'removedAt',
+            });
+            await repo.softDelete!('123');
+
+            expect(mockModel.updateOne).toHaveBeenCalledWith(
+                { _id: '123', removedAt: { $eq: null } },
+                expect.objectContaining({ removedAt: expect.any(Date) }),
+                {},
+            );
+        });
+
+        it('should restore a soft-deleted record', async () => {
+            const mockModel = {
+                find: jest.fn().mockReturnThis(),
+                findOneAndUpdate: jest.fn().mockReturnValue({
+                    lean: jest.fn().mockReturnValue({
+                        exec: jest.fn().mockResolvedValue({ _id: '123', name: 'Test' }),
+                    }),
+                }),
+                lean: jest.fn().mockReturnThis(),
+                exec: jest.fn(),
+            };
+
+            const repo = adapter.createRepository({ model: mockModel, softDelete: true });
+            const result = await repo.restore!('123');
+
+            expect(result).toEqual({ _id: '123', name: 'Test' });
+            expect(mockModel.findOneAndUpdate).toHaveBeenCalledWith(
+                { _id: '123', deletedAt: { $ne: null } },
+                { $unset: { deletedAt: 1 } },
+                { new: true },
+            );
+        });
+
+        it('should find only deleted records', async () => {
+            const mockDocs = [{ _id: '1', deletedAt: new Date() }];
+            const mockModel = {
+                find: jest.fn().mockReturnValue({
+                    lean: jest.fn().mockReturnValue({
+                        exec: jest.fn().mockResolvedValue(mockDocs),
+                    }),
+                }),
+            };
+
+            const repo = adapter.createRepository({ model: mockModel, softDelete: true });
+            const result = await repo.findDeleted!({});
+
+            expect(result).toEqual(mockDocs);
+            expect(mockModel.find).toHaveBeenCalledWith({ deletedAt: { $ne: null } });
+        });
+
+        it('should deleteMany as soft delete when enabled', async () => {
+            const mockModel = {
+                find: jest.fn().mockReturnThis(),
+                updateMany: jest.fn().mockReturnValue({
+                    exec: jest.fn().mockResolvedValue({ modifiedCount: 5 }),
+                }),
+                lean: jest.fn().mockReturnThis(),
+                exec: jest.fn(),
+            };
+
+            const repo = adapter.createRepository({ model: mockModel, softDelete: true });
+            const result = await repo.deleteMany({ status: 'old' });
+
+            expect(result).toBe(5);
+            expect(mockModel.updateMany).toHaveBeenCalledWith(
+                expect.objectContaining({ status: 'old', deletedAt: { $eq: null } }),
+                expect.objectContaining({ deletedAt: expect.any(Date) }),
+                {},
+            );
+        });
+
+        it('should filter out soft-deleted records in findAll', async () => {
+            const mockDocs = [{ _id: '1', name: 'Active' }];
+            const mockModel = {
+                find: jest.fn().mockReturnValue({
+                    lean: jest.fn().mockReturnValue({
+                        exec: jest.fn().mockResolvedValue(mockDocs),
+                    }),
+                }),
+            };
+
+            const repo = adapter.createRepository({ model: mockModel, softDelete: true });
+            await repo.findAll({});
+
+            expect(mockModel.find).toHaveBeenCalledWith(
+                expect.objectContaining({ deletedAt: { $eq: null } }),
+            );
+        });
+    });
+
+    describe('Timestamps', () => {
+        it('should add createdAt on create when timestamps enabled', async () => {
+            const mockDoc = { _id: '1', name: 'Test', toObject: () => ({ _id: '1', name: 'Test' }) };
+            const mockModel = {
+                create: jest.fn().mockResolvedValue(mockDoc),
+            };
+
+            const repo = adapter.createRepository({ model: mockModel, timestamps: true });
+            await repo.create({ name: 'Test' });
+
+            expect(mockModel.create).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    name: 'Test',
+                    createdAt: expect.any(Date),
+                }),
+            );
+        });
+
+        it('should not add createdAt when timestamps disabled', async () => {
+            const mockDoc = { _id: '1', name: 'Test', toObject: () => ({ _id: '1', name: 'Test' }) };
+            const mockModel = {
+                create: jest.fn().mockResolvedValue(mockDoc),
+            };
+
+            const repo = adapter.createRepository({ model: mockModel, timestamps: false });
+            await repo.create({ name: 'Test' });
+
+            expect(mockModel.create).toHaveBeenCalledWith({ name: 'Test' });
+        });
+
+        it('should add updatedAt on updateById when timestamps enabled', async () => {
+            const mockModel = {
+                find: jest.fn().mockReturnThis(),
+                findOneAndUpdate: jest.fn().mockReturnValue({
+                    lean: jest.fn().mockReturnValue({
+                        exec: jest.fn().mockResolvedValue({ _id: '1', name: 'Updated' }),
+                    }),
+                }),
+                lean: jest.fn().mockReturnThis(),
+                exec: jest.fn(),
+            };
+
+            const repo = adapter.createRepository({ model: mockModel, timestamps: true });
+            await repo.updateById('1', { name: 'Updated' });
+
+            expect(mockModel.findOneAndUpdate).toHaveBeenCalledWith(
+                { _id: '1' },
+                expect.objectContaining({
+                    name: 'Updated',
+                    updatedAt: expect.any(Date),
+                }),
+                { new: true },
+            );
+        });
+
+        it('should use custom timestamp fields', async () => {
+            const mockDoc = { _id: '1', name: 'Test', toObject: () => ({ _id: '1', name: 'Test' }) };
+            const mockModel = {
+                create: jest.fn().mockResolvedValue(mockDoc),
+            };
+
+            const repo = adapter.createRepository({
+                model: mockModel,
+                timestamps: true,
+                createdAtField: 'created',
+                updatedAtField: 'modified',
+            });
+            await repo.create({ name: 'Test' });
+
+            expect(mockModel.create).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    name: 'Test',
+                    created: expect.any(Date),
+                }),
+            );
+        });
+
+        it('should add createdAt to insertMany items when timestamps enabled', async () => {
+            const mockDocs = [
+                { _id: '1', name: 'John', toObject: () => ({ _id: '1', name: 'John' }) },
+                { _id: '2', name: 'Jane', toObject: () => ({ _id: '2', name: 'Jane' }) },
+            ];
+            const mockModel = {
+                insertMany: jest.fn().mockResolvedValue(mockDocs),
+            };
+
+            const repo = adapter.createRepository({ model: mockModel, timestamps: true });
+            await repo.insertMany([{ name: 'John' }, { name: 'Jane' }]);
+
+            expect(mockModel.insertMany).toHaveBeenCalledWith([
+                expect.objectContaining({ name: 'John', createdAt: expect.any(Date) }),
+                expect.objectContaining({ name: 'Jane', createdAt: expect.any(Date) }),
+            ]);
+        });
+
+        it('should add updatedAt to updateMany when timestamps enabled', async () => {
+            const mockModel = {
+                find: jest.fn().mockReturnThis(),
+                updateMany: jest.fn().mockReturnValue({
+                    exec: jest.fn().mockResolvedValue({ modifiedCount: 3 }),
+                }),
+                lean: jest.fn().mockReturnThis(),
+                exec: jest.fn(),
+            };
+
+            const repo = adapter.createRepository({ model: mockModel, timestamps: true });
+            await repo.updateMany({ status: 'pending' }, { status: 'active' });
+
+            expect(mockModel.updateMany).toHaveBeenCalledWith(
+                { status: 'pending' },
+                expect.objectContaining({
+                    status: 'active',
+                    updatedAt: expect.any(Date),
+                }),
+                {},
+            );
+        });
+    });
+});
diff --git a/src/adapters/mongo.adapter.ts b/src/adapters/mongo.adapter.ts
index f0dbe77..9700a45 100644
--- a/src/adapters/mongo.adapter.ts
+++ b/src/adapters/mongo.adapter.ts
@@ -1,13 +1,16 @@
-// src/adapters/mongo.adapter.ts
-
-import mongoose, { ConnectOptions, Model } from 'mongoose';
+import mongoose, { ConnectOptions, Model, ClientSession } from 'mongoose';
 import { Injectable, Logger } from '@nestjs/common';
 import {
     MongoDatabaseConfig,
     MongoRepositoryOptions,
+    MongoTransactionContext,
     Repository,
     PageResult,
     PageOptions,
+    TransactionOptions,
+    TransactionCallback,
+    HealthCheckResult,
+    DATABASE_KIT_CONSTANTS,
 } from '../contracts/database.contracts';
 
 /**
@@ -43,9 +46,20 @@ export class MongoAdapter {
         if (!this.connectionPromise) {
             this.logger.log('Connecting to MongoDB...');
 
+            // Apply pool configuration from config
+            const poolConfig = this.config.pool || {};
+            const maxPoolSize = poolConfig.max ?? 10;
+            const minPoolSize = poolConfig.min ?? 5;
+            const serverSelectionTimeoutMS = this.config.serverSelectionTimeoutMS ?? 5000;
+            const socketTimeoutMS = this.config.socketTimeoutMS ?? 45000;
+            const maxIdleTimeMS = poolConfig.idleTimeoutMs ?? 30000;
+
             this.connectionPromise = mongoose.connect(this.config.connectionString, {
-                maxPoolSize: 10,
-                serverSelectionTimeoutMS: 5000,
+                maxPoolSize,
+                minPoolSize,
+                serverSelectionTimeoutMS,
+                socketTimeoutMS,
+                maxIdleTimeMS,
                 ...options,
             });
 
@@ -81,16 +95,107 @@ export class MongoAdapter {
         return mongoose.connection.readyState === 1;
     }
 
+    /**
+     * Performs a health check on the MongoDB connection.
+     * Sends a ping command to verify the database is responsive.
+     * 
+     * @returns Health check result with status and response time
+     * 
+     * @example
+     * ```typescript
+     * const health = await adapter.healthCheck();
+     * if (!health.healthy) {
+     *   console.error('Database unhealthy:', health.error);
+     * }
+     * ```
+     */
+    async healthCheck(): Promise<HealthCheckResult> {
+        const startTime = Date.now();
+
+        try {
+            if (!this.isConnected()) {
+                return {
+                    healthy: false,
+                    responseTimeMs: Date.now() - startTime,
+                    type: 'mongo',
+                    error: 'Not connected to MongoDB',
+                };
+            }
+
+            // Send ping command to verify connection
+            const admin = mongoose.connection.db?.admin();
+            const pingResult = await admin?.ping();
+
+            if (!pingResult?.ok) {
+                return {
+                    healthy: false,
+                    responseTimeMs: Date.now() - startTime,
+                    type: 'mongo',
+                    error: 'Ping command failed',
+                };
+            }
+
+            // Get server info for details
+            const serverInfo = await admin?.serverInfo();
+
+            return {
+                healthy: true,
+                responseTimeMs: Date.now() - startTime,
+                type: 'mongo',
+                details: {
+                    version: serverInfo?.version,
+                },
+            };
+        } catch (error) {
+            return {
+                healthy: false,
+                responseTimeMs: Date.now() - startTime,
+                type: 'mongo',
+                error: error instanceof Error ? error.message : 'Unknown error',
+            };
+        }
+    }
+
     /**
      * Creates a repository for a Mongoose model.
      * The repository provides a standardized CRUD interface.
      * 
      * @param opts - Options containing the Mongoose model
+     * @param session - Optional MongoDB session for transaction support
      * @returns Repository instance with CRUD methods
      */
-    createRepository<T = unknown>(opts: MongoRepositoryOptions): Repository<T> {
+    createRepository<T = unknown>(opts: MongoRepositoryOptions, session?: ClientSession): Repository<T> {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const model = opts.model as Model<any>;
+        const softDeleteEnabled = opts.softDelete ?? false;
+        const softDeleteField = opts.softDeleteField ?? 'deletedAt';
+
+        // Timestamp configuration
+        const timestampsEnabled = opts.timestamps ?? false;
+        const createdAtField = opts.createdAtField ?? 'createdAt';
+        const updatedAtField = opts.updatedAtField ?? 'updatedAt';
+
+        // Base filter to exclude soft-deleted records
+        const notDeletedFilter = softDeleteEnabled
+            ? { [softDeleteField]: { $eq: null } }
+            : {};
+
+        // Helper to add createdAt timestamp
+        const addCreatedAt = <D extends Record<string, unknown>>(data: D): D => {
+            if (timestampsEnabled) {
+                return { ...data, [createdAtField]: new Date() };
+            }
+            return data;
+        };
+
+        // Helper to add updatedAt timestamp
+        const addUpdatedAt = <D extends Record<string, unknown>>(data: D): D => {
+            if (timestampsEnabled) {
+                return { ...data, [updatedAtField]: new Date() };
+            }
+            return data;
+        };
+
         const shapePage = (
             data: T[],
             page: number,
@@ -103,61 +208,386 @@ export class MongoAdapter {
 
         const repo: Repository<T> = {
             async create(data: Partial<T>): Promise<T> {
-                const doc = await model.create(data);
+                const timestampedData = addCreatedAt(data as Record<string, unknown>);
+                const doc = session
+                    ? (await model.create([timestampedData], { session }))[0]
+                    : await model.create(timestampedData);
                 return (doc as { toObject?: () => T }).toObject?.() ?? (doc as T);
             },
 
             async findById(id: string | number): Promise<T | null> {
-                const doc = await model.findById(id).lean().exec();
+                const mergedFilter = { _id: id, ...notDeletedFilter };
+                let query = model.findOne(mergedFilter);
+                if (session) query = query.session(session);
+                const doc = await query.lean().exec();
                 return doc as T | null;
             },
 
             async findAll(filter: Record<string, unknown> = {}): Promise<T[]> {
-                const docs = await model.find(filter).lean().exec();
+                const mergedFilter = { ...filter, ...notDeletedFilter };
+                let query = model.find(mergedFilter);
+                if (session) query = query.session(session);
+                const docs = await query.lean().exec();
                 return docs as T[];
             },
 
+            async findOne(filter: Record<string, unknown>): Promise<T | null> {
+                const mergedFilter = { ...filter, ...notDeletedFilter };
+                let query = model.findOne(mergedFilter);
+                if (session) query = query.session(session);
+                const doc = await query.lean().exec();
+                return doc as T | null;
+            },
+
             async findPage(options: PageOptions = {}): Promise<PageResult<T>> {
                 const { filter = {}, page = 1, limit = 10, sort } = options;
+                const mergedFilter = { ...filter, ...notDeletedFilter };
 
                 const skip = Math.max(0, (page - 1) * limit);
-                let query = model.find(filter).skip(skip).limit(limit);
+                let query = model.find(mergedFilter).skip(skip).limit(limit);
 
                 if (sort) {
                     query = query.sort(sort as Record<string, 1 | -1>);
                 }
+                if (session) query = query.session(session);
 
                 const [data, total] = await Promise.all([
                     query.lean().exec(),
-                    model.countDocuments(filter).exec(),
+                    session
+                        ? model.countDocuments(mergedFilter).session(session).exec()
+                        : model.countDocuments(mergedFilter).exec(),
                 ]);
 
                 return shapePage(data as T[], page, limit, total);
             },
 
             async updateById(id: string | number, update: Partial<T>): Promise<T | null> {
-                const doc = await model
-                    .findByIdAndUpdate(id, update, { new: true })
-                    .lean()
-                    .exec();
+                const mergedFilter = { _id: id, ...notDeletedFilter };
+                const timestampedUpdate = addUpdatedAt(update as Record<string, unknown>);
+                let query = model.findOneAndUpdate(mergedFilter, timestampedUpdate, { new: true });
+                if (session) query = query.session(session);
+                const doc = await query.lean().exec();
                 return doc as T | null;
             },
 
             async deleteById(id: string | number): Promise<boolean> {
-                const res = await model.findByIdAndDelete(id).lean().exec();
+                // If soft delete is enabled, use softDelete instead
+                if (softDeleteEnabled) {
+                    const mergedFilter = { _id: id, ...notDeletedFilter };
+                    const options = session ? { session } : {};
+                    const result = await model.updateOne(
+                        mergedFilter,
+                        { [softDeleteField]: new Date() },
+                        options
+                    ).exec();
+                    return result.modifiedCount > 0;
+                }
+
+                let query = model.findByIdAndDelete(id);
+                if (session) query = query.session(session);
+                const res = await query.lean().exec();
                 return !!res;
             },
 
             async count(filter: Record<string, unknown> = {}): Promise<number> {
-                return model.countDocuments(filter).exec();
+                const mergedFilter = { ...filter, ...notDeletedFilter };
+                let query = model.countDocuments(mergedFilter);
+                if (session) query = query.session(session);
+                return query.exec();
             },
 
             async exists(filter: Record<string, unknown> = {}): Promise<boolean> {
-                const res = await model.exists(filter);
+                const mergedFilter = { ...filter, ...notDeletedFilter };
+                // exists() doesn't support session directly, use findOne
+                if (session) {
+                    const doc = await model.findOne(mergedFilter).session(session).select('_id').lean().exec();
+                    return !!doc;
+                }
+                const res = await model.exists(mergedFilter);
                 return !!res;
             },
+
+            // -----------------------------
+            // Bulk Operations
+            // -----------------------------
+
+            async insertMany(data: Partial<T>[]): Promise<T[]> {
+                if (data.length === 0) return [];
+
+                // Add createdAt timestamp to each record
+                const timestampedData = data.map(item =>
+                    addCreatedAt(item as Record<string, unknown>)
+                );
+
+                const docs = session
+                    ? await model.insertMany(timestampedData, { session })
+                    : await model.insertMany(timestampedData);
+
+                return docs.map((doc) =>
+                    (doc as { toObject?: () => T }).toObject?.() ?? (doc as T)
+                );
+            },
+
+            async updateMany(filter: Record<string, unknown>, update: Partial<T>): Promise<number> {
+                const mergedFilter = { ...filter, ...notDeletedFilter };
+                const timestampedUpdate = addUpdatedAt(update as Record<string, unknown>);
+                const options = session ? { session } : {};
+                const result = await model.updateMany(mergedFilter, timestampedUpdate, options).exec();
+                return result.modifiedCount;
+            },
+
+            async deleteMany(filter: Record<string, unknown>): Promise<number> {
+                const mergedFilter = { ...filter, ...notDeletedFilter };
+                const options = session ? { session } : {};
+
+                // If soft delete is enabled, update instead of delete
+                if (softDeleteEnabled) {
+                    const result = await model.updateMany(
+                        mergedFilter,
+                        { [softDeleteField]: new Date() },
+                        options
+                    ).exec();
+                    return result.modifiedCount;
+                }
+
+                const result = await model.deleteMany(mergedFilter, options).exec();
+                return result.deletedCount;
+            },
+
+            // -----------------------------
+            // Advanced Query Operations
+            // -----------------------------
+
+            async upsert(filter: Record<string, unknown>, data: Partial<T>): Promise<T> {
+                const mergedFilter = { ...filter, ...notDeletedFilter };
+                const timestampedData = timestampsEnabled
+                    ? { ...data, [updatedAtField]: new Date() }
+                    : data;
+
+                let query = model.findOneAndUpdate(
+                    mergedFilter,
+                    {
+                        $set: timestampedData,
+                        ...(timestampsEnabled ? { $setOnInsert: { [createdAtField]: new Date() } } : {})
+                    },
+                    { upsert: true, new: true }
+                );
+                if (session) query = query.session(session);
+                const doc = await query.lean().exec();
+                return doc as T;
+            },
+
+            async distinct<K extends keyof T>(field: K, filter: Record<string, unknown> = {}): Promise<T[K][]> {
+                const mergedFilter = { ...filter, ...notDeletedFilter };
+                let query = model.distinct(String(field), mergedFilter);
+                if (session) query = query.session(session);
+                const values = await query.exec();
+                return values as T[K][];
+            },
+
+            async select<K extends keyof T>(filter: Record<string, unknown>, fields: K[]): Promise<Pick<T, K>[]> {
+                const mergedFilter = { ...filter, ...notDeletedFilter };
+                const projection = fields.reduce((acc, field) => ({ ...acc, [field]: 1 }), {});
+                let query = model.find(mergedFilter).select(projection);
+                if (session) query = query.session(session);
+                const docs = await query.lean().exec();
+                return docs as Pick<T, K>[];
+            },
+
+            // -----------------------------
+            // Soft Delete Operations
+            // -----------------------------
+
+            softDelete: softDeleteEnabled
+                ? async (id: string | number): Promise<boolean> => {
+                    const mergedFilter = { _id: id, ...notDeletedFilter };
+                    const options = session ? { session } : {};
+                    const result = await model.updateOne(
+                        mergedFilter,
+                        { [softDeleteField]: new Date() },
+                        options
+                    ).exec();
+                    return result.modifiedCount > 0;
+                }
+                : undefined,
+
+            softDeleteMany: softDeleteEnabled
+                ? async (filter: Record<string, unknown>): Promise<number> => {
+                    const mergedFilter = { ...filter, ...notDeletedFilter };
+                    const options = session ? { session } : {};
+                    const result = await model.updateMany(
+                        mergedFilter,
+                        { [softDeleteField]: new Date() },
+                        options
+                    ).exec();
+                    return result.modifiedCount;
+                }
+                : undefined,
+
+            restore: softDeleteEnabled
+                ? async (id: string | number): Promise<T | null> => {
+                    const deletedFilter = { _id: id, [softDeleteField]: { $ne: null } };
+                    let query = model.findOneAndUpdate(
+                        deletedFilter,
+                        { $unset: { [softDeleteField]: 1 } },
+                        { new: true }
+                    );
+                    if (session) query = query.session(session);
+                    const doc = await query.lean().exec();
+                    return doc as T | null;
+                }
+                : undefined,
+
+            restoreMany: softDeleteEnabled
+                ? async (filter: Record<string, unknown>): Promise<number> => {
+                    const deletedFilter = { ...filter, [softDeleteField]: { $ne: null } };
+                    const options = session ? { session } : {};
+                    const result = await model.updateMany(
+                        deletedFilter,
+                        { $unset: { [softDeleteField]: 1 } },
+                        options
+                    ).exec();
+                    return result.modifiedCount;
+                }
+                : undefined,
+
+            findAllWithDeleted: softDeleteEnabled
+                ? async (filter: Record<string, unknown> = {}): Promise<T[]> => {
+                    let query = model.find(filter);
+                    if (session) query = query.session(session);
+                    const docs = await query.lean().exec();
+                    return docs as T[];
+                }
+                : undefined,
+
+            findDeleted: softDeleteEnabled
+                ? async (filter: Record<string, unknown> = {}): Promise<T[]> => {
+                    const deletedFilter = { ...filter, [softDeleteField]: { $ne: null } };
+                    let query = model.find(deletedFilter);
+                    if (session) query = query.session(session);
+                    const docs = await query.lean().exec();
+                    return docs as T[];
+                }
+                : undefined,
         };
 
         return repo;
     }
+
+    /**
+     * Executes a callback within a MongoDB transaction.
+     * All database operations within the callback are atomic.
+     * 
+     * **Note:** MongoDB transactions require a replica set.
+     * Standalone MongoDB instances do not support transactions.
+     * 
+     * @param callback - Function to execute within the transaction
+     * @param options - Transaction options
+     * @returns Result of the callback function
+     * @throws Error if transaction fails after all retries
+     * 
+     * @example
+     * ```typescript
+     * const result = await mongoAdapter.withTransaction(async (ctx) => {
+     *   const usersRepo = ctx.createRepository<User>({ model: UserModel });
+     *   const ordersRepo = ctx.createRepository<Order>({ model: OrderModel });
+     *   
+     *   const user = await usersRepo.create({ name: 'John' });
+     *   const order = await ordersRepo.create({ userId: user._id, total: 100 });
+     *   
+     *   return { user, order };
+     * });
+     * ```
+     */
+    async withTransaction<TResult>(
+        callback: TransactionCallback<MongoTransactionContext, TResult>,
+        options: TransactionOptions = {},
+    ): Promise<TResult> {
+        const { retries = 0, timeout = DATABASE_KIT_CONSTANTS.DEFAULT_TRANSACTION_TIMEOUT } = options;
+
+        await this.connect();
+
+        let lastError: Error | undefined;
+
+        for (let attempt = 0; attempt <= retries; attempt++) {
+            const session = await mongoose.startSession();
+
+            try {
+                session.startTransaction({
+                    maxCommitTimeMS: timeout,
+                });
+
+                const context: MongoTransactionContext = {
+                    transaction: session,
+                    createRepository: <T>(opts: MongoRepositoryOptions) =>
+                        this.createRepository<T>(opts, session),
+                };
+
+                const result = await callback(context);
+
+                await session.commitTransaction();
+                this.logger.debug(`Transaction committed successfully (attempt ${attempt + 1})`);
+
+                return result;
+            } catch (error) {
+                await session.abortTransaction();
+                lastError = error as Error;
+
+                this.logger.warn(
+                    `Transaction failed (attempt ${attempt + 1}/${retries + 1}): ${lastError.message}`,
+                );
+
+                // Check if error is transient and retryable
+                const isTransient = this.isTransientError(error);
+                if (!isTransient || attempt >= retries) {
+                    throw lastError;
+                }
+
+                // Exponential backoff before retry
+                const backoffMs = Math.min(100 * Math.pow(2, attempt), 3000);
+                await this.sleep(backoffMs);
+            } finally {
+                await session.endSession();
+            }
+        }
+
+        throw lastError || new Error('Transaction failed');
+    }
+
+    /**
+     * Checks if an error is transient and can be retried.
+     */
+    private isTransientError(error: unknown): boolean {
+        if (error && typeof error === 'object') {
+            const mongoError = error as { hasErrorLabel?: (label: string) => boolean; code?: number };
+
+            // MongoDB transient transaction errors
+            if (mongoError.hasErrorLabel?.('TransientTransactionError')) {
+                return true;
+            }
+
+            // Common retryable error codes
+            const retryableCodes = [
+                11600, // InterruptedAtShutdown
+                11602, // InterruptedDueToReplStateChange
+                10107, // NotWritablePrimary
+                13435, // NotPrimaryNoSecondaryOk
+                13436, // NotPrimaryOrSecondary
+                189,   // PrimarySteppedDown
+                91,    // ShutdownInProgress
+            ];
+
+            if (mongoError.code && retryableCodes.includes(mongoError.code)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Simple sleep utility for retry backoff.
+     */
+    private sleep(ms: number): Promise<void> {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
 }
diff --git a/src/adapters/postgres.adapter.spec.ts b/src/adapters/postgres.adapter.spec.ts
new file mode 100644
index 0000000..46dfce5
--- /dev/null
+++ b/src/adapters/postgres.adapter.spec.ts
@@ -0,0 +1,814 @@
+import { PostgresAdapter } from './postgres.adapter';
+import { PostgresDatabaseConfig, PostgresTransactionContext } from '../contracts/database.contracts';
+import { Knex } from 'knex';
+
+// Mock knex
+const mockTrx = {
+    raw: jest.fn().mockResolvedValue(undefined),
+    select: jest.fn().mockReturnThis(),
+    insert: jest.fn().mockReturnThis(),
+    update: jest.fn().mockReturnThis(),
+    delete: jest.fn().mockReturnThis(),
+    where: jest.fn().mockReturnThis(),
+    returning: jest.fn().mockResolvedValue([{ id: 1, name: 'test' }]),
+    first: jest.fn().mockResolvedValue({ id: 1, name: 'test' }),
+};
+
+const mockKnexInstance = jest.fn((_tableName: string) => ({
+    select: jest.fn().mockReturnThis(),
+    insert: jest.fn().mockReturnThis(),
+    update: jest.fn().mockReturnThis(),
+    delete: jest.fn().mockReturnThis(),
+    where: jest.fn().mockReturnThis(),
+    whereNot: jest.fn().mockReturnThis(),
+    whereIn: jest.fn().mockReturnThis(),
+    whereNotIn: jest.fn().mockReturnThis(),
+    whereILike: jest.fn().mockReturnThis(),
+    whereNull: jest.fn().mockReturnThis(),
+    whereNotNull: jest.fn().mockReturnThis(),
+    orderBy: jest.fn().mockReturnThis(),
+    limit: jest.fn().mockReturnThis(),
+    offset: jest.fn().mockReturnThis(),
+    count: jest.fn().mockReturnThis(),
+    modify: jest.fn().mockReturnThis(),
+    clone: jest.fn().mockReturnThis(),
+    returning: jest.fn().mockResolvedValue([{ id: 1, name: 'test' }]),
+    first: jest.fn().mockResolvedValue({ id: 1, name: 'test' }),
+})) as unknown as ReturnType<typeof import('knex').default>;
+
+// Add transaction method to mock
+(mockKnexInstance as unknown as { transaction: jest.Mock }).transaction = jest.fn(
+    async (callback: (trx: typeof mockTrx) => Promise<unknown>, _options?: unknown) => {
+        return callback(mockTrx);
+    },
+);
+
+(mockKnexInstance as unknown as { destroy: jest.Mock }).destroy = jest.fn().mockResolvedValue(undefined);
+
+jest.mock('knex', () => {
+    return jest.fn(() => mockKnexInstance);
+});
+
+describe('PostgresAdapter', () => {
+    let adapter: PostgresAdapter;
+    const mockConfig: PostgresDatabaseConfig = {
+        type: 'postgres',
+        connectionString: 'postgresql://localhost:5432/testdb',
+    };
+
+    // Test interface for typed repositories
+    interface TestUser {
+        id: number;
+        name: string;
+        email: string;
+        status: string;
+        active: boolean;
+    }
+
+    beforeEach(() => {
+        adapter = new PostgresAdapter(mockConfig);
+        jest.clearAllMocks();
+    });
+
+    afterEach(async () => {
+        // Reset the knexInstance to avoid disconnect issues with mocks
+        adapter['knexInstance'] = undefined;
+    });
+
+    describe('constructor', () => {
+        it('should create adapter instance', () => {
+            expect(adapter).toBeDefined();
+            expect(adapter).toBeInstanceOf(PostgresAdapter);
+        });
+    });
+
+    describe('isConnected', () => {
+        it('should return false when not connected', () => {
+            expect(adapter.isConnected()).toBe(false);
+        });
+
+        it('should return true when connected', () => {
+            adapter.connect();
+            expect(adapter.isConnected()).toBe(true);
+        });
+    });
+
+    describe('connect', () => {
+        it('should create Knex instance', () => {
+            const knex = adapter.connect();
+            expect(knex).toBeDefined();
+        });
+
+        it('should reuse existing connection', () => {
+            const knex1 = adapter.connect();
+            const knex2 = adapter.connect();
+            expect(knex1).toBe(knex2);
+        });
+    });
+
+    describe('disconnect', () => {
+        it('should destroy Knex instance', async () => {
+            adapter.connect();
+            await adapter.disconnect();
+            expect(adapter.isConnected()).toBe(false);
+        });
+    });
+
+    describe('getKnex', () => {
+        it('should throw when not connected', () => {
+            expect(() => adapter.getKnex()).toThrow('PostgreSQL not connected');
+        });
+
+        it('should return Knex instance when connected', () => {
+            adapter.connect();
+            expect(adapter.getKnex()).toBeDefined();
+        });
+    });
+
+    describe('createRepository', () => {
+        beforeEach(() => {
+            adapter.connect();
+        });
+
+        it('should create a repository with all CRUD methods', () => {
+            const repo = adapter.createRepository({
+                table: 'users',
+                primaryKey: 'id',
+                columns: ['id', 'name', 'email'],
+            });
+
+            expect(repo).toBeDefined();
+            expect(typeof repo.create).toBe('function');
+            expect(typeof repo.findById).toBe('function');
+            expect(typeof repo.findAll).toBe('function');
+            expect(typeof repo.findPage).toBe('function');
+            expect(typeof repo.updateById).toBe('function');
+            expect(typeof repo.deleteById).toBe('function');
+            expect(typeof repo.count).toBe('function');
+            expect(typeof repo.exists).toBe('function');
+            // Bulk operations
+            expect(typeof repo.insertMany).toBe('function');
+            expect(typeof repo.updateMany).toBe('function');
+            expect(typeof repo.deleteMany).toBe('function');
+        });
+
+        it('should use default primary key when not specified', () => {
+            const repo = adapter.createRepository({
+                table: 'users',
+            });
+
+            expect(repo).toBeDefined();
+        });
+
+        it('should have insertMany method that returns array', async () => {
+            const repo = adapter.createRepository({ table: 'users' });
+
+            // Test that insertMany returns an array (mock returns array)
+            const result = await repo.insertMany([{ name: 'John' }, { name: 'Jane' }]);
+            expect(Array.isArray(result)).toBe(true);
+        });
+
+        it('should return empty array when insertMany with empty data', async () => {
+            const repo = adapter.createRepository({ table: 'users' });
+
+            const result = await repo.insertMany([]);
+            expect(result).toEqual([]);
+        });
+
+        it('should have updateMany method that returns count', async () => {
+            const repo = adapter.createRepository({ table: 'users' });
+
+            // updateMany method exists
+            expect(typeof repo.updateMany).toBe('function');
+        });
+
+        it('should have deleteMany method that returns count', async () => {
+            const repo = adapter.createRepository({ table: 'users' });
+
+            // deleteMany method exists
+            expect(typeof repo.deleteMany).toBe('function');
+        });
+    });
+
+    describe('withTransaction', () => {
+        beforeEach(() => {
+            adapter.connect();
+        });
+
+        it('should execute callback within transaction', async () => {
+            const mockCallback = jest.fn().mockResolvedValue({ success: true });
+
+            const result = await adapter.withTransaction(mockCallback);
+
+            expect(result).toEqual({ success: true });
+            expect(mockCallback).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    transaction: expect.any(Object),
+                    createRepository: expect.any(Function),
+                }),
+            );
+        });
+
+        it('should set statement timeout in transaction', async () => {
+            await adapter.withTransaction(async () => 'result', { timeout: 15000 });
+
+            expect(mockTrx.raw).toHaveBeenCalledWith('SET LOCAL statement_timeout = 15000');
+        });
+
+        it('should provide transaction context with createRepository', async () => {
+            let capturedContext: PostgresTransactionContext | undefined;
+
+            await adapter.withTransaction(async (ctx) => {
+                capturedContext = ctx;
+                return 'done';
+            });
+
+            expect(capturedContext).toBeDefined();
+            expect(capturedContext!.transaction).toBeDefined();
+            expect(typeof capturedContext!.createRepository).toBe('function');
+        });
+
+        it('should propagate errors from callback', async () => {
+            const error = new Error('Test error');
+
+            await expect(
+                adapter.withTransaction(async () => {
+                    throw error;
+                }),
+            ).rejects.toThrow('Test error');
+        });
+
+        it('should support isolation levels', async () => {
+            const mockTransaction = (mockKnexInstance as unknown as { transaction: jest.Mock }).transaction;
+
+            await adapter.withTransaction(
+                async () => 'result',
+                { isolationLevel: 'serializable' },
+            );
+
+            expect(mockTransaction).toHaveBeenCalledWith(
+                expect.any(Function),
+                { isolationLevel: 'serializable' },
+            );
+        });
+
+        it('should use default isolation level when not specified', async () => {
+            const mockTransaction = (mockKnexInstance as unknown as { transaction: jest.Mock }).transaction;
+
+            await adapter.withTransaction(async () => 'result');
+
+            expect(mockTransaction).toHaveBeenCalledWith(
+                expect.any(Function),
+                { isolationLevel: 'read committed' },
+            );
+        });
+    });
+
+    describe('healthCheck', () => {
+        it('should return unhealthy when not connected', async () => {
+            const result = await adapter.healthCheck();
+
+            expect(result.healthy).toBe(false);
+            expect(result.type).toBe('postgres');
+            expect(result.error).toBe('Not connected to PostgreSQL');
+            expect(result.responseTimeMs).toBeGreaterThanOrEqual(0);
+        });
+
+        it('should have healthCheck method', () => {
+            expect(typeof adapter.healthCheck).toBe('function');
+        });
+
+        it('should return response time in result', async () => {
+            const result = await adapter.healthCheck();
+
+            expect(typeof result.responseTimeMs).toBe('number');
+            expect(result.responseTimeMs).toBeGreaterThanOrEqual(0);
+        });
+
+        it('should return healthy result when connected', async () => {
+            // Create a fresh adapter and set up raw mock before health check
+            const freshAdapter = new PostgresAdapter(mockConfig);
+            freshAdapter.connect();
+
+            // The mock already returns an object for raw, so we just need to verify
+            // that healthCheck returns something when connected
+            const result = await freshAdapter.healthCheck();
+
+            expect(result.type).toBe('postgres');
+            expect(result.responseTimeMs).toBeGreaterThanOrEqual(0);
+            // Note: In real tests with actual DB, this would be true
+            // With mocks, we're just verifying the method works
+        });
+    });
+
+    describe('Soft Delete', () => {
+        it('should not have soft delete methods when softDelete is disabled', () => {
+            adapter.connect();
+            const repo = adapter.createRepository({ table: 'users', softDelete: false });
+
+            expect(repo.softDelete).toBeUndefined();
+            expect(repo.softDeleteMany).toBeUndefined();
+            expect(repo.restore).toBeUndefined();
+            expect(repo.restoreMany).toBeUndefined();
+            expect(repo.findAllWithDeleted).toBeUndefined();
+            expect(repo.findDeleted).toBeUndefined();
+        });
+
+        it('should have soft delete methods when softDelete is enabled', () => {
+            adapter.connect();
+            const repo = adapter.createRepository({ table: 'users', softDelete: true });
+
+            expect(typeof repo.softDelete).toBe('function');
+            expect(typeof repo.softDeleteMany).toBe('function');
+            expect(typeof repo.restore).toBe('function');
+            expect(typeof repo.restoreMany).toBe('function');
+            expect(typeof repo.findAllWithDeleted).toBe('function');
+            expect(typeof repo.findDeleted).toBe('function');
+        });
+
+        it('should soft delete a record by setting deleted_at', async () => {
+            adapter.connect();
+            const repo = adapter.createRepository({ table: 'users', softDelete: true });
+
+            await repo.softDelete!('123');
+
+            // Verify that update was called (soft delete sets timestamp instead of deleting)
+            const knexTableMock = mockKnexInstance as unknown as jest.Mock;
+            expect(knexTableMock).toHaveBeenCalledWith('users');
+        });
+
+        it('should use custom softDeleteField', () => {
+            adapter.connect();
+            const repo = adapter.createRepository({
+                table: 'users',
+                softDelete: true,
+                softDeleteField: 'removed_at',
+            });
+
+            // Verify soft delete methods are available with custom field
+            expect(typeof repo.softDelete).toBe('function');
+            expect(typeof repo.restore).toBe('function');
+        });
+
+        it('should provide restore method when soft delete is enabled', () => {
+            adapter.connect();
+            const repo = adapter.createRepository({ table: 'users', softDelete: true });
+
+            expect(typeof repo.restore).toBe('function');
+            expect(typeof repo.restoreMany).toBe('function');
+        });
+
+        it('should provide findDeleted method when soft delete is enabled', () => {
+            adapter.connect();
+            const repo = adapter.createRepository({ table: 'users', softDelete: true });
+
+            expect(typeof repo.findDeleted).toBe('function');
+        });
+
+        it('should provide findAllWithDeleted method when soft delete is enabled', () => {
+            adapter.connect();
+            const repo = adapter.createRepository({ table: 'users', softDelete: true });
+
+            expect(typeof repo.findAllWithDeleted).toBe('function');
+        });
+
+        it('should provide softDeleteMany method when soft delete is enabled', () => {
+            adapter.connect();
+            const repo = adapter.createRepository({ table: 'users', softDelete: true });
+
+            expect(typeof repo.softDeleteMany).toBe('function');
+        });
+
+        it('should have all soft delete methods defined correctly', () => {
+            adapter.connect();
+            const repo = adapter.createRepository({
+                table: 'users',
+                softDelete: true,
+                columns: ['id', 'name', 'deleted_at']
+            });
+
+            // All soft delete methods should be defined
+            expect(repo.softDelete).toBeDefined();
+            expect(repo.softDeleteMany).toBeDefined();
+            expect(repo.restore).toBeDefined();
+            expect(repo.restoreMany).toBeDefined();
+            expect(repo.findAllWithDeleted).toBeDefined();
+            expect(repo.findDeleted).toBeDefined();
+
+            // They should all be functions
+            expect(typeof repo.softDelete).toBe('function');
+            expect(typeof repo.softDeleteMany).toBe('function');
+            expect(typeof repo.restore).toBe('function');
+            expect(typeof repo.restoreMany).toBe('function');
+            expect(typeof repo.findAllWithDeleted).toBe('function');
+            expect(typeof repo.findDeleted).toBe('function');
+        });
+    });
+
+    describe('Timestamps', () => {
+        it('should accept timestamps configuration option', () => {
+            adapter.connect();
+            const repo = adapter.createRepository({
+                table: 'users',
+                timestamps: true,
+            });
+
+            expect(repo).toBeDefined();
+            expect(typeof repo.create).toBe('function');
+        });
+
+        it('should accept custom timestamp field names', () => {
+            adapter.connect();
+            const repo = adapter.createRepository({
+                table: 'users',
+                timestamps: true,
+                createdAtField: 'date_created',
+                updatedAtField: 'date_modified',
+            });
+
+            expect(repo).toBeDefined();
+        });
+
+        it('should have all CRUD methods when timestamps enabled', () => {
+            adapter.connect();
+            const repo = adapter.createRepository({
+                table: 'users',
+                timestamps: true,
+            });
+
+            expect(typeof repo.create).toBe('function');
+            expect(typeof repo.findById).toBe('function');
+            expect(typeof repo.findAll).toBe('function');
+            expect(typeof repo.findPage).toBe('function');
+            expect(typeof repo.updateById).toBe('function');
+            expect(typeof repo.deleteById).toBe('function');
+            expect(typeof repo.insertMany).toBe('function');
+            expect(typeof repo.updateMany).toBe('function');
+            expect(typeof repo.deleteMany).toBe('function');
+        });
+
+        it('should work with both timestamps and soft delete enabled', () => {
+            adapter.connect();
+            const repo = adapter.createRepository({
+                table: 'users',
+                timestamps: true,
+                softDelete: true,
+                columns: ['id', 'name', 'created_at', 'updated_at', 'deleted_at'],
+            });
+
+            expect(repo).toBeDefined();
+            expect(typeof repo.create).toBe('function');
+            expect(typeof repo.softDelete).toBe('function');
+            expect(typeof repo.restore).toBe('function');
+        });
+
+        it('should use default field names when not specified', () => {
+            adapter.connect();
+            // Default: created_at, updated_at for PostgreSQL
+            const repo = adapter.createRepository({
+                table: 'users',
+                timestamps: true,
+            });
+
+            expect(repo).toBeDefined();
+        });
+    });
+
+    describe('Advanced Query Operations', () => {
+        describe('findOne', () => {
+            it('should find one row by filter', async () => {
+                const mockRow = { id: 1, name: 'John', email: 'john@example.com' };
+                const mockQb = {
+                    select: jest.fn().mockReturnThis(),
+                    where: jest.fn().mockReturnThis(),
+                    whereNull: jest.fn().mockReturnThis(),
+                    first: jest.fn().mockResolvedValue(mockRow),
+                };
+
+                const mockKnex = jest.fn(() => mockQb) as unknown as Knex;
+                adapter['knexInstance'] = mockKnex;
+
+                const repo = adapter.createRepository({
+                    table: 'users',
+                    columns: ['id', 'name', 'email'],
+                });
+                const result = await repo.findOne({ email: 'john@example.com' });
+
+                expect(mockQb.select).toHaveBeenCalledWith('*');
+                expect(mockQb.where).toHaveBeenCalledWith('email', 'john@example.com');
+                expect(result).toEqual(mockRow);
+            });
+
+            it('should return null when findOne finds nothing', async () => {
+                const mockQb = {
+                    select: jest.fn().mockReturnThis(),
+                    where: jest.fn().mockReturnThis(),
+                    first: jest.fn().mockResolvedValue(undefined),
+                };
+
+                const mockKnex = jest.fn(() => mockQb) as unknown as Knex;
+                adapter['knexInstance'] = mockKnex;
+
+                const repo = adapter.createRepository({
+                    table: 'users',
+                    columns: ['email'],
+                });
+                const result = await repo.findOne({ email: 'nonexistent@example.com' });
+
+                expect(result).toBeNull();
+            });
+        });
+
+        describe('upsert', () => {
+            it('should update existing row', async () => {
+                const existingRow = { id: 1, name: 'John', email: 'john@example.com' };
+                const updatedRow = { id: 1, name: 'John Updated', email: 'john@example.com' };
+
+                const mockSelectQb = {
+                    select: jest.fn().mockReturnThis(),
+                    where: jest.fn().mockReturnThis(),
+                    first: jest.fn().mockResolvedValue(existingRow),
+                };
+
+                const mockUpdateQb = {
+                    where: jest.fn().mockReturnThis(),
+                    update: jest.fn().mockReturnThis(),
+                    returning: jest.fn().mockResolvedValue([updatedRow]),
+                };
+
+                let callCount = 0;
+                const mockKnex = jest.fn(() => {
+                    callCount++;
+                    return callCount === 1 ? mockSelectQb : mockUpdateQb;
+                }) as unknown as Knex;
+
+                adapter['knexInstance'] = mockKnex;
+
+                const repo = adapter.createRepository({
+                    table: 'users',
+                    columns: ['id', 'name', 'email'],
+                });
+                const result = await repo.upsert(
+                    { email: 'john@example.com' },
+                    { name: 'John Updated' },
+                );
+
+                expect(result).toEqual(updatedRow);
+            });
+
+            it('should insert new row when not exists', async () => {
+                const newRow = { id: 1, name: 'New User', email: 'new@example.com' };
+
+                const mockSelectQb = {
+                    select: jest.fn().mockReturnThis(),
+                    where: jest.fn().mockReturnThis(),
+                    first: jest.fn().mockResolvedValue(undefined),
+                };
+
+                const mockInsertQb = {
+                    insert: jest.fn().mockReturnThis(),
+                    returning: jest.fn().mockResolvedValue([newRow]),
+                };
+
+                let callCount = 0;
+                const mockKnex = jest.fn(() => {
+                    callCount++;
+                    return callCount === 1 ? mockSelectQb : mockInsertQb;
+                }) as unknown as Knex;
+
+                adapter['knexInstance'] = mockKnex;
+
+                const repo = adapter.createRepository({
+                    table: 'users',
+                    columns: ['id', 'name', 'email'],
+                });
+                const result = await repo.upsert(
+                    { email: 'new@example.com' },
+                    { name: 'New User' },
+                );
+
+                expect(result).toEqual(newRow);
+            });
+        });
+
+        describe('distinct', () => {
+            it('should return distinct values for a column', async () => {
+                const mockRows = [{ status: 'active' }, { status: 'pending' }];
+                const mockQb = {
+                    distinct: jest.fn().mockReturnThis(),
+                    modify: jest.fn().mockImplementation(function (this: unknown, fn: (qb: unknown) => void) {
+                        fn(this);
+                        return Promise.resolve(mockRows);
+                    }),
+                    where: jest.fn().mockReturnThis(),
+                };
+
+                const mockKnex = jest.fn(() => mockQb) as unknown as Knex;
+                adapter['knexInstance'] = mockKnex;
+
+                const repo = adapter.createRepository<TestUser>({
+                    table: 'users',
+                    columns: ['status'],
+                });
+                const result = await repo.distinct('status');
+
+                expect(mockQb.distinct).toHaveBeenCalledWith('status');
+                expect(result).toEqual(['active', 'pending']);
+            });
+        });
+
+        describe('select', () => {
+            it('should return rows with only selected columns', async () => {
+                const mockRows = [
+                    { name: 'John', email: 'john@example.com' },
+                    { name: 'Jane', email: 'jane@example.com' },
+                ];
+                const mockQb = {
+                    select: jest.fn().mockReturnThis(),
+                    where: jest.fn().mockReturnThis(),
+                    modify: jest.fn().mockImplementation(function (this: unknown, fn: (qb: unknown) => void) {
+                        fn(this);
+                        return Promise.resolve(mockRows);
+                    }),
+                };
+
+                const mockKnex = jest.fn(() => mockQb) as unknown as Knex;
+                adapter['knexInstance'] = mockKnex;
+
+                const repo = adapter.createRepository<TestUser>({
+                    table: 'users',
+                    columns: ['name', 'email', 'active'],
+                });
+                const result = await repo.select({ active: true }, ['name', 'email']);
+
+                expect(mockQb.select).toHaveBeenCalledWith(['name', 'email']);
+                expect(result).toEqual(mockRows);
+            });
+        });
+    });
+
+    describe('Repository Hooks', () => {
+        it('should call beforeCreate hook and use modified data', async () => {
+            const mockRow = { id: 1, name: 'MODIFIED' };
+            const mockQb = {
+                insert: jest.fn().mockReturnThis(),
+                returning: jest.fn().mockResolvedValue([mockRow]),
+            };
+
+            const mockKnex = jest.fn(() => mockQb) as unknown as Knex;
+            adapter['knexInstance'] = mockKnex;
+
+            const beforeCreate = jest.fn().mockImplementation((context) => ({
+                ...context.data,
+                name: 'MODIFIED',
+            }));
+
+            const repo = adapter.createRepository({
+                table: 'users',
+                hooks: { beforeCreate },
+            });
+            await repo.create({ name: 'Original' });
+
+            expect(beforeCreate).toHaveBeenCalledWith({
+                data: { name: 'Original' },
+                operation: 'create',
+                isBulk: false,
+            });
+            expect(mockQb.insert).toHaveBeenCalledWith(
+                expect.objectContaining({ name: 'MODIFIED' }),
+            );
+        });
+
+        it('should call afterCreate hook with created entity', async () => {
+            const mockRow = { id: 1, name: 'Test' };
+            const mockQb = {
+                insert: jest.fn().mockReturnThis(),
+                returning: jest.fn().mockResolvedValue([mockRow]),
+            };
+
+            const mockKnex = jest.fn(() => mockQb) as unknown as Knex;
+            adapter['knexInstance'] = mockKnex;
+
+            const afterCreate = jest.fn();
+
+            const repo = adapter.createRepository({
+                table: 'users',
+                hooks: { afterCreate },
+            });
+            await repo.create({ name: 'Test' });
+
+            expect(afterCreate).toHaveBeenCalledWith({ id: 1, name: 'Test' });
+        });
+
+        it('should call beforeUpdate hook and use modified data', async () => {
+            const mockRow = { id: 1, name: 'UPDATED' };
+            const mockQb = {
+                where: jest.fn().mockReturnThis(),
+                update: jest.fn().mockReturnThis(),
+                returning: jest.fn().mockResolvedValue([mockRow]),
+            };
+
+            const mockKnex = jest.fn(() => mockQb) as unknown as Knex;
+            adapter['knexInstance'] = mockKnex;
+
+            const beforeUpdate = jest.fn().mockImplementation((context) => ({
+                ...context.data,
+                name: 'UPDATED',
+            }));
+
+            const repo = adapter.createRepository({
+                table: 'users',
+                hooks: { beforeUpdate },
+            });
+            await repo.updateById(1, { name: 'Original' });
+
+            expect(beforeUpdate).toHaveBeenCalledWith({
+                data: { name: 'Original' },
+                operation: 'update',
+                isBulk: false,
+            });
+        });
+
+        it('should call afterUpdate hook with updated entity', async () => {
+            const mockRow = { id: 1, name: 'Updated' };
+            const mockQb = {
+                where: jest.fn().mockReturnThis(),
+                update: jest.fn().mockReturnThis(),
+                returning: jest.fn().mockResolvedValue([mockRow]),
+            };
+
+            const mockKnex = jest.fn(() => mockQb) as unknown as Knex;
+            adapter['knexInstance'] = mockKnex;
+
+            const afterUpdate = jest.fn();
+
+            const repo = adapter.createRepository({
+                table: 'users',
+                hooks: { afterUpdate },
+            });
+            await repo.updateById(1, { name: 'Updated' });
+
+            expect(afterUpdate).toHaveBeenCalledWith(mockRow);
+        });
+
+        it('should call beforeDelete hook with entity id', async () => {
+            const mockQb = {
+                where: jest.fn().mockReturnThis(),
+                delete: jest.fn().mockResolvedValue(1),
+            };
+
+            const mockKnex = jest.fn(() => mockQb) as unknown as Knex;
+            adapter['knexInstance'] = mockKnex;
+
+            const beforeDelete = jest.fn();
+
+            const repo = adapter.createRepository({
+                table: 'users',
+                hooks: { beforeDelete },
+            });
+            await repo.deleteById(1);
+
+            expect(beforeDelete).toHaveBeenCalledWith(1);
+        });
+
+        it('should call afterDelete hook with success status', async () => {
+            const mockQb = {
+                where: jest.fn().mockReturnThis(),
+                delete: jest.fn().mockResolvedValue(1),
+            };
+
+            const mockKnex = jest.fn(() => mockQb) as unknown as Knex;
+            adapter['knexInstance'] = mockKnex;
+
+            const afterDelete = jest.fn();
+
+            const repo = adapter.createRepository({
+                table: 'users',
+                hooks: { afterDelete },
+            });
+            await repo.deleteById(1);
+
+            expect(afterDelete).toHaveBeenCalledWith(true);
+        });
+
+        it('should call afterDelete with false when entity not found', async () => {
+            const mockQb = {
+                where: jest.fn().mockReturnThis(),
+                delete: jest.fn().mockResolvedValue(0),
+            };
+
+            const mockKnex = jest.fn(() => mockQb) as unknown as Knex;
+            adapter['knexInstance'] = mockKnex;
+
+            const afterDelete = jest.fn();
+
+            const repo = adapter.createRepository({
+                table: 'users',
+                hooks: { afterDelete },
+            });
+            await repo.deleteById(999);
+
+            expect(afterDelete).toHaveBeenCalledWith(false);
+        });
+    });
+});
diff --git a/src/adapters/postgres.adapter.ts b/src/adapters/postgres.adapter.ts
index 1b710c2..5f6cab6 100644
--- a/src/adapters/postgres.adapter.ts
+++ b/src/adapters/postgres.adapter.ts
@@ -1,13 +1,16 @@
-// src/adapters/postgres.adapter.ts
-
 import knex, { Knex } from 'knex';
 import { Injectable, Logger } from '@nestjs/common';
 import {
     PostgresDatabaseConfig,
     PostgresEntityConfig,
+    PostgresTransactionContext,
     Repository,
     PageResult,
     PageOptions,
+    TransactionOptions,
+    TransactionCallback,
+    HealthCheckResult,
+    DATABASE_KIT_CONSTANTS,
 } from '../contracts/database.contracts';
 
 /**
@@ -42,10 +45,20 @@ export class PostgresAdapter {
         if (!this.knexInstance) {
             this.logger.log('Creating PostgreSQL connection pool...');
 
+            // Apply pool configuration from config
+            const poolConfig = this.config.pool || {};
+            const pool = {
+                min: poolConfig.min ?? 0,
+                max: poolConfig.max ?? 10,
+                idleTimeoutMillis: poolConfig.idleTimeoutMs ?? 30000,
+                acquireTimeoutMillis: poolConfig.acquireTimeoutMs ?? 60000,
+            };
+
             this.knexInstance = knex({
                 client: 'pg',
                 connection: this.config.connectionString,
-                pool: { min: 0, max: 10 },
+                pool,
+                acquireConnectionTimeout: poolConfig.acquireTimeoutMs ?? 60000,
                 ...overrides,
             });
 
@@ -84,20 +97,157 @@ export class PostgresAdapter {
         return !!this.knexInstance;
     }
 
+    /**
+     * Performs a health check on the PostgreSQL connection.
+     * Executes a simple query to verify the database is responsive.
+     * 
+     * @returns Health check result with status and response time
+     * 
+     * @example
+     * ```typescript
+     * const health = await adapter.healthCheck();
+     * if (!health.healthy) {
+     *   console.error('Database unhealthy:', health.error);
+     * }
+     * ```
+     */
+    async healthCheck(): Promise<HealthCheckResult> {
+        const startTime = Date.now();
+
+        try {
+            if (!this.knexInstance) {
+                return {
+                    healthy: false,
+                    responseTimeMs: Date.now() - startTime,
+                    type: 'postgres',
+                    error: 'Not connected to PostgreSQL',
+                };
+            }
+
+            // Execute simple query to verify connection
+            const result = await this.knexInstance.raw('SELECT version(), current_database()');
+            const row = result.rows?.[0];
+
+            // Get pool info if available
+            const pool = (this.knexInstance.client as { pool?: { numUsed?: () => number; numFree?: () => number } }).pool;
+
+            return {
+                healthy: true,
+                responseTimeMs: Date.now() - startTime,
+                type: 'postgres',
+                details: {
+                    version: row?.version?.split(' ').slice(0, 2).join(' '),
+                    activeConnections: pool?.numUsed?.() ?? 0,
+                    poolSize: (pool?.numUsed?.() ?? 0) + (pool?.numFree?.() ?? 0),
+                },
+            };
+        } catch (error) {
+            return {
+                healthy: false,
+                responseTimeMs: Date.now() - startTime,
+                type: 'postgres',
+                error: error instanceof Error ? error.message : 'Unknown error',
+            };
+        }
+    }
+
     /**
      * Creates a repository for a PostgreSQL table.
      * The repository provides a standardized CRUD interface.
      * 
      * @param cfg - Configuration for the entity/table
+     * @param trx - Optional Knex transaction for transaction support
      * @returns Repository instance with CRUD methods
      */
-    createRepository<T = unknown>(cfg: PostgresEntityConfig): Repository<T> {
-        const kx = this.getKnex();
+    createRepository<T = unknown>(cfg: PostgresEntityConfig<T>, trx?: Knex.Transaction): Repository<T> {
+        const kx = trx || this.getKnex();
         const table = cfg.table;
         const pk = cfg.primaryKey || 'id';
         const allowed = cfg.columns || [];
         const baseFilter = cfg.defaultFilter || {};
 
+        // Soft delete configuration
+        const softDeleteEnabled = cfg.softDelete ?? false;
+        const softDeleteField = cfg.softDeleteField ?? 'deleted_at';
+
+        // Timestamp configuration
+        const timestampsEnabled = cfg.timestamps ?? false;
+        const createdAtField = cfg.createdAtField ?? 'created_at';
+        const updatedAtField = cfg.updatedAtField ?? 'updated_at';
+
+        // Hooks configuration
+        const hooks = cfg.hooks;
+
+        // Create not-deleted filter for soft delete
+        const notDeletedFilter: Record<string, unknown> = softDeleteEnabled
+            ? { [softDeleteField]: { isNull: true } }
+            : {};
+
+        // Helper to add createdAt timestamp
+        const addCreatedAt = <D extends Record<string, unknown>>(data: D): D => {
+            if (timestampsEnabled) {
+                return { ...data, [createdAtField]: new Date() };
+            }
+            return data;
+        };
+
+        // Helper to add updatedAt timestamp
+        const addUpdatedAt = <D extends Record<string, unknown>>(data: D): D => {
+            if (timestampsEnabled) {
+                return { ...data, [updatedAtField]: new Date() };
+            }
+            return data;
+        };
+
+        // Hook helper functions
+        const runBeforeCreate = async (data: Partial<T>): Promise<Partial<T>> => {
+            if (hooks?.beforeCreate) {
+                const result = await hooks.beforeCreate({
+                    data,
+                    operation: 'create',
+                    isBulk: false,
+                });
+                return result ?? data;
+            }
+            return data;
+        };
+
+        const runAfterCreate = async (entity: T): Promise<void> => {
+            if (hooks?.afterCreate) {
+                await hooks.afterCreate(entity);
+            }
+        };
+
+        const runBeforeUpdate = async (data: Partial<T>): Promise<Partial<T>> => {
+            if (hooks?.beforeUpdate) {
+                const result = await hooks.beforeUpdate({
+                    data,
+                    operation: 'update',
+                    isBulk: false,
+                });
+                return result ?? data;
+            }
+            return data;
+        };
+
+        const runAfterUpdate = async (entity: T | null): Promise<void> => {
+            if (hooks?.afterUpdate) {
+                await hooks.afterUpdate(entity);
+            }
+        };
+
+        const runBeforeDelete = async (id: string | number): Promise<void> => {
+            if (hooks?.beforeDelete) {
+                await hooks.beforeDelete(id);
+            }
+        };
+
+        const runAfterDelete = async (success: boolean): Promise<void> => {
+            if (hooks?.afterDelete) {
+                await hooks.afterDelete(success);
+            }
+        };
+
         const assertFieldAllowed = (field: string): void => {
             if (allowed.length && !allowed.includes(field)) {
                 throw new Error(
@@ -169,29 +319,48 @@ export class PostgresAdapter {
 
         const repo: Repository<T> = {
             async create(data: Partial<T>): Promise<T> {
-                const [row] = await kx(table).insert(data).returning('*');
-                return row as T;
+                // Run beforeCreate hook
+                let processedData = await runBeforeCreate(data);
+                processedData = addCreatedAt(processedData as Record<string, unknown>) as Partial<T>;
+
+                const [row] = await kx(table).insert(processedData).returning('*');
+                const entity = row as T;
+
+                // Run afterCreate hook
+                await runAfterCreate(entity);
+
+                return entity;
             },
 
             async findById(id: string | number): Promise<T | null> {
-                const row = await kx(table)
+                const mergedFilter = { ...baseFilter, ...notDeletedFilter };
+                const qb = kx(table)
                     .select('*')
-                    .where({ [pk]: id, ...baseFilter })
-                    .first();
+                    .where({ [pk]: id });
+                applyFilter(qb, mergedFilter);
+                const row = await qb.first();
                 return (row as T) || null;
             },
 
             async findAll(filter: Record<string, unknown> = {}): Promise<T[]> {
-                const mergedFilter = { ...baseFilter, ...filter };
+                const mergedFilter = { ...baseFilter, ...notDeletedFilter, ...filter };
                 const qb = kx(table).select('*');
                 applyFilter(qb, mergedFilter);
                 const rows = await qb;
                 return rows as T[];
             },
 
+            async findOne(filter: Record<string, unknown>): Promise<T | null> {
+                const mergedFilter = { ...baseFilter, ...notDeletedFilter, ...filter };
+                const qb = kx(table).select('*');
+                applyFilter(qb, mergedFilter);
+                const row = await qb.first();
+                return (row as T) || null;
+            },
+
             async findPage(options: PageOptions = {}): Promise<PageResult<T>> {
                 const { filter = {}, page = 1, limit = 10, sort } = options;
-                const mergedFilter = { ...baseFilter, ...filter };
+                const mergedFilter = { ...baseFilter, ...notDeletedFilter, ...filter };
 
                 const offset = Math.max(0, (page - 1) * limit);
 
@@ -210,23 +379,51 @@ export class PostgresAdapter {
             },
 
             async updateById(id: string | number, update: Partial<T>): Promise<T | null> {
-                const [row] = await kx(table)
-                    .where({ [pk]: id })
-                    .update(update)
-                    .returning('*');
-                return (row as T) || null;
+                // Run beforeUpdate hook
+                let processedUpdate = await runBeforeUpdate(update);
+                processedUpdate = addUpdatedAt(processedUpdate as Record<string, unknown>) as Partial<T>;
+
+                const mergedFilter = { ...baseFilter, ...notDeletedFilter };
+                const qb = kx(table)
+                    .where({ [pk]: id });
+                applyFilter(qb, mergedFilter);
+                const [row] = await qb.update(processedUpdate).returning('*');
+                const entity = (row as T) || null;
+
+                // Run afterUpdate hook
+                await runAfterUpdate(entity);
+
+                return entity;
             },
 
             async deleteById(id: string | number): Promise<boolean> {
-                const [row] = await kx(table)
-                    .where({ [pk]: id })
-                    .delete()
-                    .returning('*');
-                return !!row;
+                // Run beforeDelete hook
+                await runBeforeDelete(id);
+
+                const mergedFilter = { ...baseFilter, ...notDeletedFilter };
+                let success: boolean;
+
+                // If soft delete is enabled, update instead of delete
+                if (softDeleteEnabled) {
+                    const qb = kx(table).where({ [pk]: id });
+                    applyFilter(qb, mergedFilter);
+                    const affectedRows = await qb.update({ [softDeleteField]: new Date() });
+                    success = affectedRows > 0;
+                } else {
+                    const qb = kx(table).where({ [pk]: id });
+                    applyFilter(qb, mergedFilter);
+                    const affectedRows = await qb.delete();
+                    success = affectedRows > 0;
+                }
+
+                // Run afterDelete hook
+                await runAfterDelete(success);
+
+                return success;
             },
 
             async count(filter: Record<string, unknown> = {}): Promise<number> {
-                const mergedFilter = { ...baseFilter, ...filter };
+                const mergedFilter = { ...baseFilter, ...notDeletedFilter, ...filter };
                 const [{ count }] = await kx(table)
                     .count<{ count: string }[]>({ count: '*' })
                     .modify((q) => applyFilter(q, mergedFilter));
@@ -234,15 +431,283 @@ export class PostgresAdapter {
             },
 
             async exists(filter: Record<string, unknown> = {}): Promise<boolean> {
-                const mergedFilter = { ...baseFilter, ...filter };
+                const mergedFilter = { ...baseFilter, ...notDeletedFilter, ...filter };
                 const row = await kx(table)
                     .select([pk])
                     .modify((q) => applyFilter(q, mergedFilter))
                     .first();
                 return !!row;
             },
+
+            // -----------------------------
+            // Bulk Operations
+            // -----------------------------
+
+            async insertMany(data: Partial<T>[]): Promise<T[]> {
+                if (data.length === 0) return [];
+
+                // Add createdAt timestamp to each record
+                const timestampedData = data.map(item =>
+                    addCreatedAt(item as Record<string, unknown>)
+                );
+
+                const rows = await kx(table)
+                    .insert(timestampedData)
+                    .returning('*');
+
+                return rows as T[];
+            },
+
+            async updateMany(filter: Record<string, unknown>, update: Partial<T>): Promise<number> {
+                const mergedFilter = { ...baseFilter, ...notDeletedFilter, ...filter };
+                const timestampedUpdate = addUpdatedAt(update as Record<string, unknown>);
+
+                const affectedRows = await kx(table)
+                    .modify((q) => applyFilter(q, mergedFilter))
+                    .update(timestampedUpdate);
+
+                return affectedRows;
+            },
+
+            async deleteMany(filter: Record<string, unknown>): Promise<number> {
+                const mergedFilter = { ...baseFilter, ...notDeletedFilter, ...filter };
+
+                // If soft delete is enabled, update instead of delete
+                if (softDeleteEnabled) {
+                    const affectedRows = await kx(table)
+                        .modify((q) => applyFilter(q, mergedFilter))
+                        .update({ [softDeleteField]: new Date() });
+                    return affectedRows;
+                }
+
+                const affectedRows = await kx(table)
+                    .modify((q) => applyFilter(q, mergedFilter))
+                    .delete();
+
+                return affectedRows;
+            },
+
+            // -----------------------------
+            // Advanced Query Operations
+            // -----------------------------
+
+            async upsert(filter: Record<string, unknown>, data: Partial<T>): Promise<T> {
+                const mergedFilter = { ...baseFilter, ...notDeletedFilter, ...filter };
+
+                // Try to find existing record
+                const qb = kx(table).select('*');
+                applyFilter(qb, mergedFilter);
+                const existing = await qb.first();
+
+                if (existing) {
+                    // Update existing record
+                    const timestampedUpdate = addUpdatedAt(data as Record<string, unknown>);
+                    const updateQb = kx(table).where({ [pk]: existing[pk] });
+                    const [row] = await updateQb.update(timestampedUpdate).returning('*');
+                    return row as T;
+                } else {
+                    // Insert new record
+                    const timestampedData = addCreatedAt({ ...filter, ...data } as Record<string, unknown>);
+                    const [row] = await kx(table).insert(timestampedData).returning('*');
+                    return row as T;
+                }
+            },
+
+            async distinct<K extends keyof T>(field: K, filter: Record<string, unknown> = {}): Promise<T[K][]> {
+                const mergedFilter = { ...baseFilter, ...notDeletedFilter, ...filter };
+                const qb = kx(table)
+                    .distinct(String(field))
+                    .modify((q) => applyFilter(q, mergedFilter));
+                const rows = await qb;
+                return rows.map((row: Record<string, unknown>) => row[String(field)] as T[K]);
+            },
+
+            async select<K extends keyof T>(filter: Record<string, unknown>, fields: K[]): Promise<Pick<T, K>[]> {
+                const mergedFilter = { ...baseFilter, ...notDeletedFilter, ...filter };
+                const qb = kx(table)
+                    .select(fields.map(String))
+                    .modify((q) => applyFilter(q, mergedFilter));
+                const rows = await qb;
+                return rows as Pick<T, K>[];
+            },
+
+            // -----------------------------
+            // Soft Delete Operations
+            // -----------------------------
+
+            softDelete: softDeleteEnabled
+                ? async (id: string | number): Promise<boolean> => {
+                    const mergedFilter = { ...baseFilter, ...notDeletedFilter };
+                    const qb = kx(table).where({ [pk]: id });
+                    applyFilter(qb, mergedFilter);
+                    const affectedRows = await qb.update({ [softDeleteField]: new Date() });
+                    return affectedRows > 0;
+                }
+                : undefined,
+
+            softDeleteMany: softDeleteEnabled
+                ? async (filter: Record<string, unknown>): Promise<number> => {
+                    const mergedFilter = { ...baseFilter, ...notDeletedFilter, ...filter };
+                    const affectedRows = await kx(table)
+                        .modify((q) => applyFilter(q, mergedFilter))
+                        .update({ [softDeleteField]: new Date() });
+                    return affectedRows;
+                }
+                : undefined,
+
+            restore: softDeleteEnabled
+                ? async (id: string | number): Promise<T | null> => {
+                    const deletedFilter = { [softDeleteField]: { isNotNull: true } };
+                    const mergedFilter = { ...baseFilter, ...deletedFilter };
+                    const qb = kx(table).where({ [pk]: id });
+                    applyFilter(qb, mergedFilter);
+                    const [row] = await qb.update({ [softDeleteField]: null }).returning('*');
+                    return (row as T) || null;
+                }
+                : undefined,
+
+            restoreMany: softDeleteEnabled
+                ? async (filter: Record<string, unknown>): Promise<number> => {
+                    const deletedFilter = { [softDeleteField]: { isNotNull: true } };
+                    const mergedFilter = { ...baseFilter, ...deletedFilter, ...filter };
+                    const affectedRows = await kx(table)
+                        .modify((q) => applyFilter(q, mergedFilter))
+                        .update({ [softDeleteField]: null });
+                    return affectedRows;
+                }
+                : undefined,
+
+            findAllWithDeleted: softDeleteEnabled
+                ? async (filter: Record<string, unknown> = {}): Promise<T[]> => {
+                    // Ignore soft delete filter, include all records
+                    const mergedFilter = { ...baseFilter, ...filter };
+                    const qb = kx(table).select('*');
+                    applyFilter(qb, mergedFilter);
+                    const rows = await qb;
+                    return rows as T[];
+                }
+                : undefined,
+
+            findDeleted: softDeleteEnabled
+                ? async (filter: Record<string, unknown> = {}): Promise<T[]> => {
+                    // Only find deleted records
+                    const deletedFilter = { [softDeleteField]: { isNotNull: true } };
+                    const mergedFilter = { ...baseFilter, ...deletedFilter, ...filter };
+                    const qb = kx(table).select('*');
+                    applyFilter(qb, mergedFilter);
+                    const rows = await qb;
+                    return rows as T[];
+                }
+                : undefined,
         };
 
         return repo;
     }
+
+    /**
+     * Executes a callback within a PostgreSQL transaction.
+     * All database operations within the callback are atomic.
+     * 
+     * @param callback - Function to execute within the transaction
+     * @param options - Transaction options including isolation level
+     * @returns Result of the callback function
+     * @throws Error if transaction fails after all retries
+     * 
+     * @example
+     * ```typescript
+     * const result = await postgresAdapter.withTransaction(async (ctx) => {
+     *   const usersRepo = ctx.createRepository<User>({ table: 'users' });
+     *   const ordersRepo = ctx.createRepository<Order>({ table: 'orders' });
+     *   
+     *   const [user] = await usersRepo.create({ name: 'John' });
+     *   const [order] = await ordersRepo.create({ user_id: user.id, total: 100 });
+     *   
+     *   return { user, order };
+     * }, { isolationLevel: 'serializable' });
+     * ```
+     */
+    async withTransaction<TResult>(
+        callback: TransactionCallback<PostgresTransactionContext, TResult>,
+        options: TransactionOptions = {},
+    ): Promise<TResult> {
+        const {
+            isolationLevel = 'read committed',
+            retries = 0,
+            timeout = DATABASE_KIT_CONSTANTS.DEFAULT_TRANSACTION_TIMEOUT,
+        } = options;
+
+        const kx = this.getKnex();
+        let lastError: Error | undefined;
+
+        for (let attempt = 0; attempt <= retries; attempt++) {
+            try {
+                const result = await kx.transaction(
+                    async (trx) => {
+                        // Set statement timeout for the transaction
+                        await trx.raw(`SET LOCAL statement_timeout = ${timeout}`);
+
+                        const context: PostgresTransactionContext = {
+                            transaction: trx,
+                            createRepository: <T>(config: PostgresEntityConfig) =>
+                                this.createRepository<T>(config, trx),
+                        };
+
+                        return await callback(context);
+                    },
+                    { isolationLevel },
+                );
+
+                this.logger.debug(`Transaction committed successfully (attempt ${attempt + 1})`);
+                return result;
+            } catch (error) {
+                lastError = error as Error;
+
+                this.logger.warn(
+                    `Transaction failed (attempt ${attempt + 1}/${retries + 1}): ${lastError.message}`,
+                );
+
+                // Check if error is retryable
+                const isRetryable = this.isRetryableError(error);
+                if (!isRetryable || attempt >= retries) {
+                    throw lastError;
+                }
+
+                // Exponential backoff before retry
+                const backoffMs = Math.min(100 * Math.pow(2, attempt), 3000);
+                await this.sleep(backoffMs);
+            }
+        }
+
+        throw lastError || new Error('Transaction failed');
+    }
+
+    /**
+     * Checks if a PostgreSQL error is retryable.
+     */
+    private isRetryableError(error: unknown): boolean {
+        if (error && typeof error === 'object') {
+            const pgError = error as { code?: string; routine?: string };
+
+            // PostgreSQL serialization failure codes
+            const retryableCodes = [
+                '40001', // serialization_failure
+                '40P01', // deadlock_detected
+                '55P03', // lock_not_available
+                '57P01', // admin_shutdown
+                '57014', // query_canceled (timeout)
+            ];
+
+            if (pgError.code && retryableCodes.includes(pgError.code)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Simple sleep utility for retry backoff.
+     */
+    private sleep(ms: number): Promise<void> {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
 }
diff --git a/src/contracts/database.contracts.ts b/src/contracts/database.contracts.ts
index d50ddd8..4fd6e87 100644
--- a/src/contracts/database.contracts.ts
+++ b/src/contracts/database.contracts.ts
@@ -1,5 +1,3 @@
-// src/contracts/database.contracts.ts
-
 /**
  * Database configuration types and interfaces for DatabaseKit.
  * These contracts define the public API surface for the package.
@@ -14,6 +12,20 @@
  */
 export type DatabaseType = 'mongo' | 'postgres';
 
+/**
+ * Connection pool configuration options.
+ */
+export interface PoolConfig {
+    /** Minimum number of connections in the pool (default: 0 for Postgres, 5 for Mongo) */
+    min?: number;
+    /** Maximum number of connections in the pool (default: 10) */
+    max?: number;
+    /** Connection idle timeout in milliseconds (default: 30000) */
+    idleTimeoutMs?: number;
+    /** Connection acquire timeout in milliseconds (default: 60000) */
+    acquireTimeoutMs?: number;
+}
+
 /**
  * Base configuration for all database types.
  */
@@ -22,6 +34,8 @@ export interface DatabaseConfigBase {
     type: DatabaseType;
     /** Connection string for the database */
     connectionString: string;
+    /** Connection pool configuration */
+    pool?: PoolConfig;
 }
 
 /**
@@ -29,6 +43,10 @@ export interface DatabaseConfigBase {
  */
 export interface MongoDatabaseConfig extends DatabaseConfigBase {
     type: 'mongo';
+    /** Server selection timeout in milliseconds (default: 5000) */
+    serverSelectionTimeoutMS?: number;
+    /** Socket timeout in milliseconds (default: 45000) */
+    socketTimeoutMS?: number;
 }
 
 /**
@@ -36,6 +54,10 @@ export interface MongoDatabaseConfig extends DatabaseConfigBase {
  */
 export interface PostgresDatabaseConfig extends DatabaseConfigBase {
     type: 'postgres';
+    /** Statement timeout in milliseconds (default: none) */
+    statementTimeout?: number;
+    /** Query timeout in milliseconds (default: none) */
+    queryTimeout?: number;
 }
 
 /**
@@ -44,6 +66,67 @@ export interface PostgresDatabaseConfig extends DatabaseConfigBase {
  */
 export type DatabaseConfig = MongoDatabaseConfig | PostgresDatabaseConfig;
 
+// -----------------------------
+// Event Hooks Types
+// -----------------------------
+
+/**
+ * Hook context passed to event hooks.
+ */
+export interface HookContext<T = unknown> {
+    /** The entity data being operated on */
+    data: T;
+    /** The operation being performed */
+    operation: 'create' | 'update' | 'delete' | 'upsert';
+    /** Whether this is a bulk operation */
+    isBulk: boolean;
+}
+
+/**
+ * Event hooks for repository lifecycle events.
+ */
+export interface RepositoryHooks<T = unknown> {
+    /** Called before creating an entity. Can modify data. */
+    beforeCreate?(context: HookContext<Partial<T>>): Promise<Partial<T>> | Partial<T>;
+    /** Called after creating an entity. */
+    afterCreate?(entity: T): Promise<void> | void;
+    /** Called before updating an entity. Can modify data. */
+    beforeUpdate?(context: HookContext<Partial<T>>): Promise<Partial<T>> | Partial<T>;
+    /** Called after updating an entity. */
+    afterUpdate?(entity: T | null): Promise<void> | void;
+    /** Called before deleting an entity. */
+    beforeDelete?(id: string | number): Promise<void> | void;
+    /** Called after deleting an entity. */
+    afterDelete?(success: boolean): Promise<void> | void;
+}
+
+// -----------------------------
+// Health Check Types
+// -----------------------------
+
+/**
+ * Result of a database health check.
+ */
+export interface HealthCheckResult {
+    /** Whether the database is healthy and responding */
+    healthy: boolean;
+    /** Response time in milliseconds */
+    responseTimeMs: number;
+    /** Database type */
+    type: DatabaseType;
+    /** Error message if unhealthy */
+    error?: string;
+    /** Additional details about the connection */
+    details?: {
+        /** Database version (if available) */
+        version?: string;
+        /** Connection pool status */
+        poolSize?: number;
+        /** Number of active connections */
+        activeConnections?: number;
+    };
+}
+
 // -----------------------------
 // Pagination Types
 // -----------------------------
@@ -104,6 +187,13 @@ export interface Repository<T = unknown, Filter = Record<string, unknown>> {
      */
     findById(id: string | number): Promise<T | null>;
 
+    /**
+     * Finds a single entity matching the filter.
+     * @param filter - Filter criteria
+     * @returns The first matching entity or null
+     */
+    findOne(filter: Filter): Promise<T | null>;
+
     /**
      * Finds all entities matching the filter.
      * @param filter - Optional filter criteria
@@ -146,6 +236,113 @@ export interface Repository<T = unknown, Filter = Record<string, unknown>> {
      * @returns True if at least one entity matches
      */
     exists(filter?: Filter): Promise<boolean>;
+
+    // -----------------------------
+    // Bulk Operations
+    // -----------------------------
+
+    /**
+     * Creates multiple entities in a single operation.
+     * @param data - Array of partial entity data
+     * @returns Array of created entities
+     */
+    insertMany(data: Partial<T>[]): Promise<T[]>;
+
+    /**
+     * Updates multiple entities matching the filter.
+     * @param filter - Filter criteria to match entities
+     * @param update - Partial update data to apply
+     * @returns Number of entities updated
+     */
+    updateMany(filter: Filter, update: Partial<T>): Promise<number>;
+
+    /**
+     * Deletes multiple entities matching the filter.
+     * @param filter - Filter criteria to match entities
+     * @returns Number of entities deleted
+     */
+    deleteMany(filter: Filter): Promise<number>;
+
+    // -----------------------------
+    // Advanced Query Operations
+    // -----------------------------
+
+    /**
+     * Creates or updates an entity based on a filter.
+     * If entity exists, updates it; otherwise creates a new one.
+     * @param filter - Filter to find existing entity
+     * @param data - Data to create or update with
+     * @returns The created or updated entity
+     */
+    upsert(filter: Filter, data: Partial<T>): Promise<T>;
+
+    /**
+     * Returns distinct values for a specified field.
+     * @param field - The field to get distinct values for
+     * @param filter - Optional filter criteria
+     * @returns Array of distinct values
+     */
+    distinct<K extends keyof T>(field: K, filter?: Filter): Promise<T[K][]>;
+
+    /**
+     * Finds entities with specific fields only (projection).
+     * @param filter - Filter criteria
+     * @param fields - Array of field names to include
+     * @returns Array of entities with selected fields only
+     */
+    select<K extends keyof T>(filter: Filter, fields: K[]): Promise<Pick<T, K>[]>;
+
+    // -----------------------------
+    // Soft Delete Operations
+    // -----------------------------
+
+    /**
+     * Soft deletes an entity by setting deletedAt timestamp.
+     * Only available when softDelete option is enabled.
+     * @param id - The entity ID
+     * @returns True if soft deleted, false if not found
+     */
+    softDelete?(id: string | number): Promise<boolean>;
+
+    /**
+     * Soft deletes multiple entities matching the filter.
+     * Only available when softDelete option is enabled.
+     * @param filter - Filter criteria to match entities
+     * @returns Number of entities soft deleted
+     */
+    softDeleteMany?(filter: Filter): Promise<number>;
+
+    /**
+     * Restores a soft-deleted entity by clearing deletedAt.
+     * Only available when softDelete option is enabled.
+     * @param id - The entity ID
+     * @returns The restored entity or null if not found
+     */
+    restore?(id: string | number): Promise<T | null>;
+
+    /**
+     * Restores multiple soft-deleted entities matching the filter.
+     * Only available when softDelete option is enabled.
+     * @param filter - Filter criteria to match entities
+     * @returns Number of entities restored
+     */
+    restoreMany?(filter: Filter): Promise<number>;
+
+    /**
+     * Finds all entities including soft-deleted ones.
+     * Only available when softDelete option is enabled.
+     * @param filter - Optional filter criteria
+     * @returns Array of all matching entities (including deleted)
+     */
+    findAllWithDeleted?(filter?: Filter): Promise<T[]>;
+
+    /**
+     * Finds only soft-deleted entities.
+     * Only available when softDelete option is enabled.
+     * @param filter - Optional filter criteria
+     * @returns Array of soft-deleted entities
+     */
+    findDeleted?(filter?: Filter): Promise<T[]>;
 }
 
 // -----------------------------
@@ -155,15 +352,41 @@ export interface Repository<T = unknown, Filter = Record<string, unknown>> {
 /**
  * Options for creating a MongoDB repository.
  */
-export interface MongoRepositoryOptions {
+export interface MongoRepositoryOptions<T = unknown> {
     /** Mongoose Model instance */
     model: unknown; // Using unknown to avoid Mongoose type dependency
+    /**
+     * Enable soft delete pattern.
+     * When enabled, deleteById/deleteMany will set deletedAt instead of removing.
+     */
+    softDelete?: boolean;
+    /**
+     * Field name for soft delete timestamp (default: 'deletedAt').
+     */
+    softDeleteField?: string;
+    /**
+     * Enable automatic timestamps (createdAt/updatedAt).
+     * When enabled, create will set createdAt and all updates will set updatedAt.
+     */
+    timestamps?: boolean;
+    /**
+     * Field name for created timestamp (default: 'createdAt').
+     */
+    createdAtField?: string;
+    /**
+     * Field name for updated timestamp (default: 'updatedAt').
+     */
+    updatedAtField?: string;
+    /**
+     * Lifecycle hooks for repository operations.
+     */
+    hooks?: RepositoryHooks<T>;
 }
 
 /**
  * Options for creating a PostgreSQL repository.
  */
-export interface PostgresEntityConfig {
+export interface PostgresEntityConfig<T = unknown> {
     /** Table name in PostgreSQL */
     table: string;
     /** Primary key column (default: "id") */
@@ -178,6 +401,32 @@ export interface PostgresEntityConfig {
      * Useful for soft-delete patterns (e.g., { is_deleted: false }).
      */
     defaultFilter?: Record<string, unknown>;
+    /**
+     * Enable soft delete pattern.
+     * When enabled, deleteById/deleteMany will set deletedAt instead of removing.
+     */
+    softDelete?: boolean;
+    /**
+     * Field name for soft delete timestamp (default: 'deleted_at').
+     */
+    softDeleteField?: string;
+    /**
+     * Enable automatic timestamps (created_at/updated_at).
+     * When enabled, create will set created_at and all updates will set updated_at.
+     */
+    timestamps?: boolean;
+    /**
+     * Field name for created timestamp (default: 'created_at').
+     */
+    createdAtField?: string;
+    /**
+     * Field name for updated timestamp (default: 'updated_at').
+     */
+    updatedAtField?: string;
+    /**
+     * Lifecycle hooks for repository operations.
+     */
+    hooks?: RepositoryHooks<T>;
 }
 
 // -----------------------------
@@ -220,6 +469,83 @@ export interface DatabaseKitModuleAsyncOptions {
     inject?: Array<InjectionToken | OptionalFactoryDependency>;
 }
 
+// -----------------------------
+// Transaction Types
+// -----------------------------
+
+/**
+ * Transaction isolation levels supported by PostgreSQL.
+ * MongoDB doesn't support isolation levels in the same way.
+ */
+export type TransactionIsolationLevel =
+    | 'read uncommitted'
+    | 'read committed'
+    | 'repeatable read'
+    | 'serializable';
+
+/**
+ * Options for transaction execution.
+ */
+export interface TransactionOptions {
+    /**
+     * Isolation level for the transaction (PostgreSQL only).
+     * Default: 'read committed'
+     */
+    isolationLevel?: TransactionIsolationLevel;
+    /**
+     * Maximum time in milliseconds to wait for the transaction to complete.
+     * Default: 30000 (30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Number of retry attempts on transient failures.
+     * Default: 0 (no retries)
+     */
+    retries?: number;
+}
+
+/**
+ * Context passed to transaction callback functions.
+ * Contains transaction-aware repository factory.
+ */
+export interface TransactionContext<TAdapter = unknown> {
+    /**
+     * The underlying transaction object.
+     * - For MongoDB: ClientSession
+     * - For PostgreSQL: Knex.Transaction
+     */
+    transaction: TAdapter;
+}
+
+/**
+ * MongoDB-specific transaction context.
+ */
+export interface MongoTransactionContext extends TransactionContext {
+    /**
+     * Creates a transaction-aware repository.
+     * All operations on this repository will be part of the transaction.
+     */
+    createRepository: <T>(options: MongoRepositoryOptions) => Repository<T>;
+}
+
+/**
+ * PostgreSQL-specific transaction context.
+ */
+export interface PostgresTransactionContext extends TransactionContext {
+    /**
+     * Creates a transaction-aware repository.
+     * All operations on this repository will be part of the transaction.
+     */
+    createRepository: <T>(config: PostgresEntityConfig) => Repository<T>;
+}
+
+/**
+ * Callback function type for transaction execution.
+ */
+export type TransactionCallback<TContext, TResult> = (
+    context: TContext,
+) => Promise<TResult>;
+
 // -----------------------------
 // Constants
 // -----------------------------
@@ -236,4 +562,6 @@ export const DATABASE_KIT_CONSTANTS = {
     DEFAULT_POOL_SIZE: 10,
     /** Default connection timeout in milliseconds */
     DEFAULT_CONNECTION_TIMEOUT: 5000,
+    /** Default transaction timeout in milliseconds */
+    DEFAULT_TRANSACTION_TIMEOUT: 30000,
 } as const;
diff --git a/src/index.ts b/src/index.ts
index 15bbaaf..81962dc 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -56,6 +56,9 @@ export {
     MongoDatabaseConfig,
     PostgresDatabaseConfig,
 
+    // Pool configuration
+    PoolConfig,
+
     // Module configuration
     DatabaseKitModuleOptions,
     DatabaseKitModuleAsyncOptions,
@@ -69,6 +72,21 @@ export {
     PageResult,
     PageOptions,
 
+    // Transaction types
+    TransactionIsolationLevel,
+    TransactionOptions,
+    TransactionContext,
+    MongoTransactionContext,
+    PostgresTransactionContext,
+    TransactionCallback,
+
+    // Health check types
+    HealthCheckResult,
+
+    // Event hooks
+    HookContext,
+    RepositoryHooks,
+
     // Repository options
     MongoRepositoryOptions,
     PostgresEntityConfig,
diff --git a/src/services/database.service.spec.ts b/src/services/database.service.spec.ts
index f3eef42..e7af992 100644
--- a/src/services/database.service.spec.ts
+++ b/src/services/database.service.spec.ts
@@ -38,6 +38,22 @@ describe('DatabaseService', () => {
                 }),
             ).toThrow('Database type is "mongo"');
         });
+
+        it('should throw when using withPostgresTransaction with mongo config', async () => {
+            await expect(
+                service.withPostgresTransaction(async () => {
+                    return 'test';
+                }),
+            ).rejects.toThrow('Database type is "mongo"');
+        });
+
+        it('should have withMongoTransaction method', () => {
+            expect(typeof service.withMongoTransaction).toBe('function');
+        });
+
+        it('should have withTransaction method', () => {
+            expect(typeof service.withTransaction).toBe('function');
+        });
     });
 
     describe('PostgreSQL', () => {
@@ -70,5 +86,43 @@ describe('DatabaseService', () => {
                 }),
             ).toThrow('Database type is "postgres"');
         });
+
+        it('should throw when using withMongoTransaction with postgres config', async () => {
+            await expect(
+                service.withMongoTransaction(async () => {
+                    return 'test';
+                }),
+            ).rejects.toThrow('Database type is "postgres"');
+        });
+
+        it('should have withPostgresTransaction method', () => {
+            expect(typeof service.withPostgresTransaction).toBe('function');
+        });
+
+        it('should have withTransaction method', () => {
+            expect(typeof service.withTransaction).toBe('function');
+        });
+
+        it('should have healthCheck method', () => {
+            expect(typeof service.healthCheck).toBe('function');
+        });
+    });
+
+    describe('Health Check', () => {
+        it('should have healthCheck method on mongo service', () => {
+            const mongoService = new DatabaseService({
+                type: 'mongo',
+                connectionString: 'mongodb://localhost:27017/testdb',
+            });
+            expect(typeof mongoService.healthCheck).toBe('function');
+        });
+
+        it('should have healthCheck method on postgres service', () => {
+            const pgService = new DatabaseService({
+                type: 'postgres',
+                connectionString: 'postgresql://localhost:5432/testdb',
+            });
+            expect(typeof pgService.healthCheck).toBe('function');
+        });
     });
 });
diff --git a/src/services/database.service.ts b/src/services/database.service.ts
index b304462..c9e2152 100644
--- a/src/services/database.service.ts
+++ b/src/services/database.service.ts
@@ -1,5 +1,3 @@
-// src/services/database.service.ts
-
 import { Injectable, Logger, OnModuleDestroy } from '@nestjs/common';
 import {
     DatabaseConfig,
@@ -7,7 +5,12 @@ import {
     PostgresDatabaseConfig,
     MongoRepositoryOptions,
     PostgresEntityConfig,
+    MongoTransactionContext,
+    PostgresTransactionContext,
     Repository,
+    TransactionOptions,
+    TransactionCallback,
+    HealthCheckResult,
 } from '../contracts/database.contracts';
 import { MongoAdapter } from '../adapters/mongo.adapter';
 import { PostgresAdapter } from '../adapters/postgres.adapter';
@@ -222,4 +225,150 @@ export class DatabaseService implements OnModuleDestroy {
 
         return this.postgresAdapter;
     }
+
+    /**
+     * Executes a callback within a MongoDB transaction.
+     * All database operations within the callback are atomic.
+     * 
+     * **Note:** MongoDB transactions require a replica set.
+     * 
+     * @param callback - Function to execute within the transaction
+     * @param options - Transaction options
+     * @returns Result of the callback function
+     * @throws Error if database type is not 'mongo' or transaction fails
+     * 
+     * @example
+     * ```typescript
+     * const result = await db.withMongoTransaction(async (ctx) => {
+     *   const usersRepo = ctx.createRepository<User>({ model: UserModel });
+     *   const user = await usersRepo.create({ name: 'John' });
+     *   return user;
+     * });
+     * ```
+     */
+    async withMongoTransaction<TResult>(
+        callback: TransactionCallback<MongoTransactionContext, TResult>,
+        options?: TransactionOptions,
+    ): Promise<TResult> {
+        if (this.config.type !== 'mongo') {
+            throw new Error(
+                `Database type is "${this.config.type}". withMongoTransaction can only be used when type === "mongo".`,
+            );
+        }
+
+        const adapter = this.getMongoAdapter();
+        return adapter.withTransaction(callback, options);
+    }
+
+    /**
+     * Executes a callback within a PostgreSQL transaction.
+     * All database operations within the callback are atomic.
+     * 
+     * @param callback - Function to execute within the transaction
+     * @param options - Transaction options including isolation level
+     * @returns Result of the callback function
+     * @throws Error if database type is not 'postgres' or transaction fails
+     * 
+     * @example
+     * ```typescript
+     * const result = await db.withPostgresTransaction(async (ctx) => {
+     *   const usersRepo = ctx.createRepository<User>({ table: 'users' });
+     *   const user = await usersRepo.create({ name: 'John' });
+     *   return user;
+     * }, { isolationLevel: 'serializable' });
+     * ```
+     */
+    async withPostgresTransaction<TResult>(
+        callback: TransactionCallback<PostgresTransactionContext, TResult>,
+        options?: TransactionOptions,
+    ): Promise<TResult> {
+        if (this.config.type !== 'postgres') {
+            throw new Error(
+                `Database type is "${this.config.type}". withPostgresTransaction can only be used when type === "postgres".`,
+            );
+        }
+
+        const adapter = this.getPostgresAdapter();
+        return adapter.withTransaction(callback, options);
+    }
+
+    /**
+     * Generic transaction method that works with the configured database type.
+     * Automatically routes to the appropriate transaction handler.
+     * 
+     * @param callback - Function to execute within the transaction
+     * @param options - Transaction options
+     * @returns Result of the callback function
+     * 
+     * @example
+     * ```typescript
+     * // Works with whatever database type is configured
+     * const result = await db.withTransaction(async (ctx) => {
+     *   const repo = ctx.createRepository({ ... });
+     *   return repo.create({ name: 'John' });
+     * });
+     * ```
+     */
+    async withTransaction<TResult>(
+        callback: TransactionCallback<MongoTransactionContext | PostgresTransactionContext, TResult>,
+        options?: TransactionOptions,
+    ): Promise<TResult> {
+        switch (this.config.type) {
+            case 'mongo':
+                return this.withMongoTransaction(
+                    callback as TransactionCallback<MongoTransactionContext, TResult>,
+                    options,
+                );
+            case 'postgres':
+                return this.withPostgresTransaction(
+                    callback as TransactionCallback<PostgresTransactionContext, TResult>,
+                    options,
+                );
+            default: {
+                const exhaustiveCheck: never = this.config;
+                throw new Error(`Unsupported database type: ${(exhaustiveCheck as DatabaseConfig).type}`);
+            }
+        }
+    }
+
+    /**
+     * Performs a health check on the database connection.
+     * Useful for load balancer health endpoints and monitoring.
+     * 
+     * @returns Health check result with status, response time, and details
+     * 
+     * @example
+     * ```typescript
+     * // In a health check endpoint
+     * @Get('/health')
+     * async healthCheck() {
+     *   const result = await this.db.healthCheck();
+     *   if (!result.healthy) {
+     *     throw new ServiceUnavailableException(result.error);
+     *   }
+     *   return result;
+     * }
+     * ```
+     */
+    async healthCheck(): Promise<HealthCheckResult> {
+        switch (this.config.type) {
+            case 'mongo': {
+                const adapter = this.getMongoAdapter();
+                return adapter.healthCheck();
+            }
+            case 'postgres': {
+                const adapter = this.getPostgresAdapter();
+                return adapter.healthCheck();
+            }
+            default: {
+                const exhaustiveCheck: never = this.config;
+                return {
+                    healthy: false,
+                    responseTimeMs: 0,
+                    type: (exhaustiveCheck as DatabaseConfig).type,
+                    error: `Unsupported database type: ${(exhaustiveCheck as DatabaseConfig).type}`,
+                };
+            }
+        }
+    }
 }