High Level Graph RAG Laravel Architecture

[User] -> [1. Laravel App (Controller)] -> [2. File Storage (S3/Supabase)]
                      |
                      v
          [3. Laravel Queue (Redis)]
                      |
                      v
[4. Laravel Worker (`php artisan queue:work`)]
   |
   |--> [5. Docling API]
   |--> [6. Supabase/Postgres (Vectors)]
   `--> [7. Neo4j (Knowledge Graph)]

// Status updates happen directly inside the worker, no API calls needed.

// In your DocumentController.php

use App\Jobs\ProcessDocumentJob;
use App\Models\Document;

// ... after saving the file
$document = Document::create([
    'user_id' => auth()->id(),
    'original_filename' => $file->getClientOriginalName(),
    'storage_path' => $path, // e.g., 'documents/unique-id.pdf'
    'status' => 'pending',
]);

// Dispatch the job to the queue
ProcessDocumentJob::dispatch($document);

return response()->json(['message' => 'Your document is being processed.'], 202);

// In app/Jobs/ProcessDocumentJob.php

namespace App\Jobs;

use App\Models\Document;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Storage;
use Laudis\Neo4j\ClientBuilder; // Example Neo4j client library

class ProcessDocumentJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    // The Eloquent model is automatically passed and unserialized
    public Document $document;

    public function __construct(Document $document)
    {
        $this->document = $document;
    }

    /**
     * Execute the job.
     */
    public function handle(): void
    {
        try {
            // 1. Update Status & Fetch File
            $this->document->update(['status' => 'processing']);
            $fileContents = Storage::disk('s3')->get($this->document->storage_path);

            // 2. Call Docling API
            $doclingResponse = Http::withBody($fileContents, 'application/pdf')
                ->post('http://your-docling-api.com/process');

            if ($doclingResponse->failed()) {
                throw new \Exception('Docling API failed.');
            }
            $data = $doclingResponse->json(); // Contains chunks, entities, etc.

            // 3. Create Vector Embeddings and Save to Supabase
            $this->document->update(['status' => 'creating_embeddings']);
            $this->saveVectorsToSupabase($data['chunks']);

            // 4. Create Knowledge Graph in Neo4j
            $this->document->update(['status' => 'building_graph']);
            $this->saveGraphToNeo4j($data['entities'], $data['relationships']);

            // 5. Final Success Status
            $this->document->update(['status' => 'completed']);

        } catch (\Throwable $e) {
            // Laravel's queue will automatically handle retries.
            // If all retries fail, it will call the failed() method.
            $this->document->update([
                'status' => 'failed',
                'error_message' => $e->getMessage()
            ]);

            // Re-throw the exception to let the queue worker know it failed
            throw $e;
        }
    }

    private function saveVectorsToSupabase(array $chunks)
    {
        // Assuming you have an embedding service (e.g., OpenAI)
        $vectorsToInsert = [];
        foreach ($chunks as $chunk) {
            // This is a conceptual call to an embedding service
            $embedding = $this->getEmbeddingForText($chunk['content']);

            $vectorsToInsert[] = [
                'document_id' => $this->document->id,
                'content'     => $chunk['content'],
                'embedding'   => '[' . implode(',', $embedding) . ']', // Format for pgvector
            ];
        }

        // Use a direct DB connection for performance.
        // Assumes you have a 'supabase' connection in config/database.php
        DB::connection('supabase')->table('document_chunks')->insert($vectorsToInsert);
    }

    private function saveGraphToNeo4j(array $entities, array $relationships)
    {
        $client = ClientBuilder::create()
            ->withDriver('bolt', 'bolt://user:pass@your-neo4j-host:7687')
            ->build();

        // Use a transaction for the entire operation
        $client->writeTransaction(function ($transaction) use ($entities, $relationships) {
            // Cypher queries to build the graph
            // ... (as shown in the previous answer)
        });
    }

    // You can define a failed() method for final error logging
    public function failed(\Throwable $exception): void
    {
        // Send a notification to an admin, etc.
        \Log::error("Job failed for document ID {$this->document->id}: {$exception->getMessage()}");
    }
}