Initial ForgeLM import

docs/app/overview.md

@@ -0,0 +1,114 @@
+# 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`.