# Documentação do Sistema Flash Card Navegador

## 1. Visão Geral do Sistema
O sistema Flash Card Navegador é uma aplicação web para estudo e prática de cartões de memória (flashcards), com funcionalidades de reconhecimento de voz (STT), síntese de voz (TTS), comparação inteligente de respostas (fuzzy match), múltiplos temas visuais e suporte a múltiplos idiomas.

## 2. Estrutura de Pastas e Arquivos
- **card_base.html, cards.html**: Interfaces principais do usuário.
- **package.json, server.js**: Configuração e backend (Node.js).
- **assets/whisper/**: Lógica de reconhecimento de voz (STT) e workers.
- **css/**: Estilos principais e temas visuais.
- **data/**: Arquivos de dados dos cartões (JS).
- **ui/**: Lógica de interface, controle, comandos, carregamento de dados, TTS/STT, etc.
- **views/**: Modais e componentes HTML auxiliares.

## 3. Principais Funcionalidades
- Exibição e navegação de cartões.
- Botão de microfone por cartão para STT e validação de pronúncia.
- Comparação inteligente de respostas (fuzzy match, normalização, etc.).
- Feedback visual e sonoro ao usuário.
- Suporte a múltiplos temas e idiomas.
- Autoplay e comandos de voz.

## 4. Fluxo de Inicialização e Eventos
- Ao carregar o HTML principal, os scripts JS são carregados.
- O evento `DOMContentLoaded` dispara a inicialização do app e o binding dos eventos de interface.
- Funções principais: `UI.init`, `UI.renderCards`, `window.bindUIEvents`, `importarDATA`.
- Cada botão de microfone ativa o STT, que transcreve, normaliza e compara a resposta, fornecendo feedback imediato.

## 5. Camadas e Responsabilidades
- **UI (ui/)**: Renderização, feedback, controle de interface.
- **Controller (controller.*.js)**: Lógica de eventos, fuzzy match, STT, TTS, comandos.
- **Assets/Whisper**: Engine de reconhecimento de voz.
- **Data**: Base de cartões.
- **CSS**: Temas e estilos.
- **Views**: Modais e componentes auxiliares.

## 6. Recomendações para Reestruturação
- Trabalhar em camadas bem definidas (UI, lógica, dados).
- Evitar modificar código estável; criar funções alternativas para novas features.
- Usar importação sob demanda para funções/módulos grandes.
- Documentar internamente cada função e fluxo.
- Utilizar versionamento (Git) para rastreabilidade.
- Planejar fluxogramas e arquitetura antes de grandes mudanças.

## 7. Modelo de Documentação Interna
Exemplo para funções JS:
```
/**
 * Nome da função: fuzzyMatch
 * Descrição: Compara duas strings usando lógica de similaridade para validar respostas do usuário.
 * Parâmetros:
 *   - expected: string esperada
 *   - actual: string fornecida pelo usuário
 * Retorno: boolean indicando se as strings são consideradas equivalentes
 */
function fuzzyMatch(expected, actual) { ... }
```

---

Este documento pode ser expandido conforme o sistema evoluir, incluindo fluxogramas, diagramas de arquitetura e detalhes de cada módulo/função.