# rapidez/core architecture

> Architecture diagram of the GitHub repository rapidez/core, 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/rapidez/core
- Repository: https://github.com/rapidez/core

## Overview

##### Project Type and Its Purpose
- This is a PHP-based e-commerce integration/core platform—Rapidez Core—that appears to integrate with Magento (as seen from the authentication guards and token names) and uses Laravel’s conventions.
- It is structured as an MVC application with a mix of backend components (controllers, models, middleware, commands) and frontend components (Blade views, Vue components, CSS/JS assets).

##### File Structure to Define Major Components
a. Configuration and Setup:
- The “config/rapidez” directory holds configurations like frontend options, routing, JWT, indexer settings, health checks, and models. This is the backbone for system behavior.
- Global configuration files (.editorconfig, .php-cs-fixer, package.json, etc.) set up code quality, formatting, and asset compilation.

b. Frontend & Asset Layer:
- The “resources” directory contains CSS, JavaScript (including Vue components), and Blade templates (views). This represents the presentation layer.
- Components are well-factored, with separate minor directories for cart, checkout, listing, product, and customer views, indicating an emphasis on modular frontend design.

c. Application Logic and Business Layer:
- The “src” folder is where most of the backend code resides:
- Controllers (e.g., CategoryController, CheckoutController, ProductController) reside in “src/Http/Controllers,” handling routing and request processing.
- Business logic is organized into Actions, Commands, Events, Jobs, and Listeners.
- Models in “src/Models” implement the domain layer for products, orders, customers, and other e-commerce components.
- Custom middleware and authentication guards (MagentoCartTokenGuard, MagentoCustomerTokenGuard) handle security and session management.
- The Service Provider (RapidezServiceProvider) and Facade (Rapidez) encapsulate bootstrap tasks and offer a clean API.

d. Routing and Integration Points:
- The “routes” directory (with “api.php” and “web.php”) shows how HTTP endpoints and API routes are defined and bound to the controllers.
- Integration with external systems is evident through Magento integrations, Elasticsearch commands (IndexCategoriesCommand, ElasticsearchIndexer), and healthcheck components.

e. Testing and Quality Control:
- The “tests” directory has unit, feature, and browser (Dusk) tests that validate the application logic and frontend interactions.
- GitHub workflows, PHPStan, and Prettier configurations ensure continuous integration and code style enforcement.

a. A top-level separation:
- Frontend/Presentation Layer: Represented by “resources/views” (Blade templates) and “resources/js/components” (Vue components, JS) together with asset compile tools (vite.config.js, tailwind.config.js).
- Application/API Layer:
– The routing files (routes/web.php, routes/api.php) serve as the entry point for HTTP requests.
– Controllers take request inputs after passing through middleware (from src/Http/Middleware).
- Business Logic Layer:
– The Service Provider and Facade that bootstrap the application.
- Data/Domain Layer:
– The “src/Models” directory represents the domain model for e-commerce elements such as Product, Category, Quote, etc. Also emphasize the model scopes and traits.
– Represent the database and external data stores (Elasticsearch, Magento) as part of this layer.

b. External Integrations:
- Magneto’s integration through authentication components.
- Elasticsearch integrations via command components and associated health check listeners.

c. Control and Communication Flow:
– From the Frontend (user/browser) to the Routing layer.
– From the Routing layer through Middleware into Controllers.
– From Controllers to various Business Logic components (Actions, Commands) and then to Models.
– Represent asynchronous processes like Jobs and Event handling.

