feat: integrate desktop runtime and root workspace updates

README.MD

@@ -1,243 +1,98 @@
 # ForgeLM
 
-High-performance local inference runtime for small and mid-sized language models, designed for efficient execution on commodity hardware.
+ForgeLM e um workspace Rust para inferencia local de LLMs com tres superficies principais:
 
-## Overview
+- uma API HTTP local compativel com partes da API de chat da OpenAI
+- uma CLI (`localllm`) para operacao, diagnostico e automacao
+- um app desktop Tauri para runtime management e chat persistente
 
-ForgeLM is a local-first inference runtime built for developers who need a clean, controllable, and efficient backend for running quantized language models on consumer GPUs and constrained systems.
+O projeto hoje e organizado para rodar localmente, com foco em modelos `.gguf`, operacao local-first e uma ponte entre backend Rust, CLI e interface desktop.
 
-The project is centered on a practical engineering goal: extracting high throughput and low latency from compact and mid-sized models without turning the runtime into an opaque monolith or an overextended product shell.
+## O que existe hoje
 
-The initial focus is on text-only inference for models in the range of Qwen 4B / 9B class deployments, with special attention to NVIDIA GPUs such as the RTX 3070 and to fallback paths for weaker hardware.
+- `crates/inference-server`: servidor HTTP com `GET /health`, `GET /v1/models` e `POST /v1/chat/completions`
+- `crates/localllm-cli`: CLI para status, modelos, auth, config, benchmark, logs e doctor
+- `tauri-app`: app desktop com runtime manager, chat UI, armazenamento local e integracao com o backend
+- `crates/api-contracts`: contratos de request/response compartilhados
+- `crates/inference-core`: engine, perfis de runtime e pipeline de inferencia
 
-ForgeLM is not intended to be a desktop UI product. It is intended to be a modular inference backend that can be embedded, extended, benchmarked, and reasoned about as infrastructure.
+## Inicio rapido
 
----
+### 1. Subir a API local
 
-## Design Goals
+Defina pelo menos o caminho do modelo e execute o servidor:
 
-ForgeLM is built around a small number of non-negotiable goals:
+```bash
+set LOCALLLM_MODEL=D:\caminho\modelo.gguf
+cargo run -p inference-server
+```
 
-- **High throughput**
-  - Prioritize sustained token generation performance for small and mid-sized models.
+Validacoes basicas:
 
-- **Low latency**
-  - Minimize time-to-first-token and reduce generation overhead in the hot path.
+```bash
+curl http://127.0.0.1:8080/health
+curl http://127.0.0.1:8080/v1/models
+```
 
-- **Efficient memory usage**
-  - Make disciplined use of VRAM and RAM through careful model loading, batching strategy, and KV-cache policies.
+### 2. Usar a CLI
 
-- **Predictable architecture**
-  - Keep the inference path understandable, inspectable, and modular.
+```bash
+cargo run -p localllm-cli -- status
+cargo run -p localllm-cli -- models list
+```
 
-- **Hardware realism**
-  - Optimize for hardware that developers actually own, including 8 GB consumer GPUs and CPU fallback scenarios.
+### 3. Abrir o app desktop
 
-- **Separation of concerns**
-  - Keep the inference core, API layer, model registry, and tooling clearly separated.
+```bash
+cd tauri-app
+npm install
+npm run tauri dev
+```
 
-- **Open integration surface**
-  - Provide a clean local API compatible with common inference client patterns.
+No app, abra o Runtime Manager, configure modo local ou remoto e depois use o chat.
 
----
+## Requisitos
 
-## Project Scope
+- Rust toolchain atual para o workspace
+- Node.js/NPM para o app Tauri
+- um modelo `.gguf` local para o runtime
+- GPU NVIDIA e opcional; o projeto tambem possui perfil CPU fallback
 
-ForgeLM focuses on the runtime layer of local language model serving.
+## Estrutura do repositorio
 
-### In scope
+- `crates/api-contracts/` - contratos HTTP e tipos compartilhados
+- `crates/inference-core/` - engine, sessoes, sampler e perfis de runtime
+- `crates/inference-server/` - servidor HTTP local
+- `crates/localllm-cli/` - CLI de operacao
+- `crates/metrics/` - contadores e medicao de throughput
+- `crates/llama-sys/` - bindings/integracao de baixo nivel
+- `tauri-app/` - app desktop Tauri + frontend React
+- `docs/` - documentacao detalhada
 
-- Local text inference
-- GGUF-based model execution
-- High-performance inference backends
-- OpenAI-compatible HTTP API
-- Streaming responses via SSE
-- Runtime tuning for throughput and memory efficiency
-- Model registry and download workflow
-- Benchmarking and observability
+## Documentacao
 
-### Out of scope for the initial versions
+- `docs/README.md` - indice da documentacao
+- `docs/api/overview.md` - visao geral do backend e da API
+- `docs/api/endpoints.md` - referencia HTTP
+- `docs/api/configuration.md` - variaveis de ambiente e configuracao do servidor
+- `docs/cli/overview.md` - visao geral da CLI
+- `docs/cli/commands.md` - referencia de comandos e exemplos
+- `docs/app/overview.md` - visao geral do app desktop
+- `docs/app/user-guide.md` - guia de uso do app
+- `docs/app/backend-commands.md` - comandos Tauri expostos pelo backend do app
+- `docs/developer/architecture.md` - arquitetura do workspace e fluxos entre modulos
 
-- Full desktop product UX
-- Multimodal inference
-- Enterprise orchestration features
-- Training and fine-tuning workflows
-- Plugin-heavy product abstractions
-- Broad feature surface at the expense of runtime efficiency
+## Estado atual e limitacoes
 
