# exposedev/expose architecture

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

- Interactive diagram: https://gitdiagram.com/exposedev/expose
- Repository: https://github.com/exposedev/expose

## Overview

##### Main Components
- Client (Laravel Zero CLI)
– CLI entry point (bin/expose)
– Client.Command layer (app/Commands/*)
– app/Client (control connection orchestration)
– HTTP client (app/Http/HttpClient) for API calls
– ProxyManager (app/ProxyManager) managing open tunnels
– Logger hooks & plugins (app/Logger/… and app/Logger/Plugins)
- Server Application (Laravel‐style)
– HTTP Server (app/Http/App.php & Controllers)
– WebSocket endpoint (app/WebSockets/Socket.php) for tunneling
– Routing, middleware, resources (app/Http/Controllers, app/Http/Modifiers)
– Request/Response logging subsystem (app/Logger, app/RequestLog, app/ResponseLog)
– Plugin framework (app/Logger/Plugins for billing, GitHub, Stripe, etc.)
– Service Providers & configuration (app/Providers/AppServiceProvider)
- Persistence & Infrastructure
– Relational Database (MySQL/PostgreSQL) for logs, tokens, config
– Docker (Dockerfile, docker-compose.yml) for containerized hosting
– .env / config/expose.php for environment configuration
- Web Dashboard (Vue SPA)
– Static assets served from public/build/internal-dashboard
– API calls against the Server’s HTTP endpoints to list tunnels, logs, settings
- External Services
– Billing gateways (Stripe, Paddle) via plugin interfaces
– GitHub (for plugin usage data)

##### Relationships & Data Flows
- CLI → (HTTPS/API) → Server.Auth endpoints (authenticate/store token)
- CLI → (TCP/WebSocket) → Server tunnel endpoint (persistent control channel)
- Public Internet → Server (reverse proxy) → Tunnel → CLI → Local service
- Server HTTP API ↔ Database (store/retrieve logs, tokens, tunnel metadata)
- Server Web Dashboard → Server HTTP API → Database/Logger → returns data to UI
- Logger plugins → External billing platforms/APIs (Stripe, GitHub, Paddle)

##### Architectural Patterns & Design Principles
- Separation of Concerns:
– CLI client is distinct from server; communicates only via API & tunnel socket
– Server splits HTTP API, WebSocket proxy, logging, and plugin subsystems
- Plugin Architecture:
– Logger/Plugins implement a common interface (BasePlugin)
– PluginManager loads & invokes plugins without hard dependencies
- MVC‐style layering on server:
– Controllers (app/Http/Controllers) → Services/Models (app/RequestLog, app/ResponseLog) → Database
- Dependency Injection & Service Providers (Laravel Zero conventions)

##### Capturing Essential Details
- Persistent connections: CLI ↔ WebSocket proxy
- Stateless interactions: CLI ↔ HTTP API
- Configuration & bootstrap:
– bootstrap/app.php → sets up service providers & dependency injection
– config/expose.php → core tunneling options
- Lifecycle of a share request:
1) CLI invokes ShareCommand → HTTP POST /api/share → server creates tunnel entry
2) CLI opens WebSocket to /socket → server accepts & binds subdomain
3) Public client HTTP request → reverse proxy → WebSocket → CLI → local dev server

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Side
    subgraph "Client Side" 
        direction TB
        CLIApp["CLI Application\n(Laravel Zero)"]:::backend
        Commands["app/Commands/"]:::backend
        HttpClient["app/Http/HttpClient.php"]:::backend
        ControlConn["app/Connections/ControlConnection.php"]:::backend
        ProxyMgr["app/ProxyManager.php"]:::backend
        CLILoggerPlugins["app/Logger/Plugins/"]:::plugin
        CLIApp --> Commands
        CLIApp --> HttpClient
        CLIApp --> ControlConn
        CLIApp --> ProxyMgr
        CLIApp --> CLILoggerPlugins
    end

    %% Server Side
    subgraph "Server Side" 
        direction TB
        subgraph "API Layer"
            direction TB
            HTTPBootstrap["app/Http/App.php\napp/Http/Server.php"]:::backend
            Controllers["app/Http/Controllers/"]:::backend
            Modifiers["app/Http/Modifiers/CheckBasicAuthentication.php"]:::backend
            Resources["app/Http/Resources/"]:::backend
            HTTPBootstrap --> Controllers
            Controllers --> Modifiers
            Controllers --> Resources
        end

        subgraph "WebSocket/TCP Proxy Layer"
            direction TB
            Socket["app/WebSockets/Socket.php"]:::backend
        end

        subgraph "Logging Subsystem"
            direction TB
            ReqLogModel["app/RequestLog.php"]:::backend
            ResLogModel["app/ResponseLog.php"]:::backend
            ReqLogger["app/Logger/RequestLogger.php"]:::plugin
            ResLogger["app/Logger/LoggedResponse.php"]:::plugin
            DBLogger["app/Logger/DatabaseLogger.php"]:::plugin
            CliLogger["app/Logger/CliLogger.php"]:::plugin
            FELogger["app/Logger/FrontendLogger.php"]:::plugin
            ReqLogModel --> ReqLogger
            ResLogModel --> ResLogger
            ReqLogger --> DBLogger
            ResLogger --> DBLogger
            CliLogger --> DBLogger
            FELogger --> DBLogger
        end

        subgraph "Plugin Framework"
            direction TB
            BasePlugin["app/Logger/Plugins/BasePlugin.php"]:::plugin
            PluginMgr["app/Logger/Plugins/PluginManager.php"]:::plugin
            StripePlugin["app/Logger/Plugins/StripePlugin.php"]:::plugin
            PaddlePlugin["app/Logger/Plugins/PaddleBillingPlugin.php"]:::plugin
            GHPlugin["app/Logger/Plugins/GitHubPlugin.php"]:::plugin
            PluginData["app/Logger/Plugins/PluginData.php"]:::plugin
            BasePlugin --> PluginMgr
            PluginMgr --> StripePlugin
            PluginMgr --> PaddlePlugin
            PluginMgr --> GHPlugin
            PluginMgr --> PluginData
        end

        subgraph "Service Providers & Config"
            direction TB
            AppProvider["app/Providers/AppServiceProvider.php"]:::backend
            EnvConfig[".env-example\nconfig/expose.php\nconfig/*.php"]:::infra
            AppProvider --> EnvConfig
        end

        subgraph "Web Dashboard (Vue SPA)"
            direction TB
            DashboardAssets["public/build/internal-dashboard/"]:::frontend
            DashboardSrc["resources/js/internal-dashboard/src/"]:::frontend
            DashboardBlade["resources/views/client/internal_dashboard.blade.php"]:::frontend
            DashboardBlade --> DashboardAssets
            DashboardBlade --> DashboardSrc
        end

        %% Database
        DB[(Database)]:::db

        %% Infrastructure
        subgraph "Infrastructure"
            direction TB
            Docker["Dockerfile\ndocker-compose.yml\ndocker-entrypoint.sh"]:::infra
            EnvExample[".env-example"]:::infra
        end

    end

    %% External Services
    PublicInternet((Public Internet)):::external
    StripeCloud((Stripe)):::external
    PaddleCloud((Paddle)):::external
    GitHubCloud((GitHub)):::external

    %% Relationships
    CLIApp -->|HTTPS/API| HTTPBootstrap
    CLIApp -.->|TCP/WebSocket| Socket
    PublicInternet -->|HTTP Request| Socket
    HTTPBootstrap -->|SQL| DB
    DashboardBlade -->|API Calls| HTTPBootstrap
    ReqLogger -->|dotted| StripeCloud
    ReqLogger -->|dotted| PaddleCloud
    ReqLogger -->|dotted| GitHubCloud

    %% Click Events
    click CLIApp "https://github.com/exposedev/expose/tree/master/bin/expose"
    click Commands "https://github.com/exposedev/expose/tree/master/app/Commands/"
    click HttpClient "https://github.com/exposedev/expose/blob/master/app/Http/HttpClient.php"
    click ControlConn "https://github.com/exposedev/expose/blob/master/app/Connections/ControlConnection.php"
    click ProxyMgr "https://github.com/exposedev/expose/blob/master/app/ProxyManager.php"
    click CLILoggerPlugins "https://github.com/exposedev/expose/tree/master/app/Logger/Plugins/"
    click HTTPBootstrap "https://github.com/exposedev/expose/blob/master/app/Http/App.php"
    click Controllers "https://github.com/exposedev/expose/tree/master/app/Http/Controllers/"
    click Modifiers "https://github.com/exposedev/expose/blob/master/app/Http/Modifiers/CheckBasicAuthentication.php"
    click Resources "https://github.com/exposedev/expose/tree/master/app/Http/Resources/"
    click Socket "https://github.com/exposedev/expose/blob/master/app/WebSockets/Socket.php"
    click ReqLogModel "https://github.com/exposedev/expose/blob/master/app/RequestLog.php"
    click ResLogModel "https://github.com/exposedev/expose/blob/master/app/ResponseLog.php"
    click ReqLogger "https://github.com/exposedev/expose/blob/master/app/Logger/RequestLogger.php"
    click ResLogger "https://github.com/exposedev/expose/blob/master/app/Logger/LoggedResponse.php"
    click DBLogger "https://github.com/exposedev/expose/blob/master/app/Logger/DatabaseLogger.php"
    click CliLogger "https://github.com/exposedev/expose/blob/master/app/Logger/CliLogger.php"
    click FELogger "https://github.com/exposedev/expose/blob/master/app/Logger/FrontendLogger.php"
    click BasePlugin "https://github.com/exposedev/expose/blob/master/app/Logger/Plugins/BasePlugin.php"
    click PluginMgr "https://github.com/exposedev/expose/blob/master/app/Logger/Plugins/PluginManager.php"
    click StripePlugin "https://github.com/exposedev/expose/blob/master/app/Logger/Plugins/StripePlugin.php"
    click PaddlePlugin "https://github.com/exposedev/expose/blob/master/app/Logger/Plugins/PaddleBillingPlugin.php"
    click GHPlugin "https://github.com/exposedev/expose/blob/master/app/Logger/Plugins/GitHubPlugin.php"
    click PluginData "https://github.com/exposedev/expose/blob/master/app/Logger/Plugins/PluginData.php"
    click AppProvider "https://github.com/exposedev/expose/blob/master/app/Providers/AppServiceProvider.php"
    click EnvConfig "https://github.com/exposedev/expose/blob/master/.env-example"
    click DashboardAssets "https://github.com/exposedev/expose/tree/master/public/build/internal-dashboard/"
    click DashboardSrc "https://github.com/exposedev/expose/tree/master/resources/js/internal-dashboard/src/"
    click DashboardBlade "https://github.com/exposedev/expose/blob/master/resources/views/client/internal_dashboard.blade.php"
    click Docker "https://github.com/exposedev/expose/blob/master/docker-compose.yml"
    click EnvExample "https://github.com/exposedev/expose/blob/master/.env-example"

    %% Styles
    classDef frontend fill:#f9f,stroke:#333,stroke-width:1px
    classDef backend fill:#cff,stroke:#333,stroke-width:1px
    classDef db fill:#fcf,stroke:#333,stroke-width:1px
    classDef plugin fill:#ffc,stroke:#333,stroke-width:1px
    classDef infra fill:#efe,stroke:#333,stroke-width:1px
    classDef external fill:#ddd,stroke:#333,stroke-width:1px
```
