# kitseno/luna architecture

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

- Interactive diagram: https://gitdiagram.com/kitseno/luna
- Repository: https://github.com/kitseno/luna

## Overview

##### Project type and purpose
- This is a full-stack boilerplate combining a Laravel (5.7) REST API backend with a React (16) SPA frontend.
- It offers user management (registration, login, password reset, profile), role/permission enforcement (Laravel-permission & CASL), real-time messaging (Laravel Events/Broadcasting with laravel-echo-server), OAuth2 auth (Passport) and social login (Socialite).

##### File structure
- Top-level “app”, “config”, “database”, “routes” folders represent the Laravel MVC backend.
- The “resources/js” tree holds the React SPA: entrypoints, components, services, Redux store, routes.
- “public/index.php” serves as PHP front controller; “resources/js/app.js” is Webpack’s React bootstrap.
- Build artifacts are managed by webpack.mix.js and npm scripts; backend uses composer.json.
- There are broadcasting config files for realtime (Echo server), queue workers (jobs in storage, queue:work), notification tables, etc.

##### README for technical stack
- Backend: Laravel MVC, Passport (OAuth2), Socialite, Events/Listeners, Notifications, Queues.
- Frontend: React, Redux (+ redux-persist), BlueprintJS (UI), Webpack/Mix.
- Real-time: laravel-echo-server + Socket.IO.
- Data store: SQL (migrations), optional Redis (broadcasting, queue).
- External services: social auth providers, mail service.

##### Detail
- Frontend module grouping (Services, Store, Routes, UI components).
- Integration points (social login, mail, echo server).
- OAuth2 flows (password grant, personal access tokens).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Browser)"
        SPA["React SPA"]:::frontend
        Main["Main Entry"]:::frontend
        CoreDir["Core Modules"]:::frontend
    end

    %% Build Config
    subgraph "Build System"
        Mix["Webpack/Mix Config"]:::config
    end

    %% Web Server
    subgraph "Web Server"
        FrontController["Public Front Controller"]:::server
    end

    %% Backend API
    subgraph "Backend (Laravel API)"
        subgraph "HTTP Layer"
            Controllers["API Controllers"]:::backend
            AuthControllers["Auth Controllers"]:::backend
            Middleware["HTTP Middleware"]:::backend
            Requests["Form Request Validation"]:::backend
            Resources["API Resource Transformers"]:::backend
        end
        subgraph "Core Services"
            ProvidersAuth["Auth Service Provider"]:::backend
            ProvidersBroadcast["Broadcast Service Provider"]:::backend
            EventDefs["Event Definitions"]:::backend
            Listeners["Event Listeners/Subscribers"]:::backend
            Notifications["Notification Classes"]:::backend
        end
        subgraph "Configuration & Data"
            QueueConfig["Queue Configuration"]:::config
            BroadcastConfig["Broadcasting Configuration"]:::config
            ServicesConfig["OAuth & Socialite Services"]:::config
            Migrations["Database Migrations"]:::db
            Seeders["Database Seeders"]:::db
            Routes["Routes (API/Web/Channels)"]:::config
        end
    end

    %% Runtime Services
    subgraph "Runtime Services"
        DB["Database (MySQL/Postgres)"]:::db
        Redis["Redis (Cache & Broker)"]:::db
        Echo["Socket.IO Server"]:::service
        QueueWorker["Queue Worker"]:::worker
    end

    %% External Services
    subgraph "External Services"
        OAuthProviders["OAuth Providers"]:::external
        EmailService["Email Service"]:::external
        FileStorage["File Storage"]:::external
    end

    %% Data Flows
    SPA -->|"Load assets"| FrontController
    FrontController --> Main
    Main --> CoreDir
    Main -->|"AJAX Requests"| Controllers
    SPA -->|"AJAX w/ Token"| AuthControllers
    AuthControllers -->|"Issue Token"| SPA
    Routes --> Controllers
    Routes --> AuthControllers
    Controllers -->|"Read/Write"| DB
    Controllers -->|"Publish Events/Queue"| Redis
    EventDefs -->|"Push Events"| Redis
    Redis -->|"Pub/Sub"| Echo
    Echo -->|"Broadcast"| SPA
    Controllers -->|"Dispatch Jobs"| Redis
    QueueWorker -->|"Consume Jobs"| Redis
    QueueWorker -->|"Send Emails"| EmailService
    QueueWorker -->|"Run Notifications"| Notifications
    AuthControllers -->|"Configure Scopes"| ProvidersAuth
    ProvidersAuth --> DB

    %% Click Events
    click SPA "https://github.com/kitseno/luna/blob/master/resources/js/app.js"
    click Main "https://github.com/kitseno/luna/blob/master/resources/js/Main.js"
    click CoreDir "https://github.com/kitseno/luna/tree/master/resources/js/core/"
    click Mix "https://github.com/kitseno/luna/blob/master/webpack.mix.js"
    click FrontController "https://github.com/kitseno/luna/blob/master/public/index.php"
    click Controllers "https://github.com/kitseno/luna/tree/master/app/Http/Controllers/API/"
    click AuthControllers "https://github.com/kitseno/luna/tree/master/app/Http/Controllers/Auth/"
    click Middleware "https://github.com/kitseno/luna/tree/master/app/Http/Middleware/"
    click Requests "https://github.com/kitseno/luna/tree/master/app/Http/Requests/"
    click Resources "https://github.com/kitseno/luna/tree/master/app/Http/Resources/"
    click ProvidersBroadcast "https://github.com/kitseno/luna/blob/master/app/Providers/BroadcastServiceProvider.php"
    click ProvidersAuth "https://github.com/kitseno/luna/blob/master/app/Providers/AuthServiceProvider.php"
    click EventDefs "https://github.com/kitseno/luna/tree/master/app/Events/"
    click Listeners "https://github.com/kitseno/luna/tree/master/app/Listeners/"
    click Notifications "https://github.com/kitseno/luna/tree/master/app/Notifications/"
    click QueueConfig "https://github.com/kitseno/luna/blob/master/config/queue.php"
    click BroadcastConfig "https://github.com/kitseno/luna/blob/master/config/broadcasting.php"
    click ServicesConfig "https://github.com/kitseno/luna/blob/master/config/services.php"
    click Migrations "https://github.com/kitseno/luna/tree/master/database/migrations/"
    click Seeders "https://github.com/kitseno/luna/tree/master/database/seeds/"
    click Routes "https://github.com/kitseno/luna/blob/master/routes/api.php"
    click QueueWorker "https://github.com/kitseno/luna/tree/master/artisan"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#1B4F72
    classDef backend fill:#FADBD8,stroke:#922B21
    classDef server fill:#FDEBD0,stroke:#B9770E
    classDef config fill:#D5F5E3,stroke:#186A3B
    classDef db fill:#FCF3CF,stroke:#7D6608
    classDef service fill:#E8DAEF,stroke:#6C3483
    classDef worker fill:#F9E79F,stroke:#B7950B
    classDef external fill:#EBF5FB,stroke:#1A5276
```
