# xiaomlove/nexusphp architecture

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

- Interactive diagram: https://gitdiagram.com/xiaomlove/nexusphp
- Repository: https://github.com/xiaomlove/nexusphp

## Overview

This project is a full-stack web application built as a complete PT (private tracker) site solution. It is based on NexusPHP integrated with the Laravel framework and the Filament admin panel. The system structure is a monolithic application that follows a layered (MVC-like) architecture with several cross-cutting concerns like authentication, authorization, plugins, file handling, queue processing, and scheduled console commands.

##### Main Components
- Client / Presentation Layer: Represent the web clients (browsers) that interact with the system. Indicate that requests go to the public folder (which serves PHP files via a web server such as Apache/nginx), with static assets (CSS, JavaScript, images) included.
- Web Server: Illustrate the hosting environment (Docker container in production, typical web server setup) that serves the public directory. Note that the .htaccess and web.config files indicate server configuration.
- Application Layer (Laravel):
- Controllers (found in app/Http/Controllers) and Middleware (app/Http/Middleware) form the core request processing – they accept input, process it via business logic, and return responses.
- Service Providers and Repositories (located under app/Providers and app/Repositories) are used to configure, inject dependencies, and manage data logic.
- Console commands (app/Console/Commands) show scheduled jobs and command-line utilities.
- Domain Layer and Business Logic:
- Models (in app/Models) and Policies (app/Policies) encapsulate domain logic.
- Plugins, Nexus core, and custom functionality (in the "nexus" directory) are layered on top for specialized operations such as torrent handling, file processing, attachments, and plugin management.
- The “nexus/Plugin” and “nexus/Torrent” components indicate custom engine integrations that extend or override the default Laravel behaviors.
- Administrative / Management Interface:
- The Filament admin modules (in app/Filament, app/Providers/Filament, and relevant resource pages under Filament folders) create a detailed backend dashboard for managing users, forums, torrents, claims, and other services.
- Data Layer:
- MySQL Database (migrations and seeders under database/migrations and database/seeders). Also, the _db directory contains SQL structure files.
- Caching and session management use Redis, as specified in the README.
- Other Supporting Components:
- File storage (attachments, uploads) represented by the “attachments”, “storage”, and “public/pic” directories.
- External services: API integrations (Json API endpoints, Oauth in app/Http/Controllers/OauthController), third-party search engines (MeiliSearch, ES) and other integrations (e.g., Google Drive driver as seen in the providers).
- Command-line jobs and scheduled tasks (Artisan commands and cron job scripts).
- Language and Multi-Language support (lang folder with different translations), emphasizing internationalization.

##### Relationships and Data Flow
- Request flow entering through controllers with middleware intercepting requests for authentication and localization.
- That controllers call services and repositories, which in turn access the Database layer.
- For asynchronous tasks (console commands or jobs), illustrate a separate process that interacts with the system’s queue (using Redis) and executes background commands.

##### Architectural Patterns and Design Principles
- Use the MVC pattern to separate concerns: Controllers, Models, and Views.
- Dependency injection and the “service provider” pattern that Laravel uses.
- Plugin extensibility model – a flexible mechanism that allows third-party modules to integrate with the system.
- Layers for CLI commands as part of the scheduled/async process.

