docs: split api_reference into per-module subdirectories and update examples

Restructure the API reference docs by breaking the monolithic adapters.md,
helpers.md, models.md, and utils.md files into dedicated per-module
subdirectories (adapters/, helpers/, models/), each with an index and
individual pages per component. Update mkdocs config and example pages
accordingly.

Author: HosseinNejatiJavaremi

docs/api_reference/adapters.md

@@ -0,0 +1,48 @@
+# Base SQLAlchemy
+
+The `base/sqlalchemy` subpackage provides the foundational SQLAlchemy components shared across all relational database adapters, including the abstract port interface, session managers, and session manager registries.
+
+## ports
+
+Abstract port interface defining the contract all SQLAlchemy-based adapters must fulfil.
+
+::: archipy.adapters.base.sqlalchemy.ports
+    options:
+      show_root_heading: true
+      show_source: true
+
+## session_manager_ports
+
+Abstract interface for SQLAlchemy session managers, decoupling session lifecycle from adapter logic.
+
+::: archipy.adapters.base.sqlalchemy.session_manager_ports
+    options:
+      show_root_heading: true
+      show_source: true
+
+## session_manager_registry
+
+Registry for tracking and resolving active session manager instances.
+
+::: archipy.adapters.base.sqlalchemy.session_manager_registry
+    options:
+      show_root_heading: true
+      show_source: true
+
+## session_managers
+
+Concrete session manager implementations that handle SQLAlchemy session creation, scoping, and teardown.
+
+::: archipy.adapters.base.sqlalchemy.session_managers
+    options:
+      show_root_heading: true
+      show_source: true
+
+## adapters
+
+The base SQLAlchemy adapter implements generic CRUD operations that concrete database adapters (PostgreSQL, SQLite, StarRocks) inherit from.
+
+::: archipy.adapters.base.sqlalchemy.adapters
+    options:
+      show_root_heading: true
+      show_source: true

docs/api_reference/adapters/base.md

@@ -0,0 +1,21 @@
+# Elasticsearch
+
+The `elasticsearch` adapter provides integration with Elasticsearch for full-text search, document indexing, and analytics queries.
+
+## ports
+
+Abstract port interface defining the Elasticsearch adapter contract.
+
+::: archipy.adapters.elasticsearch.ports
+    options:
+      show_root_heading: true
+      show_source: true
+
+## adapters
+
+Concrete Elasticsearch adapter implementing index management, document CRUD, and search operations.
+
+::: archipy.adapters.elasticsearch.adapters
+    options:
+      show_root_heading: true
+      show_source: true

docs/api_reference/adapters/elasticsearch.md

@@ -0,0 +1,21 @@
+# Email
+
+The `email` adapter provides integration with email services for sending transactional and notification emails.
+
+## ports
+
+Abstract port interface defining the email adapter contract.
+
+::: archipy.adapters.email.ports
+    options:
+      show_root_heading: true
+      show_source: true
+
+## adapters
+
+Concrete email adapter implementing SMTP-based email sending with ArchiPy conventions.
+
+::: archipy.adapters.email.adapters
+    options:
+      show_root_heading: true
+      show_source: true

docs/api_reference/adapters/email.md

