Core Concepts & Architecture

Chattree is an AI chat app with on-device model support, remote provider integrations, built-in Notes and Reminders, and slash-command tools inside a WebAssembly sandbox. With local inference selected, prompts are processed on-device; remote provider use sends request context to the selected provider.

---

Architectural Overview

Chattree is structured into decoupled, modular layers:

┌─────────────────────────────────────────────────────────────┐
│                       Flutter UI Layer                      │
│   Chat Screen  ·  Command Palette  ·  Settings  ·  Marketplace │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                      Chat Controller                        │
│   Intent Routing  ·  Token Streaming  ·  Prompt Assembly    │
└───────────────┬──────────────────────────────┬──────────────┘
                │                              │
                ▼                              ▼
┌─────────────────────────────┐ ┌─────────────────────────────┐
│   Local Inference Engine    │ │   External AI Subsystem     │
│   LlamaFlutterEngine (GGUF) │ │   RemoteInferenceEngine     │
│   On-Device Embeddings      │ │   OpenAI / Gemini / Claude  │
└───────────────┬─────────────┘ └──────────────┬──────────────┘
                │                              │
                ▼                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Vector RAG Subsystem                     │
│   Notes & Reminders Store (SQLite + Local Vector Index)     │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│              WebAssembly Plugin Runtime (WASM)              │
│   PluginLoader  ·  Linear Memory Sandbox  ·  Fuel Metering  │
└──────────────────────────────┬──────────────────────────────┘
                               │ host_call()
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                  ChattreeHostApi Bridge                     │
│   PermissionGateway  ·  Namespace Handlers (Storage/Net)   │
└─────────────────────────────────────────────────────────────┘

---

1. On-Device Inference Engine

At the core of Chattree is its local inference engine:

• Quantized GGUF Model Execution: Runs lightweight LLMs directly on the smartphone's CPU, GPU, or NPU with no network connectivity required.
• Local inference: When an on-device model is selected, inference runs locally. Conversation history is stored in app-local storage. Remote inference sends request context to the selected provider.
• Streaming Response: Generates tokens in real time, dispatched through an asynchronous stream with a 33ms throttle (~30 FPS) for smooth visual rendering.

---

2. Vector Retrieval-Augmented Generation (RAG)

Chattree incorporates an on-device vector search pipeline:

• Local Embeddings: When a note is created or edited (or when a plugin indexes a document via ai.embeddings), an on-device embedding model produces a dense vector representation.
• Vector Index: Vectors are indexed in an embedded database alongside note and plugin document content.
• Context Augmentation: During conversation, relevant notes and indexed documents matching the user's query via cosine similarity are retrieved and injected into the model's context window.
• Deterministic Removal: Deleting a note or plugin document automatically deletes its corresponding vector index entries.

---

3. WebAssembly Plugin Sandbox

To extend chat capabilities without exposing device security, Chattree runs plugins as isolated WebAssembly modules:

• WASM 1.0 MVP + Bulk Memory: Supports standard WebAssembly binaries compiled from WAT, Rust, C, C++, or Zig.
• Linear Memory Protocol: Plugins operate within an isolated linear memory buffer (default maximum 32 MB, with support for payloads up to 16 MB in ABI v2 or configurable offsets in ABI v1).
• Instruction Fuel Limits: Every plugin call is allocated an instruction budget (default 50,000,000 instructions) and a 5-second timeout, preventing infinite loops and freezing.
• No Direct System Access: Plugins cannot access operating system sockets, filesystem paths, threads, or hardware directly.

---

4. The Host API Bridge (ChattreeHostApi)

Plugins communicate with Chattree through a single imported function:

(import "chattree" "host_call" (func (param i32 i32 i32 i32) (result i32)))

Call Protocol

1. Request: The plugin writes a JSON request payload into its linear memory at reqPtr.
2. Dispatch: The plugin calls host_call(reqPtr, reqLen, resPtr, resMaxLen).
3. Permission Check: The PermissionGateway intercepts the call and verifies that the plugin possesses the declared and user-granted capability.
4. Execution:
   • Synchronous Operations (e.g., storage.*, core.*): Executed immediately. The return value is the byte length written to resPtr.
   • Asynchronous Operations (e.g., network.*, chattree.notes.*): Returns 0 immediately. The host performs the operation asynchronously and invokes the plugin's exported resume(resPtr, resLen) function once complete.
