Arquitetura técnica

Limites das camadas

[ Flowral Control Center (Slint) ]   [ Flowral Theme Manager (Slint) ]
               |                                      |
           system-api                             theme-engine
               |                                      |
 NetworkManager / BlueZ / TLP       Swirl / WezTerm / Fish / Neovim / GTK / Qt
               |
         D-Bus / polkit helper                  [ Flowral Agents (Slint) ]
                                                       |
                                      agent-client (ACP / OpenCode API)
                                                       |
                                      providers / MCP manager / keyring

[ Swirl compositor ] -- Wayland + IPC --> [ Shell: panel, launcher, overlays ]
           |
     seatd + turnstile + runit
           |
       Void glibc + kernel

Estrutura futura do workspace

crates/
  flowral-config/         # schemas, migrações, XDG paths, leitura/escrita atômica
  flowral-theme/          # tokens, tema efetivo e adapters
  flowral-system/         # status e ações não privilegiadas / DBus
  flowral-privileged/     # servidor pequeno, ações explicitamente allowlisted
  flowral-mcp/            # registry, validação, lifecycle/escopos
  flowral-providers/      # profiles de endpoints/modelos sem segredos
  flowral-acp/            # sessões, streaming, permissões, processos
  flowral-ui/             # componentes Slint reutilizáveis
apps/
  flowral-themes/         # aplicar/visualizar/restaurar seis temas
  flowral-control/        # settings por módulos
  flowral-agents/         # interface de chat/agents, chamada sob demanda
  flowral-apps/           # gestão XBPS/Flatpak/AppImage (posterior)
shell/
  flowral-panel/          # duas ilhas inferiores
  flowral-launcher/       # busca + ações, spike Layer Shell
  flowral-overlays/       # volume, mídia e lockscreen próprios (posterior)
themes/                   # paletas, wallpapers autorizados, adapters
distro/                   # imagens, init, sessão e Calamares
packages/                 # recipes XBPS locais/reproduzíveis
tests/                    # smoke tests, UI/perf/segurança e hardware

Ciclo de vida

runit inicia apenas serviços de sistema estritamente necessários.
greetd (proposto) autentica; turnstile cria runtime/session; seatd concede seat.
Swirl inicia; shell mínimo (panel/notifications, sem control center aberto) roda.
Flowral Control abre sob demanda, lê estado D-Bus e escreve configurações via APIs.
Motor de temas aplica mudança com validação, snapshots e rollback.
Agentes ACP/MCP/providers são subprocessos ou conexões sob demanda; parada limpa ao terminar sessões.

APIs e componentes

Componente	Interface de controle	Cuidados
Swirl	IPC Sway compatível, config	suporte exato por versão, verificar comandos
Wi-Fi	NetworkManager D-Bus	não reimplementar armazenamento de senhas
Bluetooth	BlueZ D-Bus	pareamento, trust, cancelamento e erros
Áudio	PipeWire + WirePlumber	preferir APIs; fallback `wpctl` encapsulado
Monitores	wlroots output management se suportado	proteger saída ativa e oferecer rollback
Energia	UPower/TLP/acpid	nunca ativar perfis concorrentes cegamente
Pacotes	XBPS/Flatpak/AppImage	transações, diff, confirmação e polkit
OpenCode V2	ACP ou API oficial	compatibilidade de capabilities por handshake
MCP	configuração cliente-específica	escopos, comandos autorizados, secrets

Regras de projeto Rust

Cada crate tem responsabilidade única, tipos explícitos e API pública enxuta.
Separar lógica de negócios de Slint; testes de adapters não exigem abrir UI.
Erros tipados e mensagens amigáveis; não silenciar falhas de subprocessos.
Configurações versionadas e migráveis; escrita atômica (arquivo temporário + rename), snapshot anterior.
Sem singletons globais de estado mutável; módulos sob demanda.
Logs estruturados com redução de dados pessoais e segredos; versão/config sem credenciais.
Evitar abreviações obscuras em nomes de funções e variáveis; documentação de funções públicas.
Avaliar custo de dependências no binário e memória residente antes de incluir crates.
Não depender de systemd; testar explicitamente Void/runit.

Testes por camada

Unitários para parse/schemas; integração com serviços simulados D-Bus; teste de contrato para OpenCode V2 e adapters; smoke em QEMU; validação física no E430. Detalhes: performance e segurança.

Ambiente de desenvolvimento em camadas

A stack de desenvolvimento não é empacotada inteira na ISO. Rust/Cargo + Slint Viewer/Live Preview + servidor Slint MCP (somente debug) oferecem feedback rápido; just padroniza tarefas, bacon observa checks e sccache armazena builds. Sessão Swirl aninhada é condicional ao suporte do fork; QEMU/KVM + libvirt + SSH dão um guest Void real; ThinkPad Edge E430 valida GPU/energia/performance. Ver toolchain e Live Preview.

Os agentes nunca devem confundir hot reload visual com build completo: UI isolada → testes MCP → desktop nested → VM → hardware. Capturas de tela e relatórios são evidência, não promessas de funcionamento.

Superfícies do futuro Flowral DE

Flowral DE reutilizará compositor e serviços existentes; a parte própria será frontend de apresentação. Apps normais: Slint/Rust. Panel, launcher, OSD, toasts e overlays precisam de Layer Shell comprovado no Swirl, com integração Slint a testar. Autenticação: greetd/PAM e lock seguro upstream, frontend personalizado apenas após testes especializados. Não reimplementar NetworkManager, BlueZ, PipeWire, polkit backend nem xdg-desktop-portal por estética.