Skip to content

API Service Architecture

This document provides a detailed overview of the API service's internal architecture and its critical role as the central orchestrator of the Labeeb platform.

1. Service Responsibilities Matrix

System-Wide Context

The Labeeb platform is a distributed system. A failure in one service can manifest as a symptom in another. This matrix defines the clear ownership and responsibility of each service, which is the foundation of our incident response process.

Service Tech Core Responsibility Inputs Outputs Depends On
API Laravel/PHP Central gateway, orchestrates jobs, owns PG & OS writes. Ingest batches, client requests. API responses, jobs. PG, Redis, OS, AI-Box.
AI-Box Python/FastAPI Hosts AI models (search, NER, etc.). API jobs/requests. Analysis results (JSON). OS, API (for hydration).
Scraper Python/FastAPI Fetches & normalizes articles from external sources. Profiles, external websites. Ingest batches. API (for ingestion).
Search OpenSearch Provides search capabilities. Indexing requests, search queries. Search results. (None)
Frontend Next.js User interface. User actions. Web pages. API.

2. Internal Architecture & Data Flow

Architectural Principles

The API is designed as a robust, stateless application that relies on external services for state and intelligence. Its primary role is to validate, persist, and orchestrate.

  • System of Record: The API is the sole owner of the PostgreSQL database. All other services must go through the API to read or write core metadata.
  • Asynchronous Processing: All heavy-lifting (content analysis, indexing) is offloaded to a Redis-backed queue (Laravel Horizon). This ensures the API can handle high-volume ingestion without blocking.
  • Service-Based Integration: The API communicates with other Labeeb services (AI-Box, Search) via their REST APIs, not by directly accessing their data stores.
  • REST API Gateway: It serves as the primary gateway for the Frontend, providing a comprehensive REST API for all data operations.

Data Flow Diagram (DFD): Ingestion Path

This diagram illustrates how the API processes an incoming batch of articles from the Scraper.

flowchart TD
    subgraph Inbound
        S[Scraper Service]:::ext
    end

    subgraph "API Service"
        C[IngestArticlesController]:::svc
        V[Validation Middleware]:::svc
        J[AnalyzeAndIndexJob]:::svc
        Q[(Redis Queue)]:::store
    end

    subgraph "Downstream Services"
        AIB[AI-Box Service]:::ext
        OS[OpenSearch]:::ext
    end

    subgraph "Data Store"
        PG[(PostgreSQL)]:::store
    end

    S -- "POST /v1/ingest/articles" --> V
    V -- "Validated Batch" --> C
    C -- "Dispatch Job" --> Q
    Q -- "Process Job" --> J
    J -- "Store Metadata" --> PG
    J -- "Index Document" --> OS
    J -- "Request Enrichment" --> AIB

    classDef ext fill:#e0f2fe,stroke:#0ea5e9,stroke-width:1px;
    classDef svc fill:#f8fafc,stroke:#64748b,stroke-width:1px;
    classDef store fill:#f0fdf4,stroke:#22c55e,stroke-width:1px;