feat: integrate desktop runtime and root workspace updates

2026-03-27 03:17:16 -03:00
1 parent f5a4a9ee97
commit 168623c459
@@ -0,0 +1,140 @@
+# Arquitetura do projeto
+
+Esta pagina resume a arquitetura atual do workspace ForgeLM para quem vai manter ou evoluir o sistema.
+
+## Mapa do workspace Rust
+
+O `Cargo.toml` raiz declara os membros:
+
+- `crates/llama-sys`
+- `crates/inference-core`
+- `crates/inference-server`
+- `crates/api-contracts`
+- `crates/metrics`
+- `crates/localllm-cli`
+
+O app desktop fica fora do workspace Rust principal, em `tauri-app/`, mas conversa diretamente com esse ecossistema por binario, comandos Tauri e HTTP local.
+
+## Responsabilidade de cada modulo
+
+### `api-contracts`
+
+Tipos compartilhados para:
+
+- chat completions
+- model listing
+- health
+- payloads de erro
+
+Serve como contrato comum entre `inference-server` e consumidores da API.
+
+### `inference-core`
+
+Responsavel pela engine de inferencia local:
+
+- carga do modelo
+- sessao de inferencia
+- sampler
+- perfis de runtime
+
+### `inference-server`
+
+Camada HTTP baseada em Axum:
+
+- leitura de env vars
+- montagem de `ServerConfig`
+- auth, CORS e aliases de modelos
+- endpoints `/health`, `/v1/models`, `/v1/chat/completions`
+
+### `localllm-cli`
+
+CLI de operacao e automacao. Hoje ela ja tem uma superficie ampla, mas a parte com execucao real comprovada contra o backend publico atual esta mais concentrada em `status`, `models list` e `bench throughput`.
+
+### `metrics`
+
+Contadores e registros de throughput/token usage usados no backend.
+
+### `llama-sys`
+
+Bindings e integracao de baixo nivel com a stack de inferencia.
+
+### `tauri-app`
+
+App desktop composto por:
+
+- frontend React/Vite
+- backend Tauri em Rust
+- runtime manager local/remoto
+- chat persistente com `sql.js`
+
+## Fluxo entre API, CLI e app
+
+## 1. Backend HTTP
+
+`inference-server` sobe, carrega o modelo e expoe a API HTTP.
+
+## 2. CLI
+
+A CLI pode falar com a API HTTP por URL configurada via `--server` e `--api-key`.
+
+## 3. App desktop
+
+O app usa duas camadas:
+
+- backend Tauri para gerenciar processo, configuracao e integracoes locais
+- frontend React para runtime manager, selecao de modelos e chat
+
+Quando em modo local, o app inicia/para o backend por meio do runtime manager do Tauri. Quando em modo remoto, o app apenas consome uma URL externa.
+
+## Runtime manager do app
+
+Arquivos centrais:
+
+- `tauri-app/src/features/runtime/useRuntimeManager.ts`
+- `tauri-app/src/features/runtime/types.ts`
+- `tauri-app/src/features/runtime/components/RuntimeStatusCard.tsx`
+- `tauri-app/src/features/runtime/components/RuntimeSettingsDrawer.tsx`
+- `tauri-app/src-tauri/src/runtime/*`
+
+Conceitos importantes:
+
+- `RuntimeConfig` e persistido no backend Tauri
+- `RuntimeSnapshot` e consumido pelo frontend
+- modo `local` e `remote` compartilham a mesma superficie de configuracao
+- readiness do modo local depende de `GET /health`
+
+## Chat e persistencia
+
+Arquivos centrais:
+
+- `tauri-app/src/components/ChatView.tsx`
+- `tauri-app/src/components/MessageBubble.tsx`
+- `tauri-app/src/lib/db.ts`
+- `tauri-app/src/lib/chat.ts`
+
+Caracteristicas importantes:
+
+- conversas e mensagens ficam em `sql.js` persistido em `localStorage`
+- o app separa reasoning de resposta final ao analisar `<think>...</think>`
+- tokens por mensagem e por chat ficam persistidos
+- memoria do chat envia ate 20 mensagens recentes quando habilitada
+
+## Limites e fronteiras atuais
+
+- a API publica ainda e pequena; nao documente ou desenvolva assumindo uma plataforma completa estilo OpenAI
+- a CLI esta mais avancada no parser/superficie do que nas capacidades HTTP publicas realmente disponiveis
+- o app desktop e a interface mais rica do projeto hoje, mas ainda depende do backend HTTP local/remoto para inferencia real
+
+## Termos recomendados
+
+- `runtime` - processo + configuracao + estado operacional do backend local
+- `API local` - o `inference-server` rodando na maquina do usuario
+- `modo local` - o app controla o processo
+- `modo remoto` - o app consome uma API externa
+- `snapshot de runtime` - estado serializado do runtime usado pelo frontend
+
+## Leitura complementar
+
+- `../api/overview.md`
+- `../cli/overview.md`
+- `../app/overview.md`