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