# getlantern/flashlight architecture

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

- Interactive diagram: https://gitdiagram.com/getlantern/flashlight
- Repository: https://github.com/getlantern/flashlight

## Overview

From the file tree and the README we can deduce that this project is the core Lantern “flashlight” library—a Go-based network proxy framework with support for various proxy protocols and configurations, along with bindings for Android and iOS. Its goal is to dynamically configure and run proxy services while managing both per-proxy and global configurations.

##### Main Components
- Library Core: This is the primary component implementing all the proxy functionalities. It contains modules that handle different connection types and protocols (e.g., chained, dialer, shadowsocks, quic, http/https).
- Configuration System: Includes directories like “config”, “embeddedconfig”, and “genconfig”. This component is responsible for merging a static configuration template with dynamic data (masquerade hosts, etc.) to generate the final global config. Note that this configuration is both fetched at runtime (from S3 and config-server) and generated via CI processes (using “go generate” and CRON jobs).
- API Definitions: The “apipb” directory (and similar ones in “issue” and “pro/client”) holds protocol buffer definitions for the APIs—essential for inter-module or inter-service communication.
- Proxy and Dialer Implementations: Under “chained”, “dialer”, and “client” directories, you see various implementations of proxies, session management, connection strategies (multipath, session caching, pre-connecting dialers), and protocol support.
- Platform-Specific Features: Modules in “browsers” (including “defaultbrowser” and “simbrowser”) indicate special handling for different operating systems (Windows, Darwin, etc.) and may be responsible for interacting with system default browsers or market share tracking.
- Auxiliary Services: There are additional modules for logging (“logging”), telemetry (“otel”), error handling (“status”), integration testing (“integrationtest”), and helper utilities (“util”, “testutils”).

##### Architectural Patterns & Design Principles
- Modular Design: The project is split into many fine-grained modules (e.g., separate packages for different protocols, config systems, service implementations). This modularity allows individual components (e.g., chained proxy implementations, dialers) to evolve separately.
- Separation of Concerns: The clear separation between configuration generation (genconfig, embeddedconfig) and runtime proxy operation (chained, dialer, client) makes the system more maintainable.
- Cross-Platform Considerations: Files with OS-specific suffixes (e.g., browsers_darwin.go, browsers_windows.go) indicate conditional compilation and platform-specific implementations.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Integration Layer
    subgraph "External Integration Layer"
        S3["S3 (Global Config Storage)"]:::external
        ConfigServer["Config-Server"]:::external
    end

    %% Core Engine Layer
    subgraph "Core Engine Layer"
        %% Configuration Management Subgraph
        subgraph "Configuration Management"
            Embedded["Embedded Config Template"]:::config
            ConfigDir["Configuration Source"]:::config
            GenConfig["Config Generator (genconfig)"]:::config
            GlobalConfig["Global Config"]:::configStore
        end

        %% Proxy Core Subgraph
        subgraph "Proxy Core"
            LibraryCore["Library Core (Proxy Functionality)"]:::core
            Chained["Chained Proxies"]:::core
            Dialer["Dialer Module"]:::core
            Client["Client Module"]:::core
            Common["Common Module"]:::core
        end

        %% Auxiliary Services Subgraph
        subgraph "Auxiliary Services"
            Logging["Logging Service"]:::aux
            Telemetry["Telemetry Service"]:::aux
            Status["Error Handling/Status"]:::aux
            Testing["Integration Testing"]:::aux
            Utilities["Utility Modules"]:::aux
        end
    end

    %% API and Platform Binding Layer
    subgraph "API and Platform Binding Layer"
        ApiDefs["API Definitions"]:::api
        Platform["Platform-Specific Features"]:::platform
        MobileBindings["iOS/Android Bindings"]:::platform
    end

    %% Configuration Flow
    Embedded -->|"mergedwith"| GenConfig
    ConfigDir -->|"providestemplate"| GenConfig
    GenConfig -->|"generates"| GlobalConfig
    GlobalConfig -->|"consumedby"| LibraryCore

    %% Proxy Core Interactions
    LibraryCore -->|"uses"| Chained
    LibraryCore -->|"uses"| Dialer
    LibraryCore -->|"uses"| Client
    LibraryCore -->|"dependson"| Common
    GlobalConfig -->|"configures"| Chained
    GlobalConfig -->|"configures"| Dialer
    GlobalConfig -->|"configures"| Client

    %% API Interactions
    ApiDefs -->|"definesprotocolsfor"| LibraryCore
    ApiDefs -->|"definesprotocolsfor"| MobileBindings

    %% Platform-specific Integration
    Platform -->|"integrateswith"| LibraryCore
    MobileBindings -->|"wraps"| LibraryCore

    %% External Integrations to Configuration
    ConfigServer -->|"feedsconfig"| GenConfig
    S3 -->|"storesglobalconfig"| GlobalConfig

    %% Auxiliary Services Links (undirected for supporting services)
    Logging --- LibraryCore
    Telemetry --- LibraryCore
    Status --- LibraryCore
    Testing --- LibraryCore
    Utilities --- LibraryCore

    %% Click Events
    click LibraryCore "https://github.com/getlantern/flashlight/blob/main/flashlight.go"
    click Common "https://github.com/getlantern/flashlight/tree/main/common/"
    click Chained "https://github.com/getlantern/flashlight/blob/main/chained/proxy.go"
    click Dialer "https://github.com/getlantern/flashlight/blob/main/dialer/dialer.go"
    click Client "https://github.com/getlantern/flashlight/blob/main/client/client.go"
    click Logging "https://github.com/getlantern/flashlight/blob/main/logging/logging.go"
    click Telemetry "https://github.com/getlantern/flashlight/blob/main/otel/otel.go"
    click Status "https://github.com/getlantern/flashlight/blob/main/status/status.go"
    click Testing "https://github.com/getlantern/flashlight/blob/main/integrationtest/integrationtest.go"
    click Utilities "https://github.com/getlantern/flashlight/tree/main/util/"
    click GenConfig "https://github.com/getlantern/flashlight/blob/main/genconfig/genconfig.go"
    click ConfigDir "https://github.com/getlantern/flashlight/blob/main/config/config.go"
    click Embedded "https://github.com/getlantern/flashlight/blob/main/embeddedconfig/global.yaml.tmpl"
    click ApiDefs "https://github.com/getlantern/flashlight/blob/main/apipb/types.proto"
    click Platform "https://github.com/getlantern/flashlight/blob/main/browsers/browsers.go"
    click MobileBindings "https://github.com/getlantern/flashlight/blob/main/common/platform_ios.go"

    %% Styles
    classDef external fill:#ffccff,stroke:#333,stroke-width:2px;
    classDef core fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef config fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef configStore fill:#e6ffcc,stroke:#333,stroke-width:2px;
    classDef api fill:#ffd9b3,stroke:#333,stroke-width:2px;
    classDef platform fill:#d9ffff,stroke:#333,stroke-width:2px;
    classDef aux fill:#fff2cc,stroke:#333,stroke-width:2px;
```
