ForgeLM/docs/app/overview.md

Visao geral do app desktop

O app desktop do ForgeLM vive em tauri-app/ e combina:

• frontend React/Vite
• backend Tauri em Rust
• runtime manager para API local/remota
• chat persistente com banco local em memoria exportado para localStorage

Funcao do app

O app foi desenhado para ser a interface principal de uso do runtime local. Ele permite:

• iniciar ou parar a API local quando o modo e local
• apontar para uma API existente quando o modo e remote
• escolher/importar modelos .gguf
• conversar com o backend via POST /v1/chat/completions
• persistir historico de chats e mensagens
• separar trechos de reasoning (<think>...</think>) da resposta final no frontend

Arquitetura em alto nivel

Frontend

Arquivos principais:

• src/App.tsx - shell principal do app
• src/components/Sidebar.tsx - sidebar com runtime card, seletor de modelo e lista de chats
• src/components/ChatView.tsx - fluxo de chat, streaming, memoria e persistencia de mensagens
• src/features/runtime/* - runtime manager unificado

Backend Tauri

Arquivos principais:

• src-tauri/src/lib.rs - comandos Tauri expostos ao frontend
• src-tauri/src/runtime/* - estado, config, spawn, health probe e snapshot do runtime local

Runtime manager

O runtime manager e a peca central do app.

Estados principais:

• stopped
• starting
• ready
• degraded
• stopping
• error

Modos de conexao:

• local - o app controla o processo do backend
• remote - o app so consome uma API externa ja existente

O frontend usa useRuntimeManager() como source of truth para:

• snapshot atual do runtime
• URL resolvida da API
• save de config
• start/stop do runtime local

Selecao de modelos

O app carrega modelos via GET /v1/models usando useModels().

Comportamentos importantes:

• se nao houver endpoint configurado, o estado fica em erro e a lista e limpa
• se a API responder sem modelos, o model selector fica vazio
• se o modelo antes selecionado nao existir mais na lista, o app seleciona o primeiro disponivel

Persistencia local

O chat usa sql.js com schema local gerenciado por src/lib/db.ts.

Tabelas principais:

• chats
• messages

Campos persistidos por mensagem incluem:

• role
• content
• reasoning_content
• prompt_tokens
• completion_tokens
• total_tokens
• tokens_per_second

Importante: isso nao e um banco nativo do sistema operacional. O app injeta sql.js por CDN e persiste a exportacao do banco em localStorage.

Chat e streaming

ChatView.tsx envia requests para POST /v1/chat/completions.

Recursos atuais:

• streaming opcional
• memoria opcional com ate 20 mensagens recentes
• separacao visual de reasoning (<think>...</think>) no frontend
• contadores de tokens por mensagem e por chat
• edicao, reenvio e exclusao de mensagens

Limitacoes atuais

• o app depende de um binario localllm acessivel quando o modo local e usado
• o fallback browser-only nao substitui os recursos desktop do Tauri
• o chat depende da pequena API HTTP atual; o app nao expoe magica propria fora dela
• o runtime manager faz polling periodico do snapshot; ele nao usa ainda um fluxo completo de eventos push

Para uso pratico, siga para user-guide.md.