# nativephp/laravel architecture

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

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

## Overview

##### Main Components
- Laravel Integration Layer:
- HTTP Interface: Controllers, routes (see the routes/api.php and the controllers in src/Http/Controllers) to accept web requests and dispatch events.
- Middleware: The “src/Http/Middleware/PreventRegularBrowserAccess.php” indicates a layer that restricts or manages access, typical to web routes.
- Service Provider: The “NativeServiceProvider.php” in both the src and resources (as a stub) registers the NativePHP services with Laravel’s container.
- Artisan Commands: Located in “src/Commands”, these provide CLI interactions to manage the application lifecycle (e.g., booting, debugging, migrating, seeding, etc.).

- NativePHP Desktop Services:
- Core Desktop Classes: Classes like “src/App.php”, “src/System.php”, “src/WindowManager.php”, “src/Windows/Window.php”, “src/Dock.php”, and “src/Notification.php” represent the underlying native desktop functionalities.
- Event Handling: The “src/Events” directory is organized by context (App, ChildProcess, Menu, MenuBar, PowerMonitor, Windows, etc.), implementing an event-driven or observer pattern.
- Facades: Wrappers in “src/Facades” (e.g., Alert, ChildProcess, Window, etc.) provide a static interface to the underlying services, consistent with Laravel’s design.
- Contracts, DTOs, and Data Objects support loose coupling and clear interfaces between components.

- Configuration and Resources:
- The “config” directory contains configuration files (for example, “nativephp.php” and “nativephp-internal.php”) which control the behavior of the integration.
- Resource stubs and views offer scaffolding and canned components which help in bootstrapping or customizing the native services.

- Testing & Quality Assurance:
- The “tests” directory houses PHPUnit tests that cover aspects such as HTTP endpoints, facade behavior, event handling, and more.
- Static analysis (phpstan.neon) and workflow configurations under the “.github” directory reflect CI/CD and style validation.

##### Relationships and Interactions
- Laravel’s container and service provider mechanism integrates the desktop services into the Laravel ecosystem.
- HTTP requests from routes (invoked via controllers) interact with the desktop services; for example, a controller may trigger an event that the NativePHP layer listens for to open a new window or display a notification.
- The facade pattern simplifies access to the native functionalities from various parts of the Laravel application.
- Commands in the “src/Commands” directory allow for performing application-wide actions (like configuration loading or database migrations) with direct access to the native desktop interface.

