# JFFI

A cross-platform framework for building native applications with Rust business logic and platform-native UIs.

##  Philosophy

**Write your business logic once in Rust. Build native UIs for each platform.**

- Write business logic once in Rust
- Use native UI frameworks (SwiftUI, Jetpack Compose, WinUI, etc.)
- Get truly native performance and platform feel
- Maintain type safety end-to-end via UniFFI

##  Quick Start

### Installation

```bash
# Install JFFI CLI
cargo install --path cli
```

### Create Your First App

```bash
# Create a new app with platform support
jffi new my-app --platforms ios,macos,android,linux,windows

# Navigate and run
cd my-app
jffi run --platform ios      # iOS Simulator
jffi run --platform macos    # macOS app
jffi run --platform android  # Android Emulator
jffi run --platform linux    # Linux GTK app
jffi run --platform windows  # Windows app
# jffi run --platform web    # Web browser (🚧 In Progress)
```

That's it! The app builds, compiles Rust, generates platform bindings, and launches automatically.

**Note:** Web platform support is currently in progress. The frontend templates are created but the `ffi-web` integration is incomplete.

## 📱 Supported Platforms

| Platform | Status | UI Framework | Language |
|----------|--------|--------------|----------|
| iOS | ✅ Ready | SwiftUI | Swift |
| macOS | ✅ Ready | SwiftUI | Swift |
| Android | ✅ Ready | Jetpack Compose | Kotlin |
| Linux | ✅ Ready | GTK 4 + Libadwaita | Python |
| Web | 🚧 In Progress | Vanilla JS + WASM | JavaScript |
| Windows | ✅ Ready | WinUI 3 | C# |

## 🏗️ Project Structure

```
my-app/
├── core/                    # Pure Rust business logic
│   ├── src/lib.rs          # Your app logic here
│   └── Cargo.toml
│
├── ffi/                     # FFI layer (auto-scaffolded)
│   ├── src/lib.rs          # UniFFI exports
│   └── Cargo.toml
│
├── platforms/
│   └── ios/                # iOS SwiftUI app
│       ├── *App.swift
│       ├── AppState.swift
│       ├── ContentView.swift
│       └── *.xcodeproj     # Auto-generated
│
└── jffi.toml               # Framework configuration
```

##  Development Workflow

### 1. Write Business Logic (Once)

`core/src/lib.rs`:

```rust
pub struct App {
    items: Vec<Item>,
}

impl App {
    pub fn add_item(&mut self, id: String, title: String) {
        self.items.push(Item { id, title, completed: false });
    }
}
```

### 2. Expose via FFI (Auto-scaffolded)

`ffi/src/lib.rs`:

```rust
#[derive(uniffi::Object)]
pub struct FfiApp {
    app: Mutex<App>,
}

#[uniffi::export]
impl FfiApp {
    pub fn add_item(&self, id: String, title: String) -> Vec<ItemViewModel> {
        let mut app = self.app.lock().unwrap();
        app.add_item(id, title);
        app.get_items().iter().map(ItemViewModel::from).collect()
    }
}
```

### 3. Build & Run

**For iOS:**
```bash
jffi run --platform ios              # Simulator
jffi run --platform ios --device     # Physical device
```

**For Android:**
```bash
jffi run --platform android          # Emulator (auto-starts)
```

**For macOS:**
```bash
jffi run --platform macos
```

**For Linux:**
```bash
jffi run --platform linux
```

**For Web:**
```bash
jffi run --platform web
```

**For Windows:**
```bash
jffi run --platform windows
```

This automatically:
- **iOS/macOS**: Compiles Rust, generates Swift bindings, creates Xcode project, builds and launches
- **Android**: Compiles Rust for 3 architectures, generates Kotlin bindings, starts emulator, builds APK, installs and launches app
- **Linux**: Compiles Rust, generates Python bindings, installs dependencies (GTK 4, build tools), builds and launches GTK app
- **Web**: Compiles Rust to WASM, generates JavaScript bindings, installs npm dependencies, starts Vite dev server
- **Windows**: Compiles Rust, generates C# bindings with uniffi-bindgen-cs, builds with MSBuild/dotnet, launches WinUI 3 app

### 4. Use in Native UI

`platforms/ios/ContentView.swift`:

```swift
Button("Add Item") {
    appState.addItem(id: UUID().uuidString, title: newItem)
}
```

The generated bindings make Rust functions available in Swift!

## ⚡ Hot Reload

JFFI works seamlessly with native IDE hot reload plus automatic Rust rebuilding.

### iOS/macOS Workflow

```bash
# Start Rust file watcher
jffi dev --platform ios

# In Xcode:
# 1. Open platforms/ios/*.xcodeproj in Xcode
# 2. Run the app (Cmd+R)
# 3. Edit Swift files → Xcode hot reloads automatically ⚡
# 4. Edit Rust files → Watcher rebuilds dylib → Press Cmd+B in Xcode
```

### Android Workflow

```bash
# Start Rust file watcher + Android Studio
jffi dev --platform android

# In Android Studio:
# 1. Press ▶️ to run the app
# 2. Edit Kotlin files → Compose hot reloads automatically ⚡
# 3. Edit Rust files → Watcher rebuilds .so → Rebuild in Android Studio
```

### Linux Workflow

