# Design do Aplicativo de Transcrição Desktop

## Objetivo

Construir um aplicativo desktop de transcrição para Windows e Linux, com foco inicial em operação offline. O usuário inicia e encerra gravações por hotkey global, revisa a transcrição em um modal flutuante editável e confirma a inserção no aplicativo de destino. O app deve permanecer residente na bandeja/barra do sistema e ser organizado para manutenção simples, builds automatizados e evolução incremental.

## Requisitos aprovados

- Plataforma: Windows e Linux.
- Base técnica: Tauri + Rust com frontend web mínimo em TypeScript.
- Linux: suporte completo no X11 quando possível; suporte parcial e honesto no Wayland.
- Transcrição: offline-first.
- Modelo principal: `cstr/parakeet-tdt-0.6b-v3-GGUF`, arquivo `parakeet-tdt-0.6b-v3-q8_0.gguf`.
- Runtime local: CrispASR como sidecar.
- UX de revisão: sempre exibir modal editável antes de inserir texto.
- Inserção: padrão por clipboard + colar, com modo manual/fallback.
- App residente: tray/system tray com ações principais.
- CI/CD: preparado para GitHub Actions, com comandos portáveis para adaptação futura ao GitLab CI.

## Arquitetura

O projeto usa uma arquitetura modular simples. O frontend Tauri renderiza o modal, configurações e estado visível. O backend Rust expõe comandos Tauri pequenos e delega cada responsabilidade a módulos focados.

```text
src/                  Frontend TypeScript/CSS
src-tauri/src/
  audio/              Estado e gravação simulada/MVP
  transcription/      Contrato comum, CrispASR sidecar e API OpenAI-compatible
  injection/          Estratégias de inserção/cópia de texto
  models/             Catálogo, status e metadados de modelos offline
  settings/           Configuração local serializável
  tray.rs             Ícone da bandeja e menu
  ui_commands.rs      Comandos Tauri expostos ao frontend
  app_state.rs        Estado compartilhado mínimo
  lib.rs              Bootstrap Tauri
  main.rs             Entrada nativa
```

A implementação inicial entrega um esqueleto funcional e testável. Integrações que dependem de APIs nativas frágeis, como hotkey global e injeção real em Wayland, ficam isoladas por contratos para serem implementadas em fatias futuras sem reestruturar o app.

## Modal flutuante

O modal é a interface principal após cada gravação. Ele sempre abre antes de qualquer inserção no aplicativo de destino.

Componentes:

- Cabeçalho com estado atual: pronto, gravando, transcrevendo ou revisando.
- Metadados: backend, modelo e idioma.
- Área editável para texto transcrito.
- Ações: iniciar/parar gravação, continuar, copiar, inserir, salvar.
- Mensagens de erro e fallback.

Fluxo principal:

```text
Pronto -> Gravando -> Transcrevendo -> Revisando -> Inserido/Copiado/Salvo
```

## Inserção de texto

A inserção padrão será `ClipboardPaste`: salvar clipboard atual, copiar transcrição, enviar colar quando o sistema suportar e restaurar clipboard depois de um atraso seguro. No MVP, a implementação real de colar é representada por contrato e fallback manual; o texto é copiado para o clipboard pelo frontend quando o usuário pressiona copiar.

Política por sistema:

- Windows: usar Win32 APIs em implementação futura (`GetForegroundWindow`, `SetForegroundWindow`, `SendInput`).
- Linux X11: usar X11 ou fallback com ferramenta opcional detectada.
- Linux Wayland: tratar como parcial; se automação for bloqueada, copiar texto e orientar Ctrl+V.

## Modelos offline

O gerenciador de modelos começa com catálogo estático e validação por metadados.

Modelo principal:

- ID: `parakeet-tdt-0.6b-v3-q8_0`
- Repositório: `cstr/parakeet-tdt-0.6b-v3-GGUF`
- Arquivo: `parakeet-tdt-0.6b-v3-q8_0.gguf`
- Tamanho aproximado: 711 MiB / 745,121,600 bytes conforme metadados do repositório.
- Idiomas: modelo base Parakeet v3 com detecção automática e suporte a 25 idiomas europeus, incluindo português.

O app não embute o modelo no instalador principal. O instalador fica leve; o modelo é baixado pelo app ou instalado manualmente em diretório local configurado.

## Transcrição local com CrispASR

CrispASR será executado como sidecar empacotado por Tauri. O contrato de transcrição aceita caminho de áudio e opções, e retorna texto, idioma detectado opcional, backend, modelo e duração.

No MVP, se o sidecar ou o modelo ainda não estiver configurado, o backend retorna mensagem clara de erro/pendência para o modal. Isso permite validar UI, settings e pipeline sem depender imediatamente do binário externo.

## API OpenAI-compatible

A integração com API externa fica em adaptador separado. Campos previstos:

- endpoint base;
- API key;
- modelo;
- idioma opcional;
- timeout.

Esse adaptador não é o padrão inicial. Ele existe para manter a arquitetura pronta para fallback online sem contaminar o fluxo offline.

## CI/CD

Workflows previstos:

- `ci.yml`: lint, typecheck, testes Rust, testes frontend e build web.
- `build.yml`: build desktop por matriz Windows/Linux.
- `release.yml`: publicação automática em GitHub Releases por tag `v*.*.*`.

A lógica principal fica em scripts npm/cargo para facilitar migração para GitLab CI.

## Escopo do MVP implementado nesta primeira fatia

- Estrutura de projeto Tauri + Rust + TypeScript.
- Módulos backend com contratos e testes unitários.
- Catálogo do modelo Parakeet GGUF Q8.
- Configuração local padrão.
- Modal funcional no frontend com revisão, cópia e simulação de fluxo.
- Tray com menu básico.
- Workflows de CI/build/release.
- Documentação de desenvolvimento e arquitetura.

## Fora do escopo imediato

- Captura real de áudio por dispositivo.
- Hotkey global real.
- Execução real do CrispASR em todos os SOs.
- Injeção real em aplicativos externos.
- Download real com barra de progresso.

Essas partes ficam isoladas em módulos para serem implementadas sem alterar a arquitetura principal.