##### Architectural Patterns and Principles
- Separation of Concerns: The project is clearly divided between the Laravel web/application side (HTTP controllers, middleware, routes) and the native desktop functions (windows, menus, notifications, system events).
- Facade Pattern: Use of facades in “src/Facades” abstracts and simplifies complicated underlying logic.
- Event-Driven Architecture: The “src/Events” structure outlines how various desktop or application state events are triggered and handled.
- Dependency Injection & Contracts: The “src/Contracts” and “src/Support” directories underline the commitment to loose coupling and adherence to well-defined interfaces.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Laravel Application Layer"
        ROUTES("Routes (routes/api.php)"):::laravel
        CONTROLLERS("Controllers (src/Http/Controllers)"):::laravel
        MIDDLEWARE("Middleware (src/Http/Middleware/PreventRegularBrowserAccess.php)"):::laravel
        SERVICEPROVIDER("Service Provider (src/NativeServiceProvider.php)"):::laravel
        SPSTUB("Service Provider Stub (resources/stubs/NativeAppServiceProvider.php.stub)"):::laravel

        ROUTES -->|"sends"| CONTROLLERS
        MIDDLEWARE -->|"guards"| CONTROLLERS
        CONTROLLERS -->|"dispatches"| SERVICEPROVIDER
        SERVICEPROVIDER -.->|"uses stub"| SPSTUB
    end

    subgraph "NativePHP Desktop Layer"
        DESKTOP("Desktop App (src/App.php)"):::native
        SYSTEM("System Functionality (src/System.php)"):::native
        WINDOW("Window (src/Windows/Window.php)"):::native
        WINDOWMANAGER("Window Manager (src/Windows/WindowManager.php)"):::native
        DOCK("Dock (src/Dock.php)"):::native
        NOTIFICATION("Notification (src/Notification.php)"):::native
        EVENTS("Event Handling (src/Events)"):::native
        FACADES("Facades (src/Facades)"):::native
        CONTRACTS("Contracts/Support (src/Contracts, src/DTOs, src/DataObjects, src/Support)"):::native

        DESKTOP -->|"triggers"| EVENTS
        EVENTS -->|"notifies"| WINDOW
        EVENTS -->|"alerts"| NOTIFICATION
        DESKTOP -->|"relies on"| SYSTEM
        SYSTEM -->|"manages"| DOCK
        SERVICEPROVIDER -->|"integrates"| DESKTOP
        SERVICEPROVIDER -->|"exposes"| FACADES
        FACADES -->|"abstracts"| CONTRACTS
    end

    subgraph "Command Bus"
        COMMANDS("Artisan Commands (src/Commands)"):::command
        COMMANDS -->|"executes"| DESKTOP
        COMMANDS -->|"triggers"| EVENTS
    end

    subgraph "Configuration & Resources"
        CONFIG("Configuration Files (config/nativephp.php, config/nativephp-internal.php)"):::config
        RESOURCES("Resource Stubs & Views (resources/stubs, resources/views)"):::config
        CONFIG -->|"configures"| SERVICEPROVIDER
        RESOURCES -->|"supports"| SERVICEPROVIDER
    end

    subgraph "Testing & QA"
        TESTS("Test Suite (tests)"):::test
        CI("CI/CD & Static Analysis (.github, phpstan.neon)"):::test
        CI -->|"validates"| TESTS
    end

    %% Click Events
    click ROUTES "https://github.com/nativephp/laravel/blob/main/routes/api.php"
    click CONTROLLERS "https://github.com/nativephp/laravel/tree/main/src/Http/Controllers"
    click MIDDLEWARE "https://github.com/nativephp/laravel/blob/main/src/Http/Middleware/PreventRegularBrowserAccess.php"
    click SERVICEPROVIDER "https://github.com/nativephp/laravel/blob/main/src/NativeServiceProvider.php"
    click SPSTUB "https://github.com/nativephp/laravel/blob/main/resources/stubs/NativeAppServiceProvider.php.stub"
    click COMMANDS "https://github.com/nativephp/laravel/tree/main/src/Commands"
    click DESKTOP "https://github.com/nativephp/laravel/blob/main/src/App.php"
    click SYSTEM "https://github.com/nativephp/laravel/blob/main/src/System.php"
    click WINDOW "https://github.com/nativephp/laravel/blob/main/src/Windows/Window.php"
    click WINDOWMANAGER "https://github.com/nativephp/laravel/blob/main/src/Windows/WindowManager.php"
    click DOCK "https://github.com/nativephp/laravel/blob/main/src/Dock.php"
    click NOTIFICATION "https://github.com/nativephp/laravel/blob/main/src/Notification.php"
    click EVENTS "https://github.com/nativephp/laravel/tree/main/src/Events"
    click FACADES "https://github.com/nativephp/laravel/tree/main/src/Facades"
    click CONTRACTS "https://github.com/nativephp/laravel/tree/main/src/Contracts"
    click CONFIG "https://github.com/nativephp/laravel/blob/main/config/nativephp.php"
    click RESOURCES "https://github.com/nativephp/laravel/tree/main/resources/stubs"
    click TESTS "https://github.com/nativephp/laravel/tree/main/tests"
    click CI "https://github.com/nativephp/laravel/blob/main/.github"

    %% Styles
    classDef laravel fill:#cce5ff,stroke:#004085,color:#004085,stroke-width:2px;
    classDef native fill:#d4edda,stroke:#155724,color:#155724,stroke-width:2px;
    classDef command fill:#fff3cd,stroke:#856404,color:#856404,stroke-width:2px;
    classDef config fill:#d1ecf1,stroke:#0c5460,color:#0c5460,stroke-width:2px;
    classDef test fill:#f8d7da,stroke:#721c24,color:#721c24,stroke-width:2px;
```
