# fluttercandies/fjs architecture

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

- Interactive diagram: https://gitdiagram.com/fluttercandies/fjs
- Repository: https://github.com/fluttercandies/fjs

## Overview

##### Project type and purpose
- This is not a typical frontend/backend app but a cross-platform Flutter plugin (“fjs”) that embeds a JavaScript engine into Flutter via Rust and QuickJS.
- It provides a high-performance JS runtime with Dart bindings, built-time tools (cargokit) to compile native libraries for Android, iOS, Linux, macOS, and Windows, and example apps demonstrating usage.

##### File structure
- Top-level components:
- android, ios, linux, macos, windows — platform-specific plugin code and build configurations
- lib — Dart library exposing JsEngine, JsValue, and API
- libfjs — Rust crate containing the QuickJS binding and engine implementation
- cargokit — CLI/build tool (Dart) to orchestrate cross-platform Rust builds (build_tool, cmake, gradle, pods scripts)
- example — sample Flutter app that integrates the plugin on each platform
- test_driver — integration test harness
- Patterns:
- Plugin pattern: Flutter → Dart API → FFI → native library
- Build orchestration: cargokit’s build_tool drives rustup, cargo, CMake, Gradle, Pod builds
- Key configs:
- pubspec.yaml (plugin meta, Dart deps)
- flutter_rust_bridge.yaml (codegen for FFI bindings)
- build.gradle, CMakeLists.txt, Podspecs (platform packaging)
- analysis_options.yaml, build.yaml (lint and build rules)

##### README for additional insights
- Confirms architecture: Dart initializes LibFjs, creates JsAsyncRuntime/JsAsyncContext, spins up QuickJS under the hood.
- Describes bridge_call mechanism, built-in modules, memory management, and module loading.
- Emphasizes cross-platform support and advanced use cases.

a. Main components
1. Flutter Application (example or end user app)
2. Dart FJS API Layer (lib/fjs.dart, lib/src)
3. FFI Bridge (generated via flutter_rust_bridge)
4. Native Engine Library (libfjs compiled into .so/.dylib/.dll)
5. QuickJS Core (bundled within libfjs; garbage collector, module loader)
6. Cargokit Build Tool (Dart build_tool + cmake/gradle/pod scripts)
7. Platform-specific package managers (Gradle for Android, CocoaPods for iOS/macOS, CMake for Linux/Windows)
b. Relationships and interactions
- The Flutter app imports the Dart FJS API.
- Dart API calls into the native engine via FFI.
- The native engine uses QuickJS to parse/evaluate JS, manages memory and modules.
- Bridge calls from JS invoke callbacks in Dart via FFI.
- Cargokit orchestrates compilation of libfjs for each target before publishing.
c. Architectural patterns and design principles
- Plugin architecture with clear separation: UI → framework → native.
- FFI boundary with generated bindings for type safety.
- Single-source Rust crate reused across all platforms.
- Build automation tooling (cargokit) to avoid manual multi-platform builds.
d. Key technologies, frameworks, libraries
- Flutter/Dart, flutter_rust_bridge, QuickJS, Rust, Cargo, CMake, Gradle, CocoaPods, shell scripts.

##### Final advice
- Be highly detailed: capture both runtime invocation and build-time orchestration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Runtime Flow"
        App["Flutter App"]:::runtime
        DartAPI["Dart FJS API Layer"]:::runtime
        FFI["FFI Bridge"]:::runtime
        Native["Native Engine Library (libfjs)"]:::runtime
        QuickJS["QuickJS Core"]:::runtime
        App -->|"calls API"| DartAPI
        DartAPI -->|"FFI Calls"| FFI
        FFI -->|"Native Calls"| Native
        Native -->|"JS Eval"| QuickJS
        QuickJS -->|"Bridge Callback"| FFI
        FFI -->|"Returns"| DartAPI
        DartAPI -->|"Result"| App
    end

    subgraph "Build Flow"
        Cargokit["Cargokit Build Tool"]:::build
        Toolchains["Target Toolchains (rustup, cargo, CMake, Gradle, Pods)"]:::build
        Artifacts["Native Artifacts (.so, .dll, .dylib)"]:::build
        Cargokit -->|"orchestrates"| Toolchains
        Toolchains -->|"produces"| Artifacts
    end

    subgraph "Platform Packaging"
        Android["Android Packaging"]:::packaging
        iOS["iOS Packaging"]:::packaging
        macOS["macOS Packaging"]:::packaging
        Linux["Linux Packaging"]:::packaging
        Windows["Windows Packaging"]:::packaging
        Artifacts --> Android
        Artifacts --> iOS
        Artifacts --> macOS
        Artifacts --> Linux
        Artifacts --> Windows
    end

    Config["Project Configuration & Metadata"]:::config
    Integration["Integration Test Harness"]:::build

    Config --> App
    Config --> Cargokit
    Config --> Integration

    click App "https://github.com/fluttercandies/fjs/blob/main/example/lib/main.dart"
    click DartAPI "https://github.com/fluttercandies/fjs/blob/main/lib/fjs.dart"
    click DartAPI "https://github.com/fluttercandies/fjs/blob/main/lib/src/engine.dart"
    click FFI "https://github.com/fluttercandies/fjs/blob/main/flutter_rust_bridge.yaml"
    click FFI "https://github.com/fluttercandies/fjs/blob/main/lib/src/frb/frb_generated.dart"
    click FFI "https://github.com/fluttercandies/fjs/blob/main/libfjs/src/frb_generated.rs"
    click Native "https://github.com/fluttercandies/fjs/blob/main/libfjs/src/lib.rs"
    click Cargokit "https://github.com/fluttercandies/fjs/blob/main/cargokit/build_tool/bin/build_tool.dart"
    click Cargokit "https://github.com/fluttercandies/fjs/blob/main/cargokit/build_pod.sh"
    click Android "https://github.com/fluttercandies/fjs/blob/main/android/build.gradle"
    click iOS "https://github.com/fluttercandies/fjs/blob/main/ios/fjs.podspec"
    click macOS "https://github.com/fluttercandies/fjs/blob/main/macos/fjs.podspec"
    click Linux "https://github.com/fluttercandies/fjs/blob/main/linux/CMakeLists.txt"
    click Windows "https://github.com/fluttercandies/fjs/blob/main/windows/CMakeLists.txt"
    click Integration "https://github.com/fluttercandies/fjs/blob/main/test_driver/integration_test.dart"
    click Config "https://github.com/fluttercandies/fjs/blob/main/pubspec.yaml"
    click Config "https://github.com/fluttercandies/fjs/blob/main/build.yaml"

    classDef runtime fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef build fill:#c8e6c9,stroke:#388e3c,color:#1b5e20;
    classDef packaging fill:#ffe0b2,stroke:#fb8c00,color:#e65100;
    classDef config fill:#e0e0e0,stroke:#757575,color:#212121;
```