##### Architectural Patterns and Technologies
- MVC pattern and the layered architecture (presentation, business logic, and data).
- How Laravel Dusk tests interact with the frontend and backend.
- Integration points for search (GraphQL queries in resources/views and JS components) and health checks (controllers and listeners).
- Use of Laravel service providers and custom authentication guards for Magento.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level User
    A["User/Browser"]:::user

    %% Frontend & Asset Layer Subgraph
    subgraph "Frontend & Asset Layer"
        B1["Blade Templates"]:::frontend
        B2["Vue Components & Assets"]:::frontend
    end

    %% Routing and Middleware
    C["Routing & API Endpoints"]:::routing
    D["HTTP Middleware"]:::controller
    E["Controllers"]:::controller

    %% Business Logic Layer Subgraph
    subgraph "Business Logic Layer"
        F["Actions"]:::business
        G["Commands"]:::business
        H["Jobs"]:::business
        I["Events"]:::business
        J["Listeners"]:::business
        K["Authentication Guards"]:::business
        subgraph "Bootstrap Components"
            L1["Rapidez Service Provider"]:::business
            L2["Rapidez Facade"]:::business
        end
    end

    %% Domain / Data Layer
    M["Domain Models"]:::domain

    %% External Integrations
    subgraph "External Services"
        N["Magento Integration"]:::external
        O["Elasticsearch"]:::external
    end

    %% Configuration and Testing
    P["Configuration (config/rapidez)"]:::config
    subgraph "Testing & CI"
        Q["Automated Tests (tests)"]:::testing
        R["CI Workflows (.github/workflows)"]:::testing
    end

    %% Flow Connections
    A --> B1
    B1 --> B2
    B2 --> C
    C --> D
    D --> E
    E --> F
    E --> G
    E --> H
    E --> I
    E --> J
    E --> K
    E --> L1
    E --> L2

    %% Business Logic to Domain Models
    F --> M
    G --> M
    H --> M
    I --> M
    J --> M
    K --> M
    L1 --> M
    L2 --> M

    %% Domain Models to External Integrations
    M --> N
    M --> O

    %% Configuration dotted connections (used globally)
    P --- C
    P --- M

    %% Testing connections (informational)
    M --- Q
    Q --- R

    %% Click Events (Configuration & Setup)
    click P "https://github.com/rapidez/core/tree/master/config/rapidez"
    
    %% Click Events (Frontend & Asset Layer)
    click B1 "https://github.com/rapidez/core/tree/master/resources/views"
    click B2 "https://github.com/rapidez/core/tree/master/resources/js/components"
    
    %% Click Events (Routing and Integration Points)
    click C "https://github.com/rapidez/core/blob/master/routes/web.php"
    
    %% Click Events (Application Logic - Middleware & Controllers)
    click D "https://github.com/rapidez/core/tree/master/src/Http/Middleware"
    click E "https://github.com/rapidez/core/tree/master/src/Http/Controllers"
    
    %% Click Events (Business Logic Components)
    click F "https://github.com/rapidez/core/tree/master/src/Actions"
    click G "https://github.com/rapidez/core/tree/master/src/Commands"
    click H "https://github.com/rapidez/core/tree/master/src/Jobs"
    click I "https://github.com/rapidez/core/tree/master/src/Events"
    click J "https://github.com/rapidez/core/tree/master/src/Listeners"
    click K "https://github.com/rapidez/core/tree/master/src/Auth"
    click L1 "https://github.com/rapidez/core/blob/master/src/RapidezServiceProvider.php"
    click L2 "https://github.com/rapidez/core/blob/master/src/Facades/Rapidez.php"
    
    %% Click Events (Domain Models)
    click M "https://github.com/rapidez/core/tree/master/src/Models"
    
    %% Click Events (Testing and Quality Control)
    click Q "https://github.com/rapidez/core/tree/master/tests"
    click R "https://github.com/rapidez/core/tree/master/.github/workflows"

    %% Styles
    classDef user fill:#FAD7A0,stroke:#C0392B,stroke-width:2px;
    classDef frontend fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef routing fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef controller fill:#F9E79F,stroke:#7D6608,stroke-width:2px;
    classDef business fill:#FCF3CF,stroke:#7D6608,stroke-width:2px;
    classDef domain fill:#D1F2EB,stroke:#117864,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef config fill:#D5DBDB,stroke:#566573,stroke-width:2px;
    classDef testing fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
```