##### Technologies
- Laravel (backend framework), Filament (admin dashboard framework), and NexusPHP (custom PT tracker engine).
- Database: MySQL.
- Cache/Queue: Redis.
- Frontend assets (Blade v/s JavaScript bundles found under resources/js and public/js).
- Docker containerization for deployment as described in the quick start guide.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Client / Presentation Layer
    subgraph "Client / Presentation Layer"
        A["Client Browser"]:::client
        B["Public Folder"]:::presentation
        C["Templates (resources/views)"]:::presentation
        D["Language Support (lang)"]:::presentation
    end

    %% Web Server
    subgraph "Web Server"
        E["Server Config: .htaccess"]:::webserver
        F["Server Config: web.config"]:::webserver
    end

    %% Application Layer (Laravel)
    subgraph "Application Layer (Laravel)"
        G["Controllers"]:::application
        H["Middleware"]:::application
        I["Service Providers"]:::application
        J["Repositories"]:::application
        K["Console Commands"]:::application
    end

    %% Domain Layer & Business Logic
    subgraph "Domain Layer & Business Logic"
        L["Models"]:::domain
        M["Policies"]:::domain
        N["NexusPHP Engine"]:::domain
        O["Plugin Subsystem"]:::domain
        P["Torrent Handling"]:::domain
    end

    %% Administrative Interface (Filament)
    subgraph "Administrative Interface (Filament)"
        Q["Filament Admin"]:::admin
        R["Filament Providers"]:::admin
    end

    %% Data Layer
    subgraph "Data Layer"
        S["MySQL Database"]:::database
        T["Redis Cache/Queue"]:::database
    end

    %% Other Supporting Components
    subgraph "Other Supporting Components"
        subgraph "File Storage"
            U1["Attachments"]:::support
            U2["Storage"]:::support
            U3["Public Pics"]:::support
        end
        V["OAuth API Endpoints"]:::external
    end

    %% Deployment
    subgraph "Deployment"
        W["Docker Container Environment"]:::deployment
    end

    %% Data Flow Connections
    A -->|"request"| B
    B -->|"served-by"| E
    E -->|"routes request"| G
    G -->|"passes-through"| H
    G -->|"calls"| I
    I -->|"configures"| J
    J -->|"reads/writes"| S
    G -->|"triggers"| L
    L -->|"secured-by"| M
    G -->|"utilizes"| N
    N -->|"extends via"| O
    N -->|"handles"| P
    I -->|"accesses"| S
    K -->|"enqueue task"| T
    T -->|"processes to update"| S

    %% Admin Interface Flow
    A -->|"accesses admin"| Q
    Q -->|"utilizes"| R

    %% External Integration
    G -->|"integrates"| V

    %% Deployment Links
    W --> E
    W --> Q

    %% Click Events
    click B "https://github.com/xiaomlove/nexusphp/tree/php8/public"
    click C "https://github.com/xiaomlove/nexusphp/tree/php8/resources/views"
    click D "https://github.com/xiaomlove/nexusphp/tree/php8/lang"
    click E "https://github.com/xiaomlove/nexusphp/blob/php8/public/.htaccess"
    click F "https://github.com/xiaomlove/nexusphp/blob/php8/public/web.config"
    click G "https://github.com/xiaomlove/nexusphp/tree/php8/app/Http/Controllers"
    click H "https://github.com/xiaomlove/nexusphp/tree/php8/app/Http/Middleware"
    click I "https://github.com/xiaomlove/nexusphp/tree/php8/app/Providers"
    click J "https://github.com/xiaomlove/nexusphp/tree/php8/app/Repositories"
    click K "https://github.com/xiaomlove/nexusphp/tree/php8/app/Console/Commands"
    click L "https://github.com/xiaomlove/nexusphp/tree/php8/app/Models"
    click M "https://github.com/xiaomlove/nexusphp/tree/php8/app/Policies"
    click N "https://github.com/xiaomlove/nexusphp/tree/php8/nexus"
    click O "https://github.com/xiaomlove/nexusphp/tree/php8/nexus/Plugin"
    click P "https://github.com/xiaomlove/nexusphp/tree/php8/nexus/Torrent"
    click Q "https://github.com/xiaomlove/nexusphp/tree/php8/app/Filament"
    click R "https://github.com/xiaomlove/nexusphp/tree/php8/app/Providers/Filament"
    click S "https://github.com/xiaomlove/nexusphp/tree/php8/database/migrations"
    click U1 "https://github.com/xiaomlove/nexusphp/tree/php8/attachments"
    click U2 "https://github.com/xiaomlove/nexusphp/tree/php8/storage"
    click U3 "https://github.com/xiaomlove/nexusphp/tree/php8/public/pic"
    click V "https://github.com/xiaomlove/nexusphp/tree/php8/app/Http/Controllers/OauthController"

    %% Styles
    classDef client fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef presentation fill:#B3E5FC,stroke:#000,stroke-width:2px;
    classDef webserver fill:#90CAF9,stroke:#000,stroke-width:2px;
    classDef application fill:#A5D6A7,stroke:#000,stroke-width:2px;
    classDef domain fill:#C5E1A5,stroke:#000,stroke-width:2px;
    classDef admin fill:#FFAB91,stroke:#000,stroke-width:2px;
    classDef database fill:#EF9A9A,stroke:#000,stroke-width:2px;
    classDef external fill:#CE93D8,stroke:#000,stroke-width:2px;
    classDef support fill:#F0E68C,stroke:#000,stroke-width:2px;
    classDef deployment fill:#D7CCC8,stroke:#000,stroke-width:2px;
```
