# Aplicativo de Transcrição Desktop MVP Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Criar o esqueleto funcional de um app desktop Windows/Linux de transcrição offline-first com Tauri, Rust, TypeScript, modal editável, catálogo de modelo Parakeet GGUF Q8, sidecar CrispASR preparado e CI/CD.

**Architecture:** O frontend TypeScript renderiza a tela/modal e chama comandos Tauri. O backend Rust mantém módulos pequenos para settings, modelos, transcrição, injeção, áudio e tray. Integrações nativas arriscadas ficam atrás de contratos e stubs explícitos para evoluir sem quebrar a arquitetura.

**Tech Stack:** Tauri 2, Rust 1.95, TypeScript, Vite, Vitest, GitHub Actions.

---

## File Structure

```text
.github/workflows/ci.yml             CI de lint/typecheck/test/build
.github/workflows/build.yml          Builds desktop Windows/Linux manuais
.github/workflows/release.yml        Release por tag v*.*.*
.gitignore                           Ignora builds, deps, modelos e segredos
README.md                            Visão geral, comandos e limitações
package.json                         Scripts frontend/Tauri
index.html                           Entrada Vite
src/main.ts                          Estado e eventos da UI
src/styles.css                       Modal/responsividade/acessibilidade
src/vite-env.d.ts                    Tipos Vite/Tauri
src-tauri/Cargo.toml                 Crates Rust/Tauri
src-tauri/build.rs                   Build script Tauri
src-tauri/tauri.conf.json            Configuração Tauri e bundle
src-tauri/capabilities/default.json  Permissões Tauri
src-tauri/icons/icon.png             Ícone mínimo temporário
src-tauri/src/main.rs                Entrada nativa
src-tauri/src/lib.rs                 Bootstrap Tauri
src-tauri/src/app_state.rs           Estado compartilhado
src-tauri/src/ui_commands.rs         Comandos Tauri
src-tauri/src/tray.rs                Tray/menu
src-tauri/src/settings/mod.rs        Settings e defaults
src-tauri/src/models/mod.rs          Catálogo/status de modelos
src-tauri/src/transcription/mod.rs   Contratos de transcrição
src-tauri/src/transcription/crispasr.rs Sidecar CrispASR preparado
src-tauri/src/transcription/openai.rs Adaptador OpenAI-compatible preparado
src-tauri/src/injection/mod.rs       Contratos/fallback de inserção
src-tauri/src/audio/mod.rs           Estado de gravação MVP
src-tauri/src/error.rs               Erros serializáveis
```

## Task 1: Scaffolding do projeto

**Files:**
- Create: `.gitignore`
- Create: `package.json`
- Create: `index.html`
- Create: `src/vite-env.d.ts`
- Create: `src-tauri/Cargo.toml`
- Create: `src-tauri/build.rs`
- Create: `src-tauri/tauri.conf.json`
- Create: `src-tauri/capabilities/default.json`
- Create: `src-tauri/src/main.rs`
- Create: `src-tauri/src/lib.rs`

- [ ] **Step 1: Criar configuração base do frontend e Tauri**

Criar arquivos com scripts `dev`, `build`, `test`, `typecheck`, `tauri:dev` e `tauri:build`. Usar Tauri 2 e Vite.

- [ ] **Step 2: Instalar dependências npm**

Run: `npm install`

Expected: `package-lock.json` criado e dependências instaladas.

- [ ] **Step 3: Verificar build frontend vazio**

Run: `npm run typecheck && npm run build`

Expected: TypeScript e Vite passam.

## Task 2: Contratos backend e testes Rust

**Files:**
- Create: `src-tauri/src/error.rs`
- Create: `src-tauri/src/settings/mod.rs`
- Create: `src-tauri/src/models/mod.rs`
- Create: `src-tauri/src/transcription/mod.rs`
- Create: `src-tauri/src/transcription/crispasr.rs`
- Create: `src-tauri/src/transcription/openai.rs`
- Create: `src-tauri/src/injection/mod.rs`
- Create: `src-tauri/src/audio/mod.rs`
- Modify: `src-tauri/src/lib.rs`

