Pathfinder — Component Architecture

Rust / Backend

React / Frontend

Storage

Gateway / External

FRONTEND

⌨️

ChatPanel.tsx

Streaming chat UI. Tools/Memory toggles. Agent loop routing. Conversation history. Abort controller.

React 19 · streaming

⚙️

Settings — 11 Panels

Registry-driven panel system. API keys, Gateway, Scheduler, Personas, Soul, Logs, Knowledge, Credentials.

PANEL_REGISTRY · Settings.tsx

🔐

VaultUnlock.tsx

Passphrase gate. Vault state machine: loading → locked → first-run → unlocked. Auto-starts Telegram gateway.

App.tsx vault gate

📊

Scheduler UI

Create/edit/delete cron jobs. Run now. Jobs tab + Run Log tab. Per-job history button. Telegram delivery.

Jobs · Run Log · History

COMMANDS

🤖

agent_chat

Agent loop up to 5 iterations. Tool parse → execute → inject. Dedup check. Short-circuit when no tools. Unknown tool recovery.

agent.rs · 10 unit tests

👤

Persona Commands

get_personas · create_persona · update_persona · delete_persona. Vault key resolution per persona. Tier enforcement.

commands/persona.rs

💬

Conversation + Memory

get/create/delete conversations and messages. get_memories · add_memory · delete_memory. count_memories.

conversation.rs · memory.rs

🔑

Vault Commands

vault_create · vault_unlock · vault_lock · vault_set · vault_get · vault_delete · vault_list_keys. encrypt_blob · decrypt_blob.

commands/vault.rs

SERVICES

🔧

Tool Factory

ALL_TOOLS registry. Tier + key gating. tool_descriptions() for system prompt injection. execute_tool() dispatcher.

tools/ · tier gated

🗂️

Services Layer

Business logic — DB queries, crypto. persona.rs · conversation.rs · memory.rs · vault.rs. Thin commands delegate here.

services/ · AppResult<T>

⏰

Scheduler Engine

scheduler_engine.rs loads enabled jobs on startup. Fires on cron. One-shot auto-disable. Telegram delivery via vault chat ID.

scheduler_engine.rs · tokio

📡

Gateway Handler

Gateway trait → shared handler → OutboundMessage. call_llm_direct for all providers. Telegram via teloxide 0.17.

gateway/ · handler.rs

LLM Providers

◆

Anthropic

Sonnet 4.6 · Opus 4.6 · Haiku 4.5

Pioneer+ · vault key

◆

Google

Gemini 2.5 Flash · 2.0 Flash

Pioneer+ · vault key

◆

OpenAI

GPT-4o · GPT-4o mini

Pioneer+ · vault key

◆

Ollama

qwen3 (preferred) · llama3.2 · gemma4

Scout+ · localhost:11434

◆

BitNet

1-bit quantized · CPU only

Scout+ · localhost:11435

Local Storage

🗄️

pathfinder.db

SQLite WAL · rusqlite 0.37 bundled · 18 migrations. Tables: personas, conversations, messages, memories, credentials, scheduled_jobs, job_runs, knowledge_chunks, pathfinder_logs.

app_data_dir/

🔐

pathfinder.vault

AES-256-GCM · PBKDF2/SHA-256 100k iterations · zeroize on drop. Stores API keys, credentials passwords, gateway config, data folder path.

app_data_dir/ · never leaves

📁

data/ folder

memory/ · conversations/ · knowledge/ · journal/ · soul/. Resolved via vault key shared.data_folder.

C:\aPathfinderTauri\data\

Gateway / External

📱

Telegram Gateway

teloxide 0.17 · polling mode · no public IP. Separate async DB connection. PIN per persona. Sender whitelist. Auto-starts on vault unlock.

gateway/telegram.rs

⚡

n8n Workflows

Single global webhook URL. Intent-based routing inside workflow. Chunky payload: intent + query + timestamp + persona context.

shared.keys.n8n_webhook

🔍

Serper / Web Search

Google search via Serper API. Tool factory entry. Tier + key gated. Results injected into agent loop context.

Pioneer+ · shared.keys.serper

