# 176wer/flclash architecture

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

- Interactive diagram: https://gitdiagram.com/176wer/flclash
- Repository: https://github.com/176wer/flclash

## Overview

##### Main Components
- UI Layer (Flutter/Dart):
– Represented by the “lib” directory. This contains all the Flutter code including UI pages, widgets, state management, and fragments for components like dashboard, logs, proxy settings, and more.
– It also includes localization assets (lib/l10n), router configurations, and shared/common code under lib/common.

- Core Engine and Business Logic (Go):
– Found in the “core” directory, this is where the proxy core engine (Clash.Meta) resides.
– There is a “dart-bridge” subdirectory to interface the Go backend with Flutter via FFI (Foreign Function Interface). This provides a crucial bridge between the UI (Dart) and the native Go functionality.

- Platform-Specific Native Code:
– Directories such as “android”, “macos”, “windows”, “linux” contain platform-specific code (for example, Android Kotlin code and macOS Swift/Objective-C files).
– These modules handle platform integrations such as rendering, packaging, and specific service integrations (e.g. VPN service for Android or specific desktop integrations).

- Plugins and Extensibility:
– The “plugins” directory (e.g., proxy and flutter_distributor) indicates an extensible design where certain functionalities are implemented as plugins to be used within the main application.
– This is supported with platform interface code that facilitates communication between the core plugin logic and the native platforms.

- Assets and Resources:
– The “assets” folder holds necessary data (e.g. ASN.mmdb, GeoIP.dat), fonts, and images that the UI uses.

##### Understand Component Interactions and Relationships
- The UI also connects with native plugins or modules (like Android’s VPN service or macOS native containers) which further interact with the platform backends.
- Additionally, configuration data, native assets, and resource files are loaded from the assets directories – highlighting their role as auxiliary data providers.
- The plugin system (in the plugins folder) further extends functionality and should be included as separate blocks interacting with both the UI and native parts.

##### Architectural Patterns and Principles
- Multi-layered architecture: Separation of responsibilities across the presentation layer (Flutter UI), business logic/engine layer (Go core), and the platform-specific native layer.
- Use of FFI for bridging cross-language integration between Dart and Go.
- Modular design through plugins and separation of Flutter widgets, shared/common utilities, and screens.
- Adaptability and cross-platform facilitation are achieved with a clear separation between native code (platform folders) and portable UI code (lib).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "FlClash Application"
        subgraph "UI Layer (Flutter/Dart)"
            UI["Flutter UI (lib)"]:::ui
            FPlugins["Flutter Plugins (lib/plugins)"]:::plugin
        end

        subgraph "Core Engine (Go)"
            Core["Core Engine (core) - includes dart-bridge"]:::core
        end

        subgraph "Platform-Specific Native Code"
            Android["Android"]:::native
            macOS["macOS"]:::native
            Linux["Linux"]:::native
            Windows["Windows"]:::native
            NPlugin["Native Plugin Code (plugins)"]:::plugin
        end

        Assets["Assets & Resources (assets)"]:::asset
    end

    UI -->|"via_dart-bridge"| Core
    Core -->|"integrates_with"| Android
    Core -->|"integrates_with"| macOS
    Core -->|"integrates_with"| Linux
    Core -->|"integrates_with"| Windows

    UI <-->|"plugin_interface"| FPlugins
    FPlugins -->|"coordinated_with"| NPlugin

    NPlugin -->|"native_plugin"| Android
    NPlugin -->|"native_plugin"| macOS
    NPlugin -->|"native_plugin"| Linux
    NPlugin -->|"native_plugin"| Windows

    Assets -->|"supports"| UI
    Assets -->|"supports"| Android
    Assets -->|"supports"| FPlugins
    Assets -->|"supports"| NPlugin

    click UI "https://github.com/176wer/flclash/tree/main/lib"
    click Core "https://github.com/176wer/flclash/tree/main/core"
    click Android "https://github.com/176wer/flclash/tree/main/android"
    click macOS "https://github.com/176wer/flclash/tree/main/macos"
    click Linux "https://github.com/176wer/flclash/tree/main/linux"
    click Windows "https://github.com/176wer/flclash/tree/main/windows"
    click FPlugins "https://github.com/176wer/flclash/tree/main/lib/plugins"
    click NPlugin "https://github.com/176wer/flclash/tree/main/plugins"
    click Assets "https://github.com/176wer/flclash/tree/main/assets"

    classDef ui fill:#a8d5e2,stroke:#333,stroke-width:2px;
    classDef core fill:#b9f6ca,stroke:#333,stroke-width:2px;
    classDef native fill:#fff59d,stroke:#333,stroke-width:2px;
    classDef plugin fill:#ce93d8,stroke:#333,stroke-width:2px;
    classDef asset fill:#eeeeee,stroke:#333,stroke-width:2px;
```