- [ ] **Step 1: Escrever tipos e testes unitários primeiro**

Testes devem cobrir:
- modelo Parakeet Q8 existe no catálogo;
- idioma manual é opcional por padrão;
- Wayland retorna inserção parcial/manual;
- CrispASR sem modelo configurado retorna erro claro.

- [ ] **Step 2: Rodar testes para validar contratos**

Run: `cargo test --manifest-path src-tauri/Cargo.toml`

Expected: todos os testes passam após implementação mínima.

## Task 3: Comandos Tauri e estado do app

**Files:**
- Create: `src-tauri/src/app_state.rs`
- Create: `src-tauri/src/ui_commands.rs`
- Modify: `src-tauri/src/lib.rs`

- [ ] **Step 1: Expor comandos pequenos para frontend**

Comandos:
- `get_app_snapshot`
- `start_recording`
- `stop_recording_and_transcribe`
- `copy_ready_text`
- `request_insert_text`
- `list_models`
- `get_settings`
- `save_settings`

- [ ] **Step 2: Testar build Rust**

Run: `cargo test --manifest-path src-tauri/Cargo.toml`

Expected: comandos compilam e testes continuam passando.

## Task 4: UI do modal flutuante

**Files:**
- Create: `src/main.ts`
- Create: `src/styles.css`
- Modify: `index.html`

- [ ] **Step 1: Construir UI sem framework pesado**

Criar interface com:
- status;
- textarea editável;
- botões gravar/parar, continuar, copiar, inserir e salvar;
- painel de modelo/configuração resumida;
- mensagens de fallback.

- [ ] **Step 2: Testar frontend**

Run: `npm run typecheck && npm run test -- --run && npm run build`

Expected: typecheck, Vitest e build passam.

## Task 5: Tray, assets e empacotamento

**Files:**
- Create: `src-tauri/src/tray.rs`
- Create: `src-tauri/icons/icon.png`
- Modify: `src-tauri/src/lib.rs`
- Modify: `src-tauri/tauri.conf.json`

- [ ] **Step 1: Adicionar tray básico**

Menu:
- Mostrar app;
- Iniciar gravação;
- Sair.

- [ ] **Step 2: Verificar build Tauri até onde o ambiente permitir**

Run: `npm run tauri:build`

Expected: se dependências do sistema estiverem instaladas, build gera bundle; se faltar WebView/NSIS/AppImage tooling, documentar o bloqueio e manter `cargo test` + `npm run build` verdes.

## Task 6: CI/CD e documentação

**Files:**
- Create: `.github/workflows/ci.yml`
- Create: `.github/workflows/build.yml`
- Create: `.github/workflows/release.yml`
- Create: `README.md`

- [ ] **Step 1: Criar workflows**

CI roda em PR/push para `main`. Build é manual. Release roda em tags `v*.*.*` e publica artefatos.

- [ ] **Step 2: Documentar arquitetura e limitações**

README deve explicar:
- offline-first;
- modelo Parakeet GGUF Q8;
- CrispASR sidecar;
- suporte Windows/Linux;
- Wayland parcial;
- comandos locais.

- [ ] **Step 3: Verificação final**

Run:
- `npm run typecheck`
- `npm run test -- --run`
- `npm run build`
- `cargo test --manifest-path src-tauri/Cargo.toml`

Expected: todos passam.

## Self-review

- Spec coverage: cobre organização, modal, inserção, modelo offline, CrispASR sidecar e CI/CD.
- Placeholder scan: não há etapas com TBD/TODO; integrações fora do MVP estão explicitamente isoladas.
- Type consistency: comandos e módulos nomeados de forma consistente com a estrutura proposta.