----
+- A API atual expoe apenas tres endpoints publicos: `GET /health`, `GET /v1/models` e `POST /v1/chat/completions`.
+- A compatibilidade com OpenAI e parcial: o projeto foca no fluxo de chat, nao em toda a superficie da plataforma.
+- A CLI possui uma superficie ampla, mas a execucao ao vivo hoje esta mais consolidada em `status`, `models list` e `bench throughput`.
+- O app desktop controla o runtime local no modo `local` e pode consumir uma API ja existente no modo `remote`.
+- O armazenamento do chat no frontend usa `sql.js` carregado por CDN e persistencia em `localStorage`.
 
-## Core Principles
+## Leitura recomendada
 
-### 1. The hot path must remain small
-
-The token generation path is where performance is won or lost. ForgeLM keeps this path narrow:
-
-- model execution in a native backend
-- Rust in the serving and orchestration layer
-- no Python in the inference hot path
-- controlled allocation and bounded runtime overhead
-
-### 2. Performance comes before feature breadth
-
-A runtime that supports everything but performs poorly is not useful for the target use case. ForgeLM deliberately starts with a constrained feature set in order to produce measurable runtime efficiency first.
-
-### 3. Public architecture should remain understandable
-
-The repository is intended to be inspectable by engineers. The design should be explainable without product-language shortcuts, hidden runtime behavior, or unnecessary framework complexity.
-
-### 4. Consumer hardware is a first-class target
-
-Many local inference projects are evaluated on unrealistic hardware assumptions. ForgeLM explicitly targets practical systems, including 8 GB GPUs and weaker fallback environments.
-
----
-
-## Technical Direction
-
-ForgeLM is structured as a layered system.
-
-### Inference Core
-
-The inference core is built around a native execution backend for quantized GGUF models. The initial backend strategy is centered on `llama.cpp`-class execution, selected for its strong hardware coverage, mature quantized model support, and practical performance characteristics.
-
-Responsibilities:
-
-- model loading
-- tokenizer access
-- context management
-- decode loop execution
-- GPU offloading control
-- sampling configuration
-- KV-cache handling
-
-### Serving Layer
-
-The HTTP serving layer is implemented in Rust and is responsible for:
-
-- request validation
-- session orchestration
-- streaming token delivery
-- concurrency control
-- backpressure
-- metrics and health endpoints
-
-This layer exists to expose the runtime cleanly without polluting the core execution path.
-
-### Model Registry
-
-Model search, metadata resolution, and download management are intentionally isolated from the hot path. Registry operations may use a separate process and different tooling, but they do not participate in token generation.
-
-Responsibilities:
-
-- model discovery
-- metadata normalization
-- artifact download
-- integrity verification
-- local registry indexing
-
-### Tooling and Benchmarks
-
-Performance claims without reproducible measurement are not useful. Benchmarking and observability are part of the project rather than afterthoughts.
-
-Responsibilities:
-
-- throughput measurement
-- latency measurement
-- memory usage tracking
-- benchmark replay
-- runtime profiling
-
----
-
-## Initial Optimization Target
-
-The first optimization target is the practical deployment envelope of small and mid-sized text models on commodity NVIDIA hardware.
-
-That means prioritizing:
-
-- compact and mid-sized Qwen-class models
-- strong throughput on RTX 3070-class systems
-- viable degraded execution on weaker hardware
-- text-only serving before broader capability expansion
-
-In practical terms, the project is designed to explore the trade space between:
-
-- model size
-- quantization level
-- context length
-- GPU offloading depth
-- batching strategy
-- latency
-- aggregate throughput
-- output quality
-
----
-
-## Architectural Priorities
-
-The implementation roadmap is shaped by the following priorities:
-
-### Text-only first
-
-Text inference is the fastest path to a stable and high-performance serving core. Additional modalities, if ever added, must not distort the original runtime goals.
-
-### Single-model efficiency before multi-model orchestration
-
-Before adding model multiplexing or dynamic model switching, the runtime must demonstrate excellent single-model performance and stable serving behavior.
-
-### Controlled concurrency before maximum concurrency
-
-Concurrency is useful only when it improves real system throughput without collapsing latency or wasting memory. The project favors disciplined scheduling over superficial parallelism.
-
-### Measured optimization over speculative abstraction
-
-Every substantial optimization should be benchmarked. Every abstraction in the serving path should justify its cost.
-
----
-
-## Proposed Stack
-
-The current technical direction is:
-
-### Native backend
-- C/C++
-- `llama.cpp`-class runtime backend
-- CUDA path for NVIDIA acceleration
-
-### Serving layer
-- Rust
-- Tokio
-- Axum
-- Hyper
-- FFI bindings generated with `bindgen`
-
-### Registry and model management
-- Python
-- isolated background process or service
-- Hugging Face integration for model discovery and retrieval
-
-### UI
-- minimal local web interface for runtime validation
-- not a product-grade desktop shell
-
----
-
-## Repository Structure
-
-```text
-forgelm/
-├── Cargo.toml
-├── crates/
-│   ├── backend-sys/
-│   ├── inference-core/
-│   ├── inference-server/
-│   ├── api-contracts/
-│   └── metrics/
-├── registry/
-│   ├── service.py
-│   └── requirements.txt
-├── ui/
-│   └── index.html
-├── vendor/
-│   └── backend/
-└── models/
+- Quer entender a API? Comece em `docs/api/overview.md`.
+- Quer operar o sistema por terminal? Va para `docs/cli/overview.md`.
+- Quer usar o app desktop? Leia `docs/app/user-guide.md`.
+- Quer contribuir no codigo? Comece em `docs/developer/architecture.md`.