Módulos

Escolha o módulo onde sua mudança se encaixa e saiba quais módulos ele pode chamar.

Antes de começar

• Leia Arquitetura para ver o mapa de pastas e as regras.
• Cada módulo tem o mesmo nome em app/backend/internal/<module>/, e em app/frontend/src/lib/<module>/ e app/tests/<module>/ quando tem telas ou testes de navegador.

Encontre o módulo certo

Módulo	Faz
requests	Pedidos, aprovações, regras de pedidos, listas externas, relatos
movies	Títulos de filmes, edições, coleções, busca e organização
shows	Séries, temporadas, episódios, busca e organização
music	Artistas, álbuns, faixas, busca e organização
sources	Fontes, a ponte com o Jackett e o Prowlarr, busca de Lançamentos
downloads	Gerenciadores de downloads, a fila, arquivos vistos, mapas de caminhos, tags, opções de cópia
subtitles	Idiomas de legendas, sites, correspondência e salvamento
discover	Explorar, Populares, Buscar, Pessoas, Calendário, páginas de título
suggest	Escolha e ordenação de fileiras e prateleiras (só backend)
mediafiles	Registros do catálogo, regras de escolha, nomes, pacotes de dados, detalhes de mídia
importer	Importação de arquivos: descompactação, tags, correspondência (só backend)
library	Pastas da Biblioteca, adoção e renomeação (só backend)
metadata	O cliente de dados externos, consultas de música, escalas de classificação, trailers
mediaservers	Avisar o Plex, o Jellyfin e o Emby para olharem de novo
accounts	Usuários, login, login único (SSO), login de apps de IA, limites para crianças, opções de exibição
alerts	Canais de alerta e quando eles falam
migrate	Trazer dados dos apps anteriores
arrapi	A API no estilo do Sonarr e do Radarr
ai	Conexões de apps de IA (retido)
backups	Criar, manter e restaurar backups
health	Verificações de saúde, o doctor, o pacote de suporte
updates	A verificação de atualizações e a lista de atualizações assinada
setup	O assistente de primeira execução

Ordem das camadas

Um módulo importa só uma camada mais baixa. Nada importa discover. O tools/structurecheck/allow.go é a fonte da verdade.

Camada	Módulos
0	core
1	metadata, suggest
2	accounts
3	mediafiles
4	importer
5	library
6	sources
7	downloads
8	subtitles, mediaservers, alerts
9	movies, shows
10	requests, health
11	music, arrapi, migrate, ai, backups, updates, setup
13	discover

Se seu módulo precisa de algo de uma camada mais alta, não importe essa camada. Faça o módulo mais alto passar dados simples para baixo, ou defina no mais baixo uma interface pequena que o wiring.go preenche.

Adicione uma rota ou um módulo

Rota nova

Registre a rota no routes.go do módulo, com a permissão dela. O openapi.json vem das rotas, e um teste falha se houver diferença. Caminhos e nomes de campos já lançados ficam como estão. Adicione campos, nunca renomeie. Depois, reescreva Rotas da API com go run ./app/backend/tools/apidoc.

Módulo novo

Primeiro tente encaixar sua mudança nos 23, e abra uma issue antes de adicionar um. Um módulo novo precisa da pasta de backend (mais lib/<module>/ e app/tests/<module>/ se tiver telas), de um lugar na ordem das camadas em tools/structurecheck e de uma linha no wiring.go.

Se não funcionar

Sintoma. TestModuleEdges falha. Causa. Um módulo importa outro da mesma camada ou de uma camada mais alta. Solução. Passe dados simples para baixo a partir do módulo mais alto, ou adicione uma interface pequena ligada no wiring.go.

Sintoma. TestSQLOnlyInStore ou TestTableOwnership falha. Causa. Há SQL fora de um arquivo store*.go, ou SQL que mexe na tabela de outro módulo. Solução. Mova a consulta para o store do dono e chame o serviço do dono por ID.

Para especialistas

Mais regras

• Um módulo importa só o pacote raiz de outro módulo.
• As funções de store recebem um database.Querier. Leia as linhas de outro módulo pelo serviço dele, por ID, e passe listas longas de IDs como um único array JSON com json_each(?).
• settings, schedules, secrets, jobs e events são do core. Cada grupo de configurações tem um módulo dono. Para mudar o grupo de outro módulo, chame o dono.
• Toda chamada externa passa por core/outbound.
• Os pacotes do core ficam em fileiras, de cima para baixo: parts, webserver e startup, logs, jobs e model, outbound e secrets, depois database, files e releasename. Um pacote do core importa só da própria fileira ou de uma mais baixa.
• Nomes: arquivos Go ficam em minúsculas com underscores, partes Svelte ficam em PascalCase, e TypeScript, docs, testes e arquivos de deploy ficam em kebab-case. Arquivos Python usam underscores para poderem ser importados. As pastas em app/ ficam em minúsculas, com uma palavra só.
• Renomeie o código à vontade, mas tudo o que é armazenado ou enviado mantém o nome: tabelas e colunas, chaves de configuração, campos JSON, nomes de tarefas e nomes de chaves.
• Os comentários não levam números do roadmap, datas, nomes nem travessões.

Donos dos registros

Dono	Registros
mediafiles	Title, Item, Version, Slot, Part, File, LibraryFolder, Quality, PickRules
downloads	Download, Downloader, SeenFile, PathMap
sources	Source, Release
requests	Ask, Report
accounts	User
core/jobs	Job, Schedule, JobError
core/database	Event e os campos de linha compartilhados

As verificações

As verificações ficam em app/backend/tools/structurecheck. A maioria precisa de -tags structure.

Verificação	Garante
TestTopLayout	As pastas do topo do repositório
TestModuleSet, TestCoreSet, TestPackageMap	As pastas permitidas em internal/ e internal/core/
TestModuleEdges	A ordem das camadas
TestModuleImportsRootOnly	Imports só do pacote raiz
TestCoreImportsNoModule, TestCoreRowOrder, TestCoreNamesNoModuleTable	Os imports, a ordem das fileiras e os nomes do core
TestSQLOnlyInStore, TestTableOwnership, TestSQLAllowlistShrinks, TestSeedSQLAllowlist	O lugar do SQL e os donos das tabelas
TestGoFileNames, TestNoBannedPackageNames	Os nomes de arquivos e de pacotes
TestFileSizeCap, TestCorePackageSize	O tamanho dos arquivos e dos pacotes do core
TestCommentHygiene	As regras de comentários acima
TestRouteTableUnchanged, TestMigrationsUnchanged, TestHeaderAndJSONLiteralsUnchanged	Uma movimentação de código não muda nenhuma rota, migração, nome de cabeçalho HTTP ou chave JSON
TestNoOldPageAddresses, TestNoOldPagesInTestsOrDocs	Os endereços antigos de páginas continuam fora do código, dos testes e dos docs
TestNoDependencyBotConfig	Nenhum arquivo de bot de dependências em .github

Relacionados

• Arquitetura
• Testes
• Rotas da API