# 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`.