# prism-php/prism architecture

> Architecture diagram of the GitHub repository prism-php/prism, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prism-php/prism
- Repository: https://github.com/prism-php/prism

## Overview

##### Project Type & Purpose
- This is a Laravel package (“Prism”) that abstracts integration with multiple AI/LLM providers.
- Its purpose is to let developers easily generate text, manage tool-based interactions, and handle multi-step conversations within Laravel apps.
- The README emphasizes it as a “powerful Laravel package” that simplifies working with LLMs while hiding the complexities of interacting with different providers.

##### Main Components
a. Core Package Components:
- Core service classes (e.g., src/Prism.php, src/PrismManager.php, src/PrismServer.php)
- Service Provider integration (src/PrismServiceProvider.php) for bootstrapping within the Laravel ecosystem.
- Configuration Files (config/prism.php) that set up defaults for provider integrations and behaviors.

b. Client-Facing Layers:
- HTTP Controllers (src/Http/Controllers/PrismChatController.php and PrismModelController.php) that expose endpoints for interactions.
- Facades (src/Facades/PrismServer.php, src/Facades/Tool.php) which provide a fluent interface.

c. AI Provider Integrations:
- A collection of provider-specific implementations under src/Providers (e.g., Anthropic, DeepSeek, Gemini, Groq, Mistral, Ollama, OpenAI, VoyageAI, XAI).
- Within each provider folder, the pattern is similar: there are Concerns, Handlers, Maps, and ValueObjects. Illustrate that the package uses a common interface (in src/Contracts) to interact with all providers.

d. Business Logic Components:
- Text, Structured, and Embeddings logic are separated into their own directories (src/Text, src/Structured, src/Embeddings). Each handles requests, responses, steps, and builders for their respective functionalities.
- Use of Schemas for structured validation (src/Schema classes).

e. Support & Utilities:
- Contracts defining interfaces (src/Contracts/Message.php, PrismRequest.php, Provider.php, Schema.php).
- Concerns and Traits contained in src/Concerns for shared functionality.
- Exceptions (src/Exceptions) for robust error handling across providers.
- Enums (src/Enums) and Value Objects (src/ValueObjects) to enforce consistency in message formatting and metadata.

##### Relationships and Data Flow
- The Prism Manager interacts with the configured provider implementations (selected from the Providers folder) via common contracts.
- Data flows from the controllers → core logic (Prism/Manager) → provider-specific handlers → external API calls.
- Results propagate back following the reverse path. Error handling occurs at both the provider level (via Exceptions) and within core logic.
- Dependency and invocation relationships among core components, providers, and helper classes (Concerns, ValueObjects, Schema).
- There is also a testing suite verifying the integration between these pieces, as seen in the tests folder.

