🎙️ speech-ai-hexagonal
API de transcrição de áudio com arquitetura hexagonal — Java 25 · Spring Boot 4 · Speaches/Whisper
🚀 Sobre o projeto
O speech-ai-hexagonal é uma API REST de transcrição de áudio construída com arquitetura hexagonal (Ports & Adapters). O domínio de negócio é completamente isolado da infraestrutura por meio de interfaces (portas), permitindo trocar o motor de transcrição (Speaches → OpenAI), o cache (InMemory → Redis) ou qualquer adapter sem alterar uma linha do use case.
Cada fase adiciona uma camada de maturidade técnica: da base hexagonal até cache, observabilidade, resiliência, Spring AI e mensageria assíncrona com RabbitMQ.
📍 Roadmap
Fase 1
Base hexagonal — transcrição local com Speaches/Whisper · RestClient · Lombok · MapStruct
✓
v1.7.0
Fase 2
Qualidade de código — SonarQube · JaCoCo · Coverage Gate · análise estática · pipeline local
✓
v2.5.0
Fase 3
Persistência de transcrições · PostgreSQL · Flyway · deduplicação por SHA-256
✓
v3.7.0
Fase 4
Cache Redis — SHA-256 · RedisCacheAdapter · TTL configurável · Testcontainers
✓
v4.3.0
Fase 5
Resiliência — Circuit Breaker · Retry · Bulkhead (Resilience4j)
✓
v5.3.0
Fase 6
Observabilidade — Prometheus · Grafana · Zipkin/OTel · Logs JSON + MDC
✓
v6.5.0
Fase 7
Validação automatizada da arquitetura hexagonal
✓
v7.1.0
Fase 8
Spring AI + OpenAI Whisper — segunda porta de saída (cloud)
✓
v8.2.0
Fase 9
Spring AI + Ollama — sumarização local via LLM ≤1B parâmetros
✓
v9.3.0
Fase 10
RabbitMQ — eventos assíncronos · DLQ · auditoria de transcrições
✓
v10.2.0
Fase 11
Notificação (SMS, WhatsAPP, Email)
✓
v11.5.0
Fase 12
Documentação OpenAPI e Swagger
✓
v12.1.0
Fase 13
CI/CD — GitHub Actions · Docker Hub · multi-arch
planejado
v12.2.0
⚡ Quick Start
# Subir infra (Speaches)
docker compose -f docker-compose.dev.yml up -d
# Baixar modelo (1ª vez)
uvx speaches-cli model download Systran/faster-whisper-small
# Rodar a API
./gradlew bootRun --args='--spring.profiles.active=dev'
# Transcrever
curl -X POST http://localhost:8080/api/transcriptions \
-F 'file=@audio.wav;type=audio/wav' | jq .
# Swagger UI
open http://localhost:8080/swagger-ui.html
🛠️ Stack
Java 25
Linguagem + Records + Pattern Matching
Spring Boot 4.0.6
Framework web + DI
RestClient
Cliente HTTP síncrono (Spring 6.1+)
Speaches
Servidor Whisper local (latest-cuda)
faster-whisper-small
Modelo de transcrição local
Lombok
Redução de boilerplate
MapStruct
Mapeamento entre camadas
Springdoc OpenAPI
Swagger UI automático
JaCoCo
Cobertura de código (≥60%)
MockWebServer
Testes de adapters HTTP
Testcontainers
Testes de integração reais
Docker Compose
Orquestração local
Prometheus
Métricas e scraping
Logs JSON
Logback + MDC + requestId
Redis
Cache SHA-256, TTL 24h
Grafana
12 painéis provisionados
Zipkin/OTel
Tracing distribuído
CircuitBreaker
Resilience4j, fallback 503
Retry
Backoff exponencial
SonarCloud
Qualidade contínua
SonarQube local
Análise local (Docker dev)
GitHub Actions
CI/CD automático
Bean Validation
DTOs validados
Hexagonaln
Ports & Adapters
RabbitMQ
Mensageria assíncrona
Spring Mail
E-mail via SMTP + GreenMail (testes)
Notificaçõesn
SMS · WhatsApp · e-mail
Spring AI
ChatClient · Ollama integration
Ollama
LLM local offline — llama3.2, mistral