```bash
# Start Rust file watcher
jffi dev --platform linux

# The app will auto-restart when Rust code changes
# 1. Edit Python/GTK files → Save and re-run
# 2. Edit Rust files → Watcher rebuilds .so → App auto-restarts ⚡
```

### Web Workflow

```bash
# Start Rust file watcher + Vite dev server
jffi dev --platform web

# Vite provides hot reload for JS/CSS changes
# 1. Edit HTML/JS/CSS → Vite hot reloads instantly ⚡
# 2. Edit Rust files → Watcher rebuilds WASM → Refresh browser
```

### How It Works

**Native UI Changes:**
- **iOS/macOS**: Edit `.swift` files → Xcode hot reloads instantly
- **Android**: Edit `.kt` files → Compose hot reloads automatically
- **Web**: Edit `.js`/`.css` files → Vite hot reloads instantly
- Use native IDE features (SwiftUI previews, Compose previews, etc.)
- Full debugging support

**Rust Changes:**
- Edit any `.rs` file in `core/` or `ffi/`
- File watcher rebuilds Rust library automatically
- Rebuild in native IDE to use new Rust code
- App updates with new business logic

### Best of Both Worlds

✅ **Native IDE experience** - Use all platform IDE features
✅ **Native UI previews** - SwiftUI/Compose previews work
✅ **Native hot reload** - Instant UI updates
✅ **Rust auto-rebuild** - No manual cargo commands
✅ **Full debugging** - Native debuggers work normally

##  CLI Commands

```bash
# Create new project
jffi new <name> --platforms <platforms>

# Build for platform
jffi build --platform <platform>
jffi build --platform ios --device          # Build for physical device

# Run on platform (builds automatically)
jffi run --platform <platform>
jffi run --platform ios --device            # Run on physical device

# Development mode (auto-rebuild on changes)
jffi dev --platform <platform>

# Add platform to existing project
jffi add <platform>

# List available platforms
jffi platforms
```

##  How It Works

```
┌─────────────────────────────────────────┐
│     Your Rust Business Logic           │
│     (core/src/lib.rs)                   │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│     UniFFI FFI Layer                    │
│     (ffi/src/lib.rs)                    │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│     Auto-Generated Bindings             │
│     (Swift, Kotlin, C#, etc.)           │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│     Native Platform UI                  │
│     (SwiftUI, Compose, WinUI, etc.)     │
└─────────────────────────────────────────┘
```

##  Configuration

`jffi.toml`:

```toml
[package]
name = "my-app"
version = "0.1.0"

[platforms]
enabled = ["ios"]

[platforms.ios]
deployment_target = "16.0"
bundle_id = "com.example.myapp"
```

##  Why JFFI?

| Feature | JFFI | Flutter | React Native |
|---------|------|---------|--------------|
| Business Logic | Rust | Dart | JavaScript |
| UI | Native | Cross-platform | Near-native |
| Performance | Native | Good | Good |
| Platform Feel | Native | Consistent | Near-native |
| Type Safety | End-to-end | Strong | Weak |

**Use JFFI when:**
- You want truly native UI and performance
- You have platform-specific design requirements
- You want to leverage native UI libraries
- You need Rust for business logic (performance, safety)

## 🛠️ Development

### Prerequisites

- Rust toolchain
- **iOS**: Xcode, iOS Simulator
- **Android**: Android Studio, Android SDK, Android Emulator (auto-configured)
- **macOS**: Xcode
- **Linux**: GTK 4, Libadwaita, Python 3 (auto-installed by setup script)
- **Web**: Node.js, npm (for Vite dev server)
- **Windows**: .NET SDK 8.0+, Visual Studio Build Tools or MSBuild

### Building the CLI

```bash
cargo build --package jffi
cargo run --package jffi -- --help
```

## Roadmap

- [x] CLI tool foundation
- [x] iOS support with SwiftUI
- [x] macOS support with SwiftUI
- [x] Android support with Jetpack Compose
- [x] Linux support with GTK 4 + Python
- [ ] Web support with Vanilla JS + WASM (frontend templates created, ffi-web integration incomplete)
- [x] Windows support with WinUI 3 + C#
- [x] Automatic Xcode project generation
- [x] Automatic Android project generation
- [x] One-command build and run (iOS, macOS, Android, Linux, Windows)
- [x] Hot reload for iOS (Xcode-native workflow)
- [x] Hot reload for Android (Android Studio-native workflow)
- [x] Hot reload for Linux (auto-restart workflow)
- [ ] Hot reload for Web (Vite hot reload - pending ffi-web completion)
- [x] Automatic emulator/simulator management
- [x] Auto-install build dependencies (targets, NDK, GTK, WASM, wasm-bindgen, uniffi-bindgen-cs, etc.)

## 🤝 Contributing

Early-stage framework. Contributions welcome!

**High priority:**
- **Complete web platform support** (create ffi-web crate with wasm-bindgen integration)
- Additional platform features and improvements
- State persistence (SQLite/local storage)
- Advanced UI components and patterns
- Hot reload for Windows (file watcher workflow)

## 📄 License

MIT

##  Acknowledgments

- [UniFFI](https://github.com/mozilla/uniffi-rs) - FFI bindings generator
- The Rust community

---

**Built with  and Rust**
