Request Lifecycle
- Introduction
- Lifecycle Overview Diagram
- First Steps: Ingress & Octane Server
- HTTP Middleware & Normalization
- Thin Controllers & Form Requests
- Domain Actions & Dynamic Model Resolution
- Concurrency, Database Transactions & Ledger
- Response Serialization
Introduction
When using any tool in the "real world", you feel more confident if you understand how that tool works. Application development is no different. When you understand how a request flows through the Reyhan Commerce headless engine, everything feels more approachable and extensible.
As a 100% headless commerce framework, Reyhan's request lifecycle follows a decoupled, highly performant path optimized for Laravel Octane (FrankenPHP), native database transactions, and sub-millisecond in-memory cache operations.
Lifecycle Overview Diagram
First Steps: Ingress & Octane Server
The entry point for all requests to a Reyhan Commerce application is the public/index.php file. All requests are directed to this file by your web server (Caddy, Nginx, or FrankenPHP).
Under Laravel Octane, application bootstrapping occurs in worker memory once upon server start. Subsequent HTTP requests execute directly against pre-warmed service providers and container bindings, resulting in microsecond response latencies.
HTTP Middleware & Normalization
Every incoming request passes through global and route-specific middleware pipelines:
- CORS & Origin Validation: Verifies stateful domain origins against
CORS_ALLOWED_ORIGINSandSANCTUM_STATEFUL_DOMAINS. - Text & Digit Normalization: Automatically standardizes input characters:
- Converts Persian and Arabic numerals (
۰-۹,٠-٩) in mobile numbers, national IDs, and quantities into ASCII digits (0-9). - Unifies Arabic characters (
ي,ك) to Persian (ی,ک). - Sanitizes Zero-Width Non-Joiners (ZWNJ).
- Converts Persian and Arabic numerals (
- Authentication & Rate Limiting: Evaluates customer Sanctum Bearer tokens and OTP attempt rate limits.
Thin Controllers & Form Requests
In adherence to clean architecture principles, controllers in Reyhan are strictly thin:
- Controllers never execute raw database queries.
- Controllers never contain inline business calculations or order placement logic.
- Incoming payloads are validated via Form Requests and cast into strongly-typed Data Transfer Objects (DTOs):
public function store(CreateOrderRequest $request, CreateOrderAction $action): JsonResponse
{
$dto = CreateOrderData::from($request->validated());
$result = $action->execute($request->user(), $dto);
return OrderResource::make($result->order)
->response()
->setStatusCode(201);
}Domain Actions & Dynamic Model Resolution
Business logic is encapsulated entirely within final Action classes under Reyhan\Core\Actions (or app/Actions in your application). When an Action executes:
- Dynamic Model Resolution: Resolves model classes through
Reyhan::model('product'), guaranteeing that custom models, attributes, and relationships are respected automatically. - Pipeline Execution: Passes payloads through configured domain pipelines (such as
checkoutorpricing).
Concurrency, Database Transactions & Ledger
Reyhan implements a battle-tested Two-Tier Concurrency Architecture:
- Tier 1 (Redis 7 Sorted Sets): Acquires temporary atomic stock reservations during checkout.
- Tier 2 (PostgreSQL Pessimistic Locking): Executes database mutations within
DB::transaction()usinglockForUpdate()to prevent double-spending or overselling. - Double-Entry Ledger: Posts balanced financial debit and credit transactions for wallets, invoices, and refunds.
- Queue Dispatch: Pushes long-running operations (SMS alerts, invoice PDFs, webhooks) to background queues managed by Laravel Horizon.
Response Serialization
The Action returns a typed result DTO back to the controller. The controller serializes the payload using Laravel API Resources (OrderResource, ProductResource, CartResource), producing a standard JSON response matching the OpenAPI specification at /docs/api.