5. Memory Safety: If reqLen or resMaxLen exceeds allocated memory boundaries, host_call returns -1 and aborts.
6. Direct Markdown & Declarative Interactive UI: When a plugin outputs formatted Markdown, Chattree renders it straight into the chat bubble via Flutter's rich Markdown engine and completely bypasses the secondary LLM pass. Furthermore, plugins declaring ui.components can emit rich interactive cards (badges with color or monochrome variants, progress bars, key-value tables and list items up to 40 entries, hideText: true card-only responses, and button rows up to 8 buttons) with built-in security modals for sensitive command confirmation.
7. Extended Host Capabilities: Includes full-duplex WebSockets (network.websocket, up to 10 sockets, 16 MB frame cap, 500 queued frames buffer), scheduled Cron tasks with anti-battery drain protection (scheduler.task, minimum 60s interval, up to 25 tasks), and dedicated private relational SQLite databases (database.sql, up to 200 MB quota with atomic transactions and sandbox isolation).

---

5. Dynamic Permission Gateway

Chattree implements a capability-based security model:

• Normal Capabilities: Low-risk sandbox privileges (such as storage.private or share.text) granted automatically.
• Sensitive Capabilities: Network requests, file access, and note management are controlled through the app permission gateway; consent timing depends on the operation and current grant state.
• Critical Capabilities: Device capabilities can require explicit user consent and operating-system permission, depending on platform and operation.
• User Control: Users can inspect, modify, or revoke permissions at any time from Settings → Plugins → [Plugin] → Permissions.

---

6. Generative Visual Design Subsystem (/visual)

Chattree integrates a specialized vector design pipeline:

• Natural Language Vector Generation: Generates and refines professional SVG vector graphics (advertisements, marketplace cards, infographics, branding) through /visual.
• Two-Pass Self-Correction: Resilient multi-pass loop that automatically diagnoses and recovers from unclosed XML tags or model truncation errors.
• Strict SVG Sanitizer: Enforces a secure whitelist of static vector elements and strips scripts, external URLs, and event listeners.
• Interactive UI: Interactive zoom/pan preview, SVG/PNG export, and contextual design modification.

For full architectural details and developer APIs, refer to the Visual Design Architecture Guide.

---

7. Inbound Webhooks & Local Event Pipeline

Chattree incorporates a secure event pipeline for integrating local workflows, terminal tools, and external automation:

• Foreground HTTP Listener: Binds to 127.0.0.1 by default (InboundHttpServer) with an optional user-enabled LAN/Wi-Fi mode (0.0.0.0), configurable port, and persistent user preferences.
• HMAC-SHA256 Signatures & SSRF Guard: Payload integrity and authenticity verified with timing-safe HMAC checks; SSRF protection prevents network abuse.
• Persistent Event Journal: Events and delivery receipts are committed to SQLite (EventJournal) with deduplication by idempotency keys, guaranteeing delivery even across app restarts.
• Decoupled Consumer Dispatch: Events are published via HostEventBus and routed to registered WebAssembly plugin handlers without blocking the UI.

For comprehensive protocol and integration details, see the Inbound Webhooks Guide.

---

8. Android Background Execution & Safety Model

Chattree adheres to strict Android battery and resource guidelines:

• Exact Alarms via AlarmManager: Reminders schedule OS-level exact alarms through flutter_local_notifications. When a reminder fires, the Android OS delivers the notification immediately without requiring Chattree to run a persistent background service.
• Foreground Listener with Auto-Resume: Network server sockets on mobile platforms cannot remain active when apps are suspended in the background without high-drain Foreground Services. Chattree cleanly suspends the webhook listener when minimized and automatically resumes it when returned to the foreground.
• Explicit Command Routing: To guarantee user safety and predictable AI behavior, tools are invoked deterministically through explicit slash commands (/note, /reminder, /visual, and third-party plugins). The AI model does not covertly trigger side-effects during conversational text generation.