ChatForge Flutter Native Client Build Guide

This repository currently contains:

• The native client architecture plan at docs/native-client-architecture-plan.md.
• The complete backend/web API implementation at chatforge-web/.

The Flutter app workspace is not scaffolded yet in this repository. This README explains how to create it and build Android/Linux/Windows binaries against the existing ChatForge API.

1. Prerequisites

1. Install Flutter SDK (stable channel) and run:

flutter doctor

2. Install platform toolchains you need:

• Android: Android Studio + SDK + emulator/device.
• Linux desktop: clang, cmake, ninja, GTK development packages.
• Windows desktop (optional): Visual Studio with Desktop C++ workload.

3. Install Node.js 20+ for the backend in chatforge-web/.

2. Start the ChatForge Backend API

From the repository root:

cd chatforge-web
npm install
cp .env.example .env

Set at least CHATFORGE_SECRET in .env, then create a test user:

npm run user:create -- <username> <password> admin

Run backend + web dev server:

npm run dev

If you only need the API server:

npm run dev:server

Default API base URL is http://localhost:3069/api.

3. Bootstrap the Flutter Workspace

From repository root:

flutter create flutter --project-name chatforge_native --platforms=android,linux,windows
cd flutter

Recommended packages for this architecture:

flutter pub add flutter_riverpod dio flutter_secure_storage device_info_plus package_info_plus

4. Runtime Configuration

Pass API base URL with --dart-define:

flutter run \
  --dart-define=CHATFORGE_API_BASE_URL=http://10.0.2.2:3069/api

Use these base URLs depending on target:

• Android emulator: http://10.0.2.2:3069/api
• Linux desktop on same machine: http://127.0.0.1:3069/api
• Physical device: http://<your-host-lan-ip>:3069/api

5. API/Auth Contract to Implement in Flutter

Use Bearer auth for native clients.

Login:

• POST /auth/native/login
• Body includes username, password, and device metadata (platform, device_name, device_model, os_version, app_version).
• platform must be android, linux, or windows.

Refresh:

• POST /auth/native/refresh
• Body: refresh_token
• Rotate and persist the returned new refresh token every time.

Logout:

• POST /auth/native/logout
• Body: refresh_token or revoke current session_id via bearer auth.

Device-link flow:

• POST /auth/device/authorize
• POST /auth/device/token (polling)
• POST /auth/device/approve (from authenticated web session)

Session management:

• GET /auth/devices
• DELETE /auth/devices/:sessionId

Attach Authorization: Bearer <access_token> on protected endpoints (including POST /stream for chat generation).

6. Build Commands

From flutter/:

Build Android + Linux AppImage release artifacts in one command (defaults to https://chat.n9x.co/api):

./scripts/build_release_artifacts.sh

Optional override:

CHATFORGE_API_BASE_URL=https://your-host/api ./scripts/build_release_artifacts.sh

Android release signing (required for Play/release artifacts):

cp android/key.properties.example android/key.properties
# edit android/key.properties with your real keystore passwords/alias

Android APK:

flutter build apk \
  --dart-define=CHATFORGE_API_BASE_URL=https://chatforge.example.com/api

Android App Bundle:

flutter build appbundle \
  --dart-define=CHATFORGE_API_BASE_URL=https://chatforge.example.com/api

Linux desktop:

flutter build linux \
  --dart-define=CHATFORGE_API_BASE_URL=https://chatforge.example.com/api

Windows desktop:

flutter build windows \
  --dart-define=CHATFORGE_API_BASE_URL=https://chatforge.example.com/api

7. Versioning

Use flutter/pubspec.yaml as the single source of truth:

• version: <semver>+<build_number> (for example 1.2.3+45)
• Semver portion (1.2.3) is written to flutter/version.txt

Generate/sync version.txt manually:

cd flutter
./scripts/version.sh --semver --write-version-file

Release build scripts already call this helper automatically.

8. Backend Environment Variables Relevant to Native Clients

Set these in chatforge-web/.env as needed:

• CHATFORGE_ACCESS_TOKEN_EXPIRY (default 15m)
• CHATFORGE_REFRESH_TOKEN_EXPIRY_DAYS (default 90)
• CHATFORGE_DEVICE_CODE_EXPIRY_MIN (default 10)
• CHATFORGE_DEVICE_CODE_POLL_INTERVAL_SEC (default 5)
• CHATFORGE_PASSKEY_ANDROID_SHA256_CERT_FINGERPRINTS (comma-separated SHA-256 cert fingerprints for Android signing certs, used to derive Android passkey origins such as android:apk-key-hash:...)
• CHATFORGE_DEVICE_VERIFICATION_URI (optional override for device-link approval URL)
• CHATFORGE_TRUST_PROXY (important when behind reverse proxy so IP/session metadata is correct)

9. Verification Checklist

1. Native login returns access_token, refresh_token, and session.
2. A forced access-token expiry is recovered by refresh rotation.
3. GET /auth/devices shows the current native session.
4. Revoking the session invalidates further refresh attempts.
5. POST /stream works with bearer auth and streams chat responses.