Spaces:
Sleeping
Download SPRINT_ROADMAP.md from jrrribeiro/BirdNET-Uploader-App: direct link, hf CLI and curl.
- Browser
- Download file 19.6 kB
-
https://huggingface.co/spaces/jrrribeiro/BirdNET-Uploader-App/resolve/main/SPRINT_ROADMAP.md
- Command line
-
hf download hf://spaces/jrrribeiro/BirdNET-Uploader-App/SPRINT_ROADMAP.md
-
curl -L -o SPRINT_ROADMAP.md https://huggingface.co/spaces/jrrribeiro/BirdNET-Uploader-App/resolve/main/SPRINT_ROADMAP.md
A newer version of the Gradio SDK is available: 6.32.0
BirdNET Uploader: Sprint Roadmap (MVP 6-8 semanas)
Overview
Objetivo: Entregar executável local moderno, um fluxo integrado, pausa/retomada, compatibilidade com validador.
Timeline:
- Semanas 1-2: Arquitetura + Setup (Foundation)
- Semanas 3-4: Módulos Core (Auth, Repo, Upload)
- Semanas 5-6: UI + Session Manager (Integration)
- Semanas 7-8: Build + Testes + Release (Polish)
Team: 2-3 engineers (1 backend, 1 frontend/UI, 1 QA/DevOps)
SPRINT 1: Foundation & Architecture (Semanas 1-2)
Semana 1: Setup Inicial + Design Review
Task 1.1: Setup do Projeto (2 dias, 3 pts)
Objetivo: Estrutura base, dependências, CI/CD
Tarefas:
- Criar branch
feature/birdnet-uploader-cli - Criar estrutura de diretórios (
src/,tests/,build/) - Setup
pyproject.tomlerequirements.txt- huggingface_hub>=0.28.0
- click>=8.0.0
- textual>=0.30.0 (TUI)
- rich>=13.0.0
- pydantic>=2.0.0
- pandas>=2.0.0
- pyarrow>=14.0.0
- keyring>=24.0.0
- Setup GitHub Actions para lint/test
- Criar
src/__init__.pyesrc/main.py(skeleton)
Critério de Pronto:
pip install -r requirements.txtsem erropython -m src.main --helproda e exibe help text
Task 1.2: Design Review + Arquitetura Finalizada (2 dias, 2 pts)
Objetivo: Alinhamento com stakeholders, decisões arquiteturais bloqueantes
Tarefas:
- Revisar documento REDESIGN com time
- Decisão final: Textual vs Rich+Click vs Typer (recomendação: Textual para melhor UX)
- Decidir sobre persistência: SQLite vs JSON files (recomendação: JSON + estrutura de diretórios)
- Validar estrutura de repositório HF (audio/index/validations/audit)
- Documentar todas as decisões em
docs/architecture-decisions.md
Critério de Pronto:
- Documento de decisões assinado
- Time alinhado em tecnologia stack
- Nenhuma bloqueante técnica identificada
Task 1.3: Estrutura Base de Módulos (2 dias, 3 pts)
Objetivo: Criar interfaces/contracts de todos os módulos
Tarefas:
- Criar
src/auth/__init__.py+auth_service.py(skeleton com docstrings) - Criar
src/repository/__init__.py+repo_service.py(skeleton) - Criar
src/upload/__init__.py+scanner.py,uploader.py,deduplicator.py(skeleton) - Criar
src/csv/__init__.py+csv_matcher.py,indexer.py(skeleton) - Criar
src/session/__init__.py+session_manager.py,checkpoint.py(skeleton) - Criar
src/ui/__init__.py+tui.py,progress_renderer.py(skeleton) - Criar
src/logger/__init__.py+structured_logger.py(skeleton) - Criar
src/utils/__init__.py+file_utils.py,hash_utils.py,error_handler.py(skeleton)
Critério de Pronto:
- Todos os módulos existem com
passou docstrings - Nenhum erro de import circular
python -c "import src; print('OK')"funciona
Task 1.4: Testes Base + Test Fixtures (1 dia, 2 pts)
Objetivo: Infraestrutura de testes pronta
Tarefas:
- Setup
pytest.inieconftest.py - Criar test fixtures para:
- Mock HfApi
- Pasta local temporária com arquivos de teste
- Session mock
- Token mock
- Criar
tests/test_auth.py(skeleton) - Criar
tests/test_uploader.py(skeleton) - Criar
tests/test_session.py(skeleton)
Critério de Pronto:
pytestexecuta sem erro (mesmo que tests sejam vazios)- Fixtures estão disponíveis para todos os testes
Semana 2: Auth + Repository Services
Task 2.1: Auth Service - Implementação Completa (2.5 dias, 5 pts)
Objetivo: Login com token, validação, armazenamento seguro
Tarefas:
- Implementar
AuthService.authenticate(token):- Validar token contra HF API
- Recuperar info do usuário (username, email, user_id)
- Salvar em keyring (Windows DPAPI)
- Retornar user context
- Implementar
AuthService.get_stored_token():- Recuperar token do keyring
- Lançar erro claro se não encontrado
- Implementar
AuthService.clear_token():- Remover token do keyring
- Implementar
TokenManager:- Gerenciar TTL de token
- Detectar expiração
- Forçar re-autenticação se necessário
- Tests:
-
test_auth_valid_token() -
test_auth_invalid_token() -
test_auth_token_stored_in_keyring() -
test_auth_token_retrieval()
-
Critério de Pronto:
- Todos os testes de auth passando
- Token nunca é logado/printed
- Falha de auth retorna mensagem clara
Task 2.2: Repository Service - Criar Dataset (2 dias, 4 pts)
Objetivo: Criar dataset HF e inicializar estrutura padrão
Tarefas:
- Implementar
RepositoryService.create_dataset():- Validar nome do repositório (slug format)
- Criar dataset no HF (público/privado)
- Inicializar pastas padrão (audio/, index/shards/, validations/, audit/)
- Criar manifest.json inicial
- Retornar repo_id
- Implementar
RepositoryService.validate_repo():- Verificar permissão de escrita
- Verificar estrutura esperada
- Retornar validation result
- Tests:
-
test_create_dataset_public() -
test_create_dataset_private() -
test_create_dataset_name_validation() -
test_validate_repo_structure()
-
Critério de Pronto:
- Dataset criado no HF com structure correta
- Manifest.json com schema_version, project_slug, index
- Testes mockeados passando
Task 2.3: Config + Constants Finalizadas (1 dia, 2 pts)
Objetivo: Configuração centralizada do app
Tarefas:
- Criar
src/config.py:AUDIO_EXTENSIONS = ['.wav', '.mp3', '.flac', '.ogg']SESSION_DIR = ~/.birdnet-uploader/sessions/CACHE_DIR = ~/.birdnet-uploader/cache/MAX_BATCH_SIZE = 10RETRY_MAX_ATTEMPTS = 3RETRY_INITIAL_BACKOFF = 1.0MANIFEST_SCHEMA_VERSION = "1.0.0"
- Implementar config via
.envse necessário
Critério de Pronto:
- Todas as constantes centralizadas
- Nenhum hardcoded value em módulos
Task 2.4: Error Handling Framework (1.5 dias, 3 pts)
Objetivo: Exceções customizadas e mensagens claras
Tarefas:
- Criar
src/exceptions.py:AuthenticationErrorRepositoryErrorUploadErrorSessionErrorValidationError
- Implementar
src/utils/error_handler.py:- Converter exceções em mensagens user-friendly
- Log estruturado de erros
- Sugestões de ação
Critério de Pronto:
- Todas as exceções possuem mensagem clara
- Tests cobrem cenários de erro
SPRINT 2: Upload & CSV Matching (Semanas 3-4)
Semana 3: Scanner + File Operations
Task 3.1: Local Scanner - Varrer Pasta (2 dias, 4 pts)
Objetivo: Descobrir arquivos locais, agrupar por espécie
Tarefas:
- Implementar
LocalScanner.scan_folder():- Varrer recursivamente
- Filtrar por extensões de áudio
- Inferir espécie do caminho/nome
- Calcular tamanho total e contagem
- Retornar estrutura normalizada
- Implementar estratégia de inferência de espécie:
- Strategy 1: Usar última pasta como specie
- Strategy 2: Usar prefixo do arquivo
- Strategy 3: Permitir mapeamento manual
- Tests:
-
test_scan_folder_empty() -
test_scan_folder_multiple_species() -
test_scan_folder_specie_inference() -
test_scan_folder_with_nested_dirs()
-
Critério de Pronto:
- Escaneia pasta com 1000+ arquivos em <5 segundos
- Estrutura normalizada e validada
Task 3.2: Hash Utils + File Operations (1.5 dias, 3 pts)
Objetivo: Computação de hash segura, operações de arquivo
Tarefas:
- Implementar
compute_file_hash(path) -> str:- SHA256 eficiente (streaming para arquivos grandes)
- Cache local de hashes
- Implementar
verify_file_integrity(path, hash):- Validar arquivo não corrompido
- Tests:
-
test_compute_hash_small_file() -
test_compute_hash_large_file() -
test_hash_consistency()
-
Critério de Pronto:
- Hash de arquivo 1GB < 2 segundos
- Testes passando
Task 3.3: Deduplicator - Verificar Existência (2 dias, 3 pts)
Objetivo: Detectar arquivos já no destino
Tarefas:
- Implementar
Deduplicator.check_remote():- Query HF API para verificar existência por caminho
- Comparar tamanho + hash opcional
- Retornar status (SKIP, UPLOAD, CONFLICT)
- Implementar dedup local cache (evitar queries repetidas)
- Tests:
-
test_check_remote_new_file() -
test_check_remote_existing_file() -
test_check_remote_conflict()
-
Critério de Pronto:
- Dedup funciona sem re-query excessiva
- Cache valida corretamente
Task 3.4: Session + Checkpoint - State Persistence (2.5 dias, 5 pts)
Objetivo: Persistência atomática de estado para retomada
Tarefas:
- Implementar
SessionManager.create_session():- Gerar session_id
- Criar diretório de sessão
- Inicializar metadata.json
- Implementar
CheckpointManager.save_checkpoint():- Escrita atômica (temp + rename)
- Validação de JSON
- Flush para disco (fsync)
- Implementar
CheckpointManager.load_checkpoint():- Recuperar último checkpoint
- Validação de integridade
- Implementar
SessionManager.mark_file_done():- Atualizar manifest por arquivo
- Tests:
-
test_session_creation() -
test_checkpoint_atomic_write() -
test_checkpoint_recovery_after_crash() -
test_session_resume_same_id()
-
Critério de Pronto:
- Checkpoint atomático garante consistência
- Recuperação de crash funciona
- Testes cobrem falha de escrita
Semana 4: Upload Engine + CSV Matching
Task 4.1: Batch Uploader - Motor Principal (3 dias, 6 pts)
Objetivo: Upload resiliente com retry/dedup/pause
Tarefas:
- Implementar
BatchUploader.upload_files():- Iterar sobre estrutura de arquivos
- Aplicar dedup check
- Upload com retry automático
- Atualizar checkpoint por lote
- Callback de progresso
- Implementar retry com exponential backoff:
- Backoff: 1s → 2s → 5s → 10s → 30s
- Tratamento de 429 (rate limit)
- Max 3 retries por padrão
- Implementar pause/resume:
- Signal SIGTERM/SIGINT
- Salvar state
- Resume com checkpoint
- Tests:
-
test_upload_batch_success() -
test_upload_with_retry() -
test_upload_skip_existing() -
test_upload_pause_resume()
-
Critério de Pronto:
- Upload funciona end-to-end
- Retry logic testado
- Pause/resume funciona
Task 4.2: CSV Matcher + Index Generator (2.5 dias, 5 pts)
Objetivo: Matching CSV com segmentos e geração de índice
Tarefas:
- Implementar
CSVMatcher.match_detections():- Ler CSV com validação de schema
- Fazer matching com segmentos (source_file → arquivo local)
- Gerar detection_key determinístico
- Retornar matched + unmatched + ambiguous
- Implementar
IndexGenerator.generate_shards():- Particionar dados em shards (tamanho configurável)
- Salvar como parquet
- Gerar metadata de shards
- Implementar
ManifestBuilder.build():- Construir manifest.json com schema_version
- Incluir metadados de index
- Serializar JSON
- Tests:
-
test_csv_matching_success() -
test_csv_missing_columns() -
test_shard_generation() -
test_manifest_format()
-
Critério de Pronto:
- CSV+segmentos matchados corretamente
- Shards gerados com formato correto
- Manifest válido e legível
SPRINT 3: UI + Integration (Semanas 5-6)
Semana 5: UI TUI Implementation
Task 5.1: Textual TUI - Fluxo Principal (3 dias, 6 pts)
Objetivo: Interface TUI moderna para guiar usuário
Tarefas:
- Criar
src/ui/screens/login_screen.py:- Input para token HF
- Validação em tempo real
- Mensagens de erro claras
- Criar
src/ui/screens/config_screen.py:- Form com campos: repo name, visibility, segments path, csv path
- Verificação de pasta
- Validação de formato
- Criar
src/ui/screens/summary_screen.py:- Exibir configuração resumida
- Botão de confirmação
- Criar
src/ui/screens/upload_screen.py:- Barra de progresso principal
- Progresso por arquivo
- Arquivo atual
- Último evento
- Botões pause/cancel
- Implementar navegação entre screens
Critério de Pronto:
- Fluxo completo funcionando (login → config → summary → upload)
- Inputs validados
- Navegação intuitiva
Task 5.2: Progress Renderer (1.5 dias, 3 pts)
Objetivo: Visualização rich de progresso
Tarefas:
- Implementar progress bar customizada:
- Percentual + barra visual
- ETA com update em tempo real
- Arquivo atual
- Contadores (uploaded/pending/failed/skipped)
- Implementar event log:
- Últimos 10 eventos
- Código de status/cor por tipo
Critério de Pronto:
- Progress bar atualiza sem flicker
- ETA coerente
- Eventos visíveis
Semana 6: Integration + Testes End-to-End
Task 6.1: Integration Testing + Mocks (2 dias, 4 pts)
Objetivo: Teste de fluxo completo (mockeado)
Tarefas:
- Criar
tests/test_integration.py:- Teste login + config + upload (mockeado)
- Teste pause/resume
- Teste com CSV
- Mockar HfApi completamente
- Rodar testes de carga (1000+ arquivos mockeados)
Critério de Pronto:
- Testes de integração passando
- Sem vazamento de recursos
Task 6.2: Real Integration Test (pequena escala) (2 dias, 4 pts)
Objetivo: Teste real com dataset HF de verdade
Tarefas:
- Criar dataset de teste no HF (alice/test-uploader-small)
- Teste com 100 arquivos reais (~500MB)
- Validar estrutura no HF pós-upload
- Validar manifest.json e shards
Critério de Pronto:
- Arquivos aparecem no HF
- Estrutura correta
- Manifest válido
SPRINT 4: Build + Polish (Semanas 7-8)
Semana 7: Build + Release
Task 7.1: PyInstaller Setup (2 dias, 4 pts)
Objetivo: Gerar executável portátil Windows
Tarefas:
- Criar
build/pyinstaller_config.spec:- One-file executable
- Hidden imports para textual, rich, pandas, pyarrow
- Resource bundling
- Criar
build/build.pyscript - Testar executável gerado localmente
- Validar tamanho (~100-150MB)
Critério de Pronto:
- Executável funciona sem Python instalado
- Tamanho razoável
- Sem erros de runtime
Task 7.2: Documentação + README (1.5 dias, 2 pts)
Objetivo: Docs para usuários finais
Tarefas:
- Criar README.md com:
- Quick start (download, run, autenticar)
- Screenshots
- Troubleshooting
- FAQ
- Criar INSTALLATION.md
- Criar USAGE.md (exemplos de comando)
Critério de Pronto:
- Usuário não-técnico consegue rodar pelo README
Task 7.3: Testes de Carga + Stress (2 dias, 4 pts)
Objetivo: Validar com dados reais maiores
Tarefas:
- Teste com pasta 5GB (1000+ arquivos)
- Teste com CSV 5000+ linhas
- Teste pause/resume 5x
- Monitorar memória e CPU
- Documentar performance (tempo/MB/s)
Critério de Pronto:
- Memória < 500MB durante upload
- CPU < 30% média
- Upload rate > 5 MB/s (com rede OK)
Semana 8: Release + Smoke Tests
Task 8.1: Release Pipeline (1.5 dias, 2 pts)
Objetivo: Setup de distribuição
Tarefas:
- Criar release no GitHub com:
- Executável (
.exe) - SHA256 hash
- Release notes
- Link para docs
- Executável (
- Testar download + execução do exe
- Validar assinatura (opcional nesta fase)
Critério de Pronto:
- Release publicado
- Download funciona
- Exe roda após download/extração
Task 8.2: Smoke Tests + Final QA (1.5 dias, 3 pts)
Objetivo: Validação final antes do release
Tarefas:
- Checklist final:
- Login funciona
- Criar repo funciona
- Upload de 10GB completa
- Pause/resume sem perda
- CSV matching correto
- Manifest válido no destino
- Estrutura compatível com validador
- Teste com 3+ usuários externos (team)
- Coleta de feedback
Critério de Pronto:
- Zero bugs críticos
- Feedback incorporado
- Pronto para release
BACKLOG: Priorização de Tasks
| Sprint | Semana | Task | Pts | Status |
|---|---|---|---|---|
| 1 | 1 | Setup + Design | 5 | Não iniciado |
| 1 | 1 | Arquitetura de Módulos | 3 | Não iniciado |
| 1 | 1 | Test Infrastructure | 2 | Não iniciado |
| 1 | 2 | Auth Service | 5 | Bloqueado por 1.1 |
| 1 | 2 | Repository Service | 4 | Bloqueado por 1.1 |
| 1 | 2 | Config + Constants | 2 | Bloqueado por 1.1 |
| 1 | 2 | Error Handling | 3 | Bloqueado por 1.1 |
| 2 | 3 | Local Scanner | 4 | Bloqueado por Sprint 1 |
| 2 | 3 | Hash Utils | 3 | Bloqueado por Sprint 1 |
| 2 | 3 | Deduplicator | 3 | Bloqueado por Sprint 1 |
| 2 | 3 | Session + Checkpoint | 5 | Bloqueado por Sprint 1 |
| 2 | 4 | Batch Uploader | 6 | Bloqueado por Sprint 1 |
| 2 | 4 | CSV Matcher | 5 | Bloqueado por Sprint 1 |
| 3 | 5 | Textual TUI | 6 | Bloqueado por Sprint 2 |
| 3 | 5 | Progress Renderer | 3 | Bloqueado por Sprint 2 |
| 3 | 6 | Integration Tests | 4 | Bloqueado por Sprint 2 |
| 3 | 6 | Real Integration Test | 4 | Bloqueado por Sprint 2 |
| 4 | 7 | PyInstaller | 4 | Bloqueado por Sprint 3 |
| 4 | 7 | Documentation | 2 | Bloqueado por Sprint 3 |
| 4 | 7 | Load Testing | 4 | Bloqueado por Sprint 3 |
| 4 | 8 | Release Pipeline | 2 | Bloqueado por Sprint 3 |
| 4 | 8 | Final QA | 3 | Bloqueado por Sprint 3 |
Total: ~84 story points (6-8 semanas com 2-3 eng)
Velocity + Alocação de Equipe
Cenário 1: Full Team (2 eng)
- Sprint de 2 semanas, 2 eng = ~40 pts/sprint
- Sprint 1-2: 26 pts (semana 1 paralelo, semana 2 paralelo) ✓ cabe
- Sprint 2 continuation: ~20 pts (cabe)
- Sprint 3: ~13 pts (cabe)
- Sprint 4: ~15 pts (cabe)
Cenário 2: 3 Eng (Backend + Frontend + QA)
- Paralelizar mais agressivamente
- Timeline pode reduzir de 8 para 6-7 semanas
Critérios de "Done" por Sprint
Sprint 1 Done ✓
- Todos os módulos base existem (importáveis)
- Auth funciona com keyring
- Repo pode ser criado no HF
- Testes de auth e repo passando
- Setup pronto para Sprint 2
Sprint 2 Done ✓
- Scanner varre pasta corretamente
- Uploader faz batch com retry
- CSV matcher funciona end-to-end
- Checkpoint salva e recupera estado
- Testes cobrem 80%+ de lógica
Sprint 3 Done ✓
- Fluxo TUI completo (login → config → upload)
- Progresso visual atualiza sem flicker
- Integração completa mockeada testada
- Real integration test com 500MB+ passou
- Pronto para build
Sprint 4 Done ✓
- Executável portátil gerado e testado
- Release pipeline setup
- Documentação completa
- Smoke tests passando
- Pronto para distribuição
Next Steps
- Aprovação: Confirmar timeline, team size, prioridades
- Sprint 1 Kickoff: Semana que vem
- Daily Standups: 15min todo dia weekday
- Sprint Reviews: Sexta-feira cada semana
- Retrospectives: Fim de cada sprint
Notas & Riscos
- Risco 1: PyInstaller não empacotar corretamente → Mitigar: spike de 1 dia em week 7
- Risco 2: Performance ruim em 50GB+ → Mitigar: load test cedo (week 4)
- Risco 3: Incompatibilidade com validador → Mitigar: validação de manifest early (week 4)
- Risco 4: UX TUI confusa → Mitigar: user testing em week 6
Todas as risks têm mitigation strategy atrelada.