# AOP Logistics — Desktop App (Tauri)

The frontend can be packaged as a Windows desktop application using **Tauri v2**.
The backend (Laravel) stays on cPanel and is reached over HTTPS — the desktop app
is just a thin native shell around the existing web UI.

---

## How it works

```
┌─────────────────────────────────────┐
│  Windows Desktop (.exe / .msi)      │
│                                     │
│  ┌─────────────────────────────┐    │
│  │  Tauri shell (Rust, ~3 MB)  │    │
│  │  WebView2 (built into Win)  │    │    HTTPS API calls
│  │  ┌───────────────────────┐  │    │ ─────────────────▶  cPanel Server
│  │  │  Next.js static files │  │    │                      Laravel backend
│  │  │  (HTML / JS / CSS)    │  │    │
│  │  └───────────────────────┘  │    │
│  └─────────────────────────────┘    │
└─────────────────────────────────────┘

Installer size: ~10–15 MB
RAM usage:      ~60–100 MB
```

- **No Chromium bundled** — uses Windows' built-in WebView2 engine
- **No Node.js server** — Next.js is exported as static files at build time
- **Auth** — Zustand token store persists to `localStorage` (same as browser)
- **API** — Axios hits the cPanel HTTPS endpoint, identical to the web version

---

## Prerequisites (one-time setup)

### 1. Install Rust

```powershell
# Download and run from https://rustup.rs
rustup-init.exe
# Accept defaults. Restart terminal after.
rustup update stable
```

### 2. Install Visual Studio C++ Build Tools

Required by Rust on Windows. Install via:  
https://visualstudio.microsoft.com/visual-cpp-build-tools/  
Select **"Desktop development with C++"** workload.

### 3. Verify WebView2 is installed

Already present on Windows 10 (21H2+) and Windows 11.  
If needed: https://developer.microsoft.com/en-us/microsoft-edge/webview2/

### 4. Install Node dependencies (from inside `frontend/`)

```bash
cd frontend
npm install
```

This installs `@tauri-apps/cli` and `cross-env` alongside the existing deps.

---

## Step-by-step build flow

### Step 1 — Set the backend API URL

Inside `frontend/`, copy the example env file:

```bash
copy .env.production.local.example .env.production.local
```

Edit `.env.production.local` and set your actual cPanel URL:

```
NEXT_PUBLIC_API_URL=https://yourdomain.com/api/v1
```

> This value is baked into the JavaScript bundle at build time.
> The desktop app will always call this URL.

---

### Step 2 — Generate app icons

Tauri needs icons in multiple sizes. Run this once from inside `frontend/`:

```bash
npx @tauri-apps/cli icon ./public/aop.jpeg
```

This reads `public/aop.jpeg` (the existing company logo) and writes all required
sizes into `src-tauri/icons/`:

```
src-tauri/icons/
  32x32.png
  128x128.png
  128x128@2x.png
  icon.ico          ← Windows taskbar / installer icon
  icon.icns         ← macOS (ignored for Windows builds)
```

---

### Step 3 — Update CORS on the Laravel backend

The desktop app sends requests with origin `https://tauri.localhost`. The Laravel
backend must allow this. On cPanel, edit the `.env` file and add the Tauri origins:

```env
CORS_ALLOWED_ORIGINS=https://yourfrontenddomain.com,https://tauri.localhost,tauri://localhost
```

Then clear the config cache:

```bash
php artisan config:clear
php artisan cache:clear
```

---

### Step 4 — Build the desktop app

From inside `frontend/`:

```bash
npm run build:desktop
```

**What happens internally:**

```
npm run build:desktop
  └── tauri build
        ├── runs: npm run build:export
        │     └── cross-env BUILD_DESKTOP=1 next build
        │           → generates frontend/out/  (static HTML/JS/CSS)
        └── compiles Rust shell
        └── bundles out/ into the binary
        └── produces installer in src-tauri/target/release/bundle/
```

Output files (in `frontend/src-tauri/target/release/bundle/`):

```
nsis/
  AOP Logistics_1.0.0_x64-setup.exe   ← standard Windows installer
msi/
  AOP Logistics_1.0.0_x64_en-US.msi   ← MSI package
```

Share either file with users. Double-click to install.

---

## Development mode (optional)

To run the app in Tauri's WebView2 window during development (with live reload):

```bash
cd frontend
npm run dev:desktop
```

This starts the Next.js dev server on port 3000 and opens a native window pointing
to it. API calls go to whatever `NEXT_PUBLIC_API_URL` is set to in `.env.local`.

---

## Updating the app

When the web UI changes:

1. Pull latest code
2. Run `npm run build:desktop` from inside `frontend/`
3. Distribute the new installer from `src-tauri/target/release/bundle/`

Users must install the new version manually (replace the old one).  
The installer handles upgrades cleanly — no leftover files.

---

## Key differences from the web version

| Feature | Web | Desktop |
|---|---|---|
| Route protection | Next.js middleware (server-side) | Client-side only (Zustand auth check in layout) |
| Login redirect if already authed | Middleware handles it | `useEffect` in login page handles it |
| `next/image` optimization | CDN/server | Disabled (`unoptimized: true`) |
| API URL | Runtime env | Baked in at build time |
| File downloads (CSV/PDF) | Browser handles | WebView2 handles (same behaviour) |

---

## Project structure added

```
frontend/
├── src-tauri/
│   ├── tauri.conf.json       ← window size, bundle config, build commands
│   ├── Cargo.toml            ← Rust dependencies
│   ├── build.rs              ← Tauri build script
│   ├── capabilities/
│   │   └── default.json      ← Tauri permissions
│   ├── icons/                ← generated by: npx tauri icon ./public/aop.jpeg
│   └── src/
│       ├── main.rs           ← entry point
│       └── lib.rs            ← Tauri app builder
├── .env.production.local.example   ← template for desktop API URL
└── next.config.js            ← BUILD_DESKTOP env var enables static export
```

---

## Troubleshooting

**`error: linker 'link.exe' not found`**  
→ Install Visual Studio C++ Build Tools (Step 2 above)

**`WebView2 is not installed`**  
→ Download the WebView2 Evergreen runtime from Microsoft

**`icons/32x32.png not found`**  
→ Run `npx @tauri-apps/cli icon ./public/aop.jpeg` (Step 2)

**API calls fail / CORS error**  
→ Add `https://tauri.localhost` and `tauri://localhost` to `CORS_ALLOWED_ORIGINS` in cPanel `.env` (Step 3)

**App shows blank screen after install**  
→ Check that `NEXT_PUBLIC_API_URL` was set correctly in `.env.production.local` before building.  
   Open DevTools: right-click anywhere → Inspect (only works in debug builds).

**`next build` fails with `output: export` error**  
→ Run `npm run build` (web build, no `BUILD_DESKTOP`) to confirm which page fails,
   then check that no server components are added.