# heruafandi06/laravel-sage architecture

> Architecture diagram of the GitHub repository heruafandi06/laravel-sage, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/heruafandi06/laravel-sage
- Repository: https://github.com/heruafandi06/laravel-sage

## Overview

Laravel Sage is a Laravel package for asking natural-language questions over ingested PDF and Markdown documents, using Gemini for embeddings and answer generation. The main workflow is document extraction and chunking, embedding and vector-store persistence, then question embedding, similarity search, and answer generation. The README also documents multi-turn chat with query rewriting and stored history, plus file, MySQL, and pgvector drivers. The sampled source shows these runtime paths; relationships for the unsampled driver internals are limited to the documented/provider-selected driver choices.

Main entry points: [`src/Contracts/VectorStore.php`](https://github.com/heruafandi06/laravel-sage/blob/main/src/Contracts/VectorStore.php) (Vector store contract), [`src/Services/RagService.php`](https://github.com/heruafandi06/laravel-sage/blob/main/src/Services/RagService.php) (RAG service), [`src/Commands/IngestCommand.php`](https://github.com/heruafandi06/laravel-sage/blob/main/src/Commands/IngestCommand.php) (Ingest command), [`src/Drivers/FileVectorStore.php`](https://github.com/heruafandi06/laravel-sage/blob/main/src/Drivers/FileVectorStore.php) (File vector driver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Document ingestion"]
  node_ingest_command["Ingest command<br/>[IngestCommand.php]"]
  node_splitter["Text splitter<br/>[TextSplitter.php]"]
end

subgraph group_qa["Question answering"]
  node_rag["RAG service<br/>[RagService.php]"]
end

subgraph group_storage["Vector storage"]
  node_vector_contract["Vector store contract<br/>[VectorStore.php]"]
  node_file_driver["File vector driver"]
  node_mysql_driver["MySQL vector driver"]
  node_pg_driver["Pgvector driver<br/>[PgvectorStore.php]"]
  node_vector_helper["Cosine similarity<br/>[VectorHelper.php]"]
end

subgraph group_integration["Laravel integration"]
  node_facade["Sage facade<br/>[Sage.php]"]
  node_provider["Service provider"]
  node_config["Package config<br/>[sage.php]"]
end

node_user(("Application user"))
node_documents["PDF and Markdown"]
node_vector_data[("Vector data")]
node_chat_history[("Chat history")]
node_gemini{{"Google Gemini"}}

node_user -->|"asks via"| node_facade
node_facade -->|"resolves service"| node_rag
node_provider -->|"constructs"| node_rag
node_provider -->|"binds implementation"| node_vector_contract
node_config -->|"configures"| node_provider
node_documents -->|"provides files"| node_ingest_command
node_ingest_command -->|"splits text"| node_splitter
node_ingest_command -->|"requests embeddings"| node_gemini
node_ingest_command -->|"saves vectors"| node_vector_contract
node_rag -->|"reads and writes"| node_chat_history
node_rag -->|"embeds and generates"| node_gemini
node_rag -->|"searches vectors"| node_vector_contract
node_vector_contract -->|"implemented by"| node_file_driver
node_vector_contract -->|"implemented by"| node_mysql_driver
node_vector_contract -->|"implemented by"| node_pg_driver
node_file_driver -->|"reads and writes"| node_vector_data
node_mysql_driver -->|"reads and writes"| node_vector_data
node_pg_driver -->|"reads and writes"| node_vector_data
node_file_driver -->|"scores vectors"| node_vector_helper
node_mysql_driver -->|"scores vectors"| node_vector_helper

click node_ingest_command "https://github.com/heruafandi06/laravel-sage/blob/main/src/Commands/IngestCommand.php"
click node_splitter "https://github.com/heruafandi06/laravel-sage/blob/main/src/Services/TextSplitter.php"
click node_rag "https://github.com/heruafandi06/laravel-sage/blob/main/src/Services/RagService.php"
click node_facade "https://github.com/heruafandi06/laravel-sage/blob/main/src/Facades/Sage.php"
click node_provider "https://github.com/heruafandi06/laravel-sage/blob/main/src/SageServiceProvider.php"
click node_config "https://github.com/heruafandi06/laravel-sage/blob/main/config/sage.php"
click node_vector_contract "https://github.com/heruafandi06/laravel-sage/blob/main/src/Contracts/VectorStore.php"
click node_file_driver "https://github.com/heruafandi06/laravel-sage/blob/main/src/Drivers/FileVectorStore.php"
click node_mysql_driver "https://github.com/heruafandi06/laravel-sage/blob/main/src/Drivers/MySqlVectorStore.php"
click node_pg_driver "https://github.com/heruafandi06/laravel-sage/blob/main/src/Drivers/PgvectorStore.php"
click node_vector_helper "https://github.com/heruafandi06/laravel-sage/blob/main/src/Support/VectorHelper.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ingest_command,node_splitter,node_user toneBlue
class node_rag,node_vector_data,node_chat_history toneAmber
class node_vector_contract,node_file_driver,node_mysql_driver,node_pg_driver,node_vector_helper toneMint
class node_facade,node_provider,node_config toneRose
class node_documents,node_gemini toneIndigo
```

## Components

### Document ingestion

- [Ingest command](https://github.com/heruafandi06/laravel-sage/blob/main/src/Commands/IngestCommand.php): `src/Commands/IngestCommand.php`
- [Text splitter](https://github.com/heruafandi06/laravel-sage/blob/main/src/Services/TextSplitter.php): `src/Services/TextSplitter.php`

### Question answering

- [RAG service](https://github.com/heruafandi06/laravel-sage/blob/main/src/Services/RagService.php): `src/Services/RagService.php`

### Vector storage

- [Vector store contract](https://github.com/heruafandi06/laravel-sage/blob/main/src/Contracts/VectorStore.php): `src/Contracts/VectorStore.php`
- [File vector driver](https://github.com/heruafandi06/laravel-sage/blob/main/src/Drivers/FileVectorStore.php): `src/Drivers/FileVectorStore.php`
- [MySQL vector driver](https://github.com/heruafandi06/laravel-sage/blob/main/src/Drivers/MySqlVectorStore.php): `src/Drivers/MySqlVectorStore.php`
- [Pgvector driver](https://github.com/heruafandi06/laravel-sage/blob/main/src/Drivers/PgvectorStore.php): `src/Drivers/PgvectorStore.php`
- [Cosine similarity](https://github.com/heruafandi06/laravel-sage/blob/main/src/Support/VectorHelper.php): `src/Support/VectorHelper.php`

### Laravel integration

- [Sage facade](https://github.com/heruafandi06/laravel-sage/blob/main/src/Facades/Sage.php): `src/Facades/Sage.php`
- [Service provider](https://github.com/heruafandi06/laravel-sage/blob/main/src/SageServiceProvider.php): `src/SageServiceProvider.php`
- [Package config](https://github.com/heruafandi06/laravel-sage/blob/main/config/sage.php): `config/sage.php`

### Other components

- **Application user**
- **PDF and Markdown**
- **Vector data**
- **Chat history**
- **Google Gemini**

## Connections

- Application user → Sage facade: asks via (evidence: `README.md`)
- Sage facade → RAG service: resolves service (evidence: `src/SageServiceProvider.php`)
- Service provider → RAG service: constructs (evidence: `src/SageServiceProvider.php`)
- Service provider → Vector store contract: binds implementation (evidence: `src/SageServiceProvider.php`)
- Package config → Service provider: configures (evidence: `src/SageServiceProvider.php`)
- PDF and Markdown → Ingest command: provides files (evidence: `src/Commands/IngestCommand.php`)
- Ingest command → Text splitter: splits text (evidence: `src/Commands/IngestCommand.php`)
- Ingest command → Google Gemini: requests embeddings (evidence: `src/Commands/IngestCommand.php`)
- Ingest command → Vector store contract: saves vectors (evidence: `src/Commands/IngestCommand.php`)
- RAG service → Chat history: reads and writes (evidence: `src/Services/RagService.php`)
- RAG service → Google Gemini: embeds and generates (evidence: `src/Services/RagService.php`)
- RAG service → Vector store contract: searches vectors (evidence: `src/Services/RagService.php`)
- Vector store contract → File vector driver: implemented by (evidence: `src/Drivers/FileVectorStore.php`)
- Vector store contract → MySQL vector driver: implemented by (evidence: `src/Drivers/MySqlVectorStore.php`)
- Vector store contract → Pgvector driver: implemented by (evidence: `src/Drivers/PgvectorStore.php`)
- File vector driver → Vector data: reads and writes (evidence: `src/Drivers/FileVectorStore.php`)
- MySQL vector driver → Vector data: reads and writes (evidence: `src/Drivers/MySqlVectorStore.php`)
- Pgvector driver → Vector data: reads and writes (evidence: `src/Drivers/PgvectorStore.php`)
- File vector driver → Cosine similarity: scores vectors (evidence: `src/Drivers/FileVectorStore.php`)
- MySQL vector driver → Cosine similarity: scores vectors (evidence: `src/Drivers/MySqlVectorStore.php`)