@@ -0,0 +1,45 @@
+# Adapters
+
+The `adapters` module provides concrete implementations of external system integrations following the Ports & Adapters pattern. Each adapter directory exposes a `ports.py` (abstract interface) and an `adapters.py` (concrete implementation).
+
+## Submodules
+
+| Adapter | Description |
+|---|---|
+| [Base SQLAlchemy](base.md) | Shared SQLAlchemy session management and base CRUD adapter |
+| [Redis](redis.md) | Redis cache and key-value store adapter |
+| [PostgreSQL](postgres.md) | PostgreSQL database adapter via SQLAlchemy |
+| [SQLite](sqlite.md) | SQLite database adapter via SQLAlchemy |
+| [StarRocks](starrocks.md) | StarRocks analytical database adapter via SQLAlchemy |
+| [Kafka](kafka.md) | Apache Kafka message streaming adapter |
+| [Keycloak](keycloak.md) | Keycloak identity and access management adapter |
+| [MinIO](minio.md) | MinIO object storage adapter |
+| [ScyllaDB](scylladb.md) | ScyllaDB/Cassandra wide-column store adapter |
+| [Elasticsearch](elasticsearch.md) | Elasticsearch search engine adapter |
+| [Temporal](temporal.md) | Temporal workflow orchestration adapter |
+| [Email](email.md) | Email service adapter |
+| [Payment Gateways](payment_gateways.md) | Internet payment gateway adapters (Parsian Shaparak) |
+
+## Source Code
+
+📁 Location: `archipy/adapters/`
+
+🔗 [Browse Source](https://github.com/SyntaxArc/ArchiPy/tree/master/archipy/adapters)
+
+## API Stability
+
+| Adapter | Status | Notes |
+|---|---|---|
+| Base SQLAlchemy | 🟢 Stable | Production-ready |
+| Redis | 🟢 Stable | Production-ready |
+| PostgreSQL | 🟢 Stable | Production-ready |
+| SQLite | 🟢 Stable | Production-ready |
+| StarRocks | 🟡 Beta | API may change |
+| Kafka | 🟢 Stable | Production-ready |
+| Keycloak | 🟢 Stable | Production-ready |
+| MinIO | 🟢 Stable | Production-ready |
+| ScyllaDB | 🟢 Stable | Production-ready |
+| Elasticsearch | 🟢 Stable | Production-ready |
+| Temporal | 🟢 Stable | Production-ready |
+| Email | 🟢 Stable | Production-ready |
+| Payment Gateways | 🟢 Stable | Production-ready |

docs/api_reference/adapters/index.md

@@ -0,0 +1,21 @@
+# Kafka
+
+The `kafka` adapter provides integration with Apache Kafka for producing and consuming messages in event-driven architectures.
+
+## ports
+
+Abstract port interface defining the Kafka adapter contract for message production and consumption.
+
+::: archipy.adapters.kafka.ports
+    options:
+      show_root_heading: true
+      show_source: true
+
+## adapters
+
+Concrete Kafka adapter implementing producer and consumer patterns with ArchiPy conventions.
+
+::: archipy.adapters.kafka.adapters
+    options:
+      show_root_heading: true
+      show_source: true

docs/api_reference/adapters/kafka.md

@@ -0,0 +1,21 @@
+# Keycloak
+
+The `keycloak` adapter provides integration with Keycloak for identity and access management, including token validation, user management, and role-based access control.
+
+## ports
+
+Abstract port interface defining the Keycloak adapter contract.
+
+::: archipy.adapters.keycloak.ports
+    options:
+      show_root_heading: true
+      show_source: true
+
+## adapters
+
+Concrete Keycloak adapter wrapping the Keycloak REST API for authentication and authorization operations.
+
+::: archipy.adapters.keycloak.adapters
+    options:
+      show_root_heading: true
+      show_source: true

docs/api_reference/adapters/keycloak.md

@@ -0,0 +1,21 @@
+# MinIO
+
+The `minio` adapter provides integration with MinIO (and S3-compatible object storage) for uploading, downloading, and managing binary objects.
+
+## ports
+
+Abstract port interface defining the MinIO adapter contract for object storage operations.
+
+::: archipy.adapters.minio.ports
+    options:
+      show_root_heading: true
+      show_source: true
+
+## adapters
+
+Concrete MinIO adapter wrapping the MinIO Python SDK with ArchiPy conventions for object storage operations.
+
+::: archipy.adapters.minio.adapters
+    options:
+      show_root_heading: true
+      show_source: true

docs/api_reference/adapters/minio.md

@@ -0,0 +1,14 @@
+# Payment Gateways
+
+The `internet_payment_gateways` adapter provides integration with internet payment gateways. Currently supports Parsian Shaparak, an Iranian payment gateway.
+
+## Parsian Shaparak
+
+### adapters
+
+Concrete Parsian Shaparak payment gateway adapter implementing payment initiation, verification, and reversal.
+
+::: archipy.adapters.internet_payment_gateways.ir.parsian.adapters
+    options:
+      show_root_heading: true
+      show_source: true

docs/api_reference/adapters/payment_gateways.md

@@ -0,0 +1,30 @@
+# PostgreSQL
+
+The `postgres/sqlalchemy` adapter provides a PostgreSQL-specific SQLAlchemy integration, including a concrete adapter, session manager, and session manager registry that extend the base SQLAlchemy components.
+
+## session_managers
+
+PostgreSQL-specific session manager handling connection pooling and lifecycle for PostgreSQL databases.
+
+::: archipy.adapters.postgres.sqlalchemy.session_managers
+    options:
+      show_root_heading: true
+      show_source: true
+
+## session_manager_registry
+
+Registry for PostgreSQL session manager instances.
+
+::: archipy.adapters.postgres.sqlalchemy.session_manager_registry
+    options:
+      show_root_heading: true
+      show_source: true
+
+## adapters
+
+Concrete PostgreSQL adapter built on top of the base SQLAlchemy adapter with PostgreSQL-specific configuration.
+
+::: archipy.adapters.postgres.sqlalchemy.adapters
+    options:
+      show_root_heading: true
+      show_source: true