coda/docs/architecture.md

Transcoder para Lidarr — Documento de Arquitetura

Objetivo

Este documento descreve a arquitetura da aplicação responsável por converter álbuns de FLAC para MP3 320 kbps CBR, acionada automaticamente por webhooks do Lidarr ou manualmente pela interface web, conforme os requisitos funcionais e não funcionais definidos no documento de requisitos.

---

1. Visão Geral

                   +--------------------+
                   |      Lidarr        |
                   +---------+----------+
                             |
                       Webhook HTTP
                             |
                             ▼
                 +----------------------+        +----------------------+
                 |   HTTP Server        |        |   Library Scanner    |
                 +----------+-----------+        +----------+-----------+
                            |                               |
                     cria nova tarefa              busca manual (web)
                            |                               |
                            +---------------+---------------+
                                            |
                                            ▼
                                   +--------------+
                                   |  Job Queue   |
                                   +------+-------+
                                          |
                                    Scheduler
                                  (Work Window)
                                          |
                                          ▼
                                     Worker Pool
                             +--------------+-------------+
                             |              |             |
                          Worker 1      Worker 2      Worker N
                             |              |             |
                             +--------------+-------------+
                                            |
                                            ▼
                                   Conversor (ffmpeg)
                                            |
                                            ▼
                                    Validação (ffprobe)
                                            |
                                            ▼
                                  Atualização do Lidarr
                                            |
                                            ▼
                              Config Service ← → SQLite
                                     ↓            ↑
                              Logger / Histórico ←┘
                                            |
                                            ▼
                                      Interface Web

---

2. Componentes

HTTP Server

Responsável por:

• receber webhooks do Lidarr;
• servir a interface web (dashboard, jobs, logs, library, settings);
• expor endpoints REST para a interface web (jobs, logs, config, scan);
• receber requisições de scan e conversão manual.

Queue

Fila interna baseada em canais (channels) do Go.

Responsável por:

• armazenar tarefas;
• controlar ordem de execução.

Worker Pool

Executa tarefas paralelamente, respeitando a janela de trabalho (quando habilitada).

Cada worker:

• recebe um álbum;
• converte todos os arquivos;
• valida;
• remove FLAC;
• atualiza o Lidarr;
• registra o resultado no SQLite.

Transcoder

Wrapper para execução do ffmpeg.

Responsável por:

• montar comandos;
• acompanhar progresso;
• capturar saída.

Validator

Executa verificações pós-conversão.

Pode utilizar:

• ffprobe;
• verificação de tamanho;
• existência dos arquivos.

Lidarr Client

Cliente HTTP responsável por:

• autenticação;
• envio do comando de rescan;
• tratamento de erros e tentativas de repetição.

Logger

Responsável por:

• logs estruturados;
• persistência em SQLite;
• disponibilização para consulta via interface web.

Storage (SQLite)

Responsável por:

• repositório de jobs (CRUD + consultas);
• repositório de logs (escrita e consulta paginada);
• repositório de configurações (persistência de overrides);
• execução de migrações automáticas na inicialização.

Scheduler / Work Window

Responsável por controlar o dispatch de tarefas para os workers com base na janela de trabalho configurada.

• se a janela está desabilitada (padrão), libera todas as tarefas imediatamente;
• se habilitada, só libera tarefas dentro do intervalo configurado (WORK_WINDOW_START — WORK_WINDOW_END);
• tarefas em andamento quando a janela fecha são finalizadas normalmente;
• utiliza o timezone configurado (TIMEZONE) para determinar o horário atual.

Config Service

Responsável por gerenciar a configuração da aplicação, fazendo merge entre:

• valores default (hard-coded);
• variáveis de ambiente (sobrescrevem os defaults);
• overrides persistidos no SQLite (sobrescrevem os env).

Expõe métodos para leitura e alteração em runtime, propagando as alterações para os componentes afetados.

Library Scanner

Responsável por:

• navegação por árvore de diretórios sob MUSIC_PATH;
• scan recursivo para detecção de arquivos FLAC e agrupamento por álbum;
• exposição dos resultados via API REST para a interface web;
• enfileiramento dos álbuns selecionados para conversão.

Web UI

Interface para operação e monitoramento do serviço.

Páginas sugeridas:

/          Dashboard (status geral, fila, janela de trabalho)
/jobs      Histórico de tarefas
/logs      Consulta de logs
/library   Navegação e busca de FLACs
/settings  Configuração da aplicação
/health    Health Check

---

3. Estrutura de Diretórios

cmd/
    server/

internal/
    config/
    scheduler/
    webhook/
    queue/
    worker/
    transcoder/
    validator/
    lidarr/
    logger/
    web/
    models/
    store/
    scanner/

web/
    styles/
    static/
    templates/

data/

Dockerfile

go.mod

---

4. Decisões Técnicas

Decisão	Escolha	Justificativa
Linguagem	Go 1.25.x	Performance, concorrência nativa, baixo footprint
Distribuição	Docker (Alpine Linux)	Imagem leve, portabilidade
HTTP Router	chi (go-chi/chi/v5)	Leve, stdlib-compatível (http.Handler), middlewares organizados, sem contexto próprio
Banco de Dados	SQLite embarcado (modernc.org/sqlite)	Histórico e config consultáveis, sem servidor externo, footprint baixo, sem CGO
Logging estruturado	log/slog (stdlib) + handler SQLite	Zero dependência, handler customizado para persistir no BD
ID de tarefa	github.com/google/uuid	Padrão simples e seguro para chave primária
Frontend	html/template + htmx + Tailwind CSS v4 + DaisyUI	Interatividade sem SPA; CSS gerado pelo Tailwind CLI standalone (sem Node)
Assets estáticos	Embutidos no binário (//go:embed)	Binário único, deploy simples, alinhado ao footprint baixo
Fila interna	Channels do Go	Simples, sem dependência externa
Conversão de áudio	ffmpeg (libmp3lame)	Maturidade, suporte a codecs
Validação	ffprobe	Padrão da indústria, integrado ao ffmpeg
Configuração	Env (default) + overrides no SQLite	Env define defaults; web permite override persistido
Agendador de tarefas	Scheduler interno (work window)	Evita processamento fora do horário desejado
Volume de mídia	Docker bind mount (mesmo path do Lidarr)	Acesso físico aos arquivos para conversão/remoção
Atualização do Lidarr	API REST do Lidarr	Integração direta, sem polling