##### Architectural Patterns & Design Principles
- The package follows a modular design, using the Strategy Pattern to manage multiple providers—each provider implementation conforms to a common interface.
- Laravel’s Service Container is used for dependency injection (as indicated by the Service Provider and facades).
- There’s a clear separation of concerns: HTTP layer, business/service layer, provider-specific logic, and utility components are clearly segmented.
- Layered architecture: configuration layer (config/prism.php), business logic layer (src/*), and presentation/HTTP layer.

##### Additional Elements
- External Services: Represent external LLM or AI provider services (OpenAI, Anthropic, etc.) as external nodes that the package communicates with.
- Development & Testing Tools: Optionally show resources for tests, CI configurations (under .github/workflows), and documentation (docs folder) as supporting elements.
- Configuration & Environment: Show the interplay between configuration files (config/prism.php) and the runtime environment.

- That each block/component has a clear label.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Laravel Integration
    subgraph "Laravel Integration"
        A1["PrismServiceProvider"]:::laravel
        A2["PrismChatController"]:::controller
        A3["PrismModelController"]:::controller
        A4["PrismServer (Facade)"]:::facade
        A5["Tool (Facade)"]:::facade
    end

    %% Core Engine
    subgraph "Core Engine"
        B1["Prism"]:::core
        B2["PrismManager"]:::core
        B3["PrismServer (Core)"]:::core
    end

    %% Provider Abstraction
    subgraph "Provider Abstraction"
        C1["Contracts/Provider"]:::provider
    end

    %% Provider Implementations
    subgraph "Provider Implementations"
        D1["Providers"]:::provider
    end

    %% Domain-specific Logic
    subgraph "Domain-specific Logic"
        E1["Text"]:::domain
        E2["Structured"]:::domain
        E3["Embeddings"]:::domain
        E4["Schema"]:::domain
    end

    %% Support & Utilities
    subgraph "Support & Utilities"
        F1["Concerns"]:::util
        F2["Exceptions"]:::util
        F3["Enums"]:::util
        F4["ValueObjects"]:::util
    end

    %% Configuration & Environment
    G1["Configuration (prism.php)"]:::laravel

    %% External Services
    H1["External LLM Services"]:::provider

    %% Connections
    %% Laravel Integration to Core Engine
    A2 -->|"calls"| B2
    A3 -->|"calls"| B2
    A1 -->|"bootstraps"| B1
    A1 -->|"bootstraps"| B2

    %% Core Engine internal connections
    B2 -->|"invokes"| B1
    B2 -->|"manages"| B3
    B2 -->|"selects"| C1

    %% Provider abstraction & implementations connections
    C1 -->|"implemented by"| D1
    D1 -->|"calls"| H1

    %% Domain-specific Logic integration
    B2 -->|"uses"| E1
    B2 -->|"uses"| E2
    B2 -->|"uses"| E3
    B2 -->|"validates with"| E4

    %% Support & Utilities integration (dashed to indicate support)
    B1 -.->|"supports"| F1
    B1 -.->|"handles"| F2
    B1 -.->|"formats with"| F3
    B1 -.->|"structures"| F4
    D1 -.->|"shares"| F1
    D1 -.->|"handles"| F2

    %% Configuration link
    G1 -->|"configures"| B1
    G1 -->|"configures"| D1

    %% Facades connection to Core Engine
    A4 -->|"proxies"| B3
    A5 -->|"proxies"| B3

    %% External loopback
    H1 -->|"returns response"| D1
    D1 -->|"feeds"| C1

    %% Click Events for Core Package Components
    click B1 "https://github.com/prism-php/prism/blob/main/src/Prism.php"
    click B2 "https://github.com/prism-php/prism/blob/main/src/PrismManager.php"
    click B3 "https://github.com/prism-php/prism/blob/main/src/PrismServer.php"
    click A1 "https://github.com/prism-php/prism/blob/main/src/PrismServiceProvider.php"
    click G1 "https://github.com/prism-php/prism/blob/main/config/prism.php"

    %% Click Events for Client-Facing Layers
    click A2 "https://github.com/prism-php/prism/blob/main/src/Http/Controllers/PrismChatController.php"
    click A3 "https://github.com/prism-php/prism/blob/main/src/Http/Controllers/PrismModelController.php"
    click A4 "https://github.com/prism-php/prism/blob/main/src/Facades/PrismServer.php"
    click A5 "https://github.com/prism-php/prism/blob/main/src/Facades/Tool.php"

    %% Click Events for Provider Integrations
    click D1 "https://github.com/prism-php/prism/tree/main/src/Providers"
    click C1 "https://github.com/prism-php/prism/tree/main/src/Contracts/Provider"

    %% Click Events for Business Logic Components
    click E1 "https://github.com/prism-php/prism/tree/main/src/Text"
    click E2 "https://github.com/prism-php/prism/tree/main/src/Structured"
    click E3 "https://github.com/prism-php/prism/tree/main/src/Embeddings"
    click E4 "https://github.com/prism-php/prism/tree/main/src/Schema"

    %% Click Events for Support & Utilities
    click F1 "https://github.com/prism-php/prism/tree/main/src/Concerns"
    click F2 "https://github.com/prism-php/prism/tree/main/src/Exceptions"
    click F3 "https://github.com/prism-php/prism/tree/main/src/Enums"
    click F4 "https://github.com/prism-php/prism/tree/main/src/ValueObjects"

    %% Styles
    classDef core fill:#eed,stroke:#c55,stroke-width:2px;
    classDef laravel fill:#ddf,stroke:#339,stroke-width:2px;
    classDef controller fill:#dfd,stroke:#383,stroke-width:2px,stroke-dasharray: 5, 5;
    classDef facade fill:#fdd,stroke:#933,stroke-width:2px,stroke-dasharray: 3, 3;
    classDef domain fill:#ffe,stroke:#aa3,stroke-width:2px;
    classDef provider fill:#fdd,stroke:#933,stroke-width:2px;
    classDef util fill:#def,stroke:#39c,stroke-width:2px;
```
