ForgeLM/docs/developer/architecture.md

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