API Service: The Central Playbook¶

1. Mission & Scope¶

The API's mission is to be the single, authoritative gateway for all data persistence, orchestration, and client-facing queries.

It is a robust Laravel application designed to act as the stable core of the platform. It enforces data integrity, orchestrates complex workflows through a queue-based system, and provides a rich GraphQL API for frontend clients. Its architecture prioritizes stability, data integrity, and clear, versioned contracts for interacting services.

2. Service Responsibilities & Interactions¶

This table defines the API's central role and its critical dependencies within the Labeeb platform ecosystem.

3. Guiding Principles¶

The architecture and operational philosophy of the API service are deeply rooted in these core SRE principles:

• System of Record ():

  • What: The PostgreSQL database is the ultimate source of truth for all relational data. The API service is the exclusive owner of its schema and write-access.
  • Why: This prevents data corruption and split-brain scenarios by ensuring a single, authoritative data store.

• Asynchronous by Default ():

  • What: All heavy or time-consuming tasks (e.g., AI analysis, search indexing) are offloaded to a robust queue system (Laravel Horizon & Redis).
  • Why: This keeps the API responsive and resilient. An ingestion request can be acknowledged in milliseconds, while the complex processing happens reliably in the background.

• Strict, Versioned Contracts ():

  • What: All inter-service communication, especially ingestion, is governed by a strict, versioned contract.
  • Why: This allows other services (like the Scraper) to evolve independently without breaking the core API, ensuring platform stability.

• Database-Driven Logic ():

  • What: Core business logic is encapsulated within the Laravel framework, primarily in Eloquent models, services, and jobs.
  • Why: This leverages a mature, well-tested framework, reducing boilerplate code and promoting maintainable, testable business logic.

4. Architecture & Request Flow¶

The API service implements a layered architecture with three core patterns: ingestion, search, and chat completion. Each follows a specific request flow optimized for reliability and performance.

Core Service Architecture¶

flowchart TD
    subgraph "Client Layer"
        SCR[Scraper Service]
        FE[Frontend App]
        EXT[External Clients]
    end

    subgraph "API Gateway Layer"
        MW[Middleware Stack]
        CTRL[Controllers]
    end

    subgraph "Service Layer"
        INGEST[Article Processor]
        SEARCH[OpenSearch Service]
        CHAT[Hybrid AI Client]
    end

    subgraph "Data & Queue Layer"
        REDIS[(Redis Cache)]
        QUEUE[Laravel Horizon]
        PG[(PostgreSQL)]
        OS[(OpenSearch)]
    end

    subgraph "External Services"
        AIB[AI-Box Service]
    end

    SCR --> MW
    FE --> MW
    EXT --> MW
    MW --> CTRL
    CTRL --> INGEST
    CTRL --> SEARCH
    CTRL --> CHAT
    INGEST --> REDIS
    INGEST --> QUEUE
    INGEST --> PG
    SEARCH --> OS
    CHAT --> AIB
    QUEUE --> AIB

Request Processing Patterns¶

Ingestion Flow (Asynchronous):

sequenceDiagram
    participant S as Scraper
    participant A as API
    participant R as Redis
    participant Q as Queue
    participant AI as AI-Box

    S->>A: POST /v1/ingest/articles
    A->>R: Check idempotency
    A->>A: Validate & normalize
    A->>Q: Dispatch job
    A->>S: 202 Accepted
    Q->>AI: Process article

Search Flow (Hybrid):

sequenceDiagram
    participant F as Frontend
    participant A as API
    participant OS as OpenSearch
    participant AI as AI-Box

    F->>A: GET /v1/search
    A->>OS: BM25 query
    A->>AI: Vector search
    AI->>OS: Retrieve embeddings
    A->>A: Merge results (RRF)
    A->>F: Unified response

Chat Flow (Streaming):

sequenceDiagram
    participant F as Frontend
    participant A as API
    participant AI as AI-Box

    F->>A: POST /chat/completions
    A->>AI: Forward request
    AI-->>A: Stream response
    A-->>F: Server-sent events

5. Core Endpoints Overview¶

Ingestion Endpoints¶

Key Features: - Idempotency via Idempotency-Key header - Request body size limits (configurable) - Async processing with immediate acknowledgment - Deduplication and validation

Search Endpoints¶

Search Modes: - bm25: Keyword-based search - vector: Semantic vector search - hybrid: Combined search with RRF fusion

Chat Endpoints¶

Streaming Protocol: - Server-sent events format - Event types: meta, delta, done, error - Real-time response rendering

6. Standard Deployment Process¶

This checklist outlines the standard procedure for deploying the API service. This process ensures consistency and minimizes downtime.

1. Enter Maintenance Mode (Production): Prevent users from accessing the service during the deployment.

   docker compose exec api php artisan down
   

2. Pull Latest Code:

   git pull origin main
   

3. Install Dependencies: Install PHP dependencies with Composer.

   docker compose exec api composer install --no-dev --optimize-autoloader
   

4. Run Database Migrations: Apply any new database schema changes.

   docker compose exec api php artisan migrate --force
   

5. Clear & Cache Configuration: Ensure the application loads the new configuration and routes.

   docker compose exec api php artisan config:cache
   docker compose exec api php artisan route:cache
   

6. Restart Queue Workers: This ensures the background workers are running the new code.

   docker compose exec api php artisan horizon:terminate
   

7. Exit Maintenance Mode: Make the application available to users again.

   docker compose exec api php artisan up
   

7. Routine Operations & Maintenance¶

• Check Horizon Status: docker compose exec api php artisan horizon:status
• Clear Failed Jobs: docker compose exec api php artisan horizon:forget-failed
• Run Tests: docker compose exec api php artisan test
• Open a Tinker Shell: docker compose exec api php artisan tinker

8. Structured Incident Playbooks¶

This section provides direct links to detailed runbooks for common operational incidents affecting the API service.