📅

Google Calendar

Read events via n8n + Google OAuth. "What do I have tomorrow?" returns real calendar data.

via n8n · OAuth2

Information Flow — A Single Message (Tools ON)

⌨️

User sends message

ChatPanel builds history with system prompt + memories + docs context. Invokes agent_chat.

💾

Memory injected

Top 4 persona-scoped memories fetched from SQLite. Injected as system context before LLM call.

🔧

Agent loop starts

Tools filtered by tier + vault keys. Tool descriptions appended to system prompt. call_llm_direct fires.

🔍

Tool parsed + executed

parse_tool_call extracts tool ID + JSON. Tool executes. Result injected as system message. Loop continues.

🤖

LLM final answer

No tool call detected → final response returned. AgentResult with response + tool_calls + iterations.

📝

Tool calls logged

pathfinder_logs table updated. ToolCallRecord[] serialized as tools_used JSON on message row.

💾

Message saved

User + assistant messages written to messages table with model, provider, tools_used.

📺

UI rendered

Response rendered with markdown. ToolCallLog.tsx shows collapsible tool call records. Memory count updates.

📱

Telegram mirror

If triggered via gateway: same pipeline. Response sent back via teloxide. Scheduler jobs deliver same way.

♻️

Ready

All state persisted in SQLite WAL. Vault remains unlocked in RAM. Gateway polling continues.

Rust Project Structure

src-tauri/src/ ├── main.rs ← entry, calls lib::run() ├── lib.rs ← AppState, builder, invoke_handler ├── db.rs ← SQLite open, 18 migrations, seed ├── error.rs ← AppError enum, AppResult<T> ├── commands/ ← thin Tauri handlers │ ├── agent.rs ← agent loop + parse_tool_call │ ├── persona.rs │ ├── vault.rs │ ├── memory.rs │ └── logs.rs ├── services/ ← business logic ├── gateway/ ← Gateway trait + teloxide │ ├── handler.rs ← call_llm_direct │ └── telegram.rs ├── tools/ ← ALL_TOOLS registry └── scheduler_engine.rs

Frontend Structure

src/ ├── App.tsx ← vault gate · first-run ├── components/ │ ├── layout/ │ │ └── AppShell.tsx ← main shell │ ├── chat/ │ │ └── ChatPanel.tsx │ ├── settings/ │ │ └── Settings.tsx ← PANEL_REGISTRY │ └── ui/ │ └── VaultUnlock.tsx ├── services/ ← invoke() wrappers only │ ├── LLMService.ts │ ├── VaultService.ts │ └── providers/ └── types/ ← mirror Rust structs data/ ← local user data ├── memory/ knowledge/ ├── journal/ conversations/ └── soul/ pathfinder.vault ← AES-256-GCM pathfinder.db ← SQLite WAL

Build Blocks — Pathfinder v0.1.5

BLOCK 1

Scaffold

Tauri 2 · Rust · React 19 · SQLite · Vault · AppState

BLOCK 2

Frontend Shell

Vault gate · 5 LLM providers · streaming · memory injection

BLOCK 3

Gateway

Telegram · teloxide · PIN auth · persona routing · vault resolution

BLOCK 4

Scheduler

Cron engine · one-shot · Telegram delivery · job run history

BLOCK 5

Agent Loop

Tool factory · web search · n8n · agent loop · brace-match parser · 10 unit tests

BLOCK 6

Skills

Folder pipeline · skill.json manifest · Morning Brief · Research

BLOCK 7

Trailhead

Eagle persona · doc context injection · RAG · PATHFINDER_GUIDE.md

BLOCK 8

RAG

knowledge_chunks · BM25 · auto-index docs/ on startup · document_search tool

BLOCK 9

Installer

First-run wizard · env scan · tier auto-detect · NSIS installer · 9b Credentials

BLOCK 10

Android

Tauri Android target · Samsung Galaxy Tab sideload APK

BLOCK 11

Dev Readiness

Architecture docs · gateway walkthrough · GitHub Actions CI · mock LLM mode

BLOCK 12

Community

Blockchain ledger · contribution approval · CLA · public launch