Participa: como o sistema é concebido e o que ele entrega

1Contexto

Antes de olhar o que mudou, vale entender o que é este sistema. Há dois níveis: uma introdução para quem nunca viu Decidim (pode pular se você já conhece) e, em seguida, o recorte específico deste repositório.

1.1 Decidim para iniciantes

O Decidim é um framework de democracia participativa escrito em Ruby on Rails. A ideia central é que uma prefeitura ou um ministério queira abrir parte da sua gestão para participação popular — orçamento, consultas, propostas, audiências — e o Decidim dá a estrutura pronta para isso.

Três conceitos organizam tudo:

• Organization (organização) — o “inquilino”. Cada órgão (Ministério, Prefeitura) é uma organização, com domínio e identidade próprios.
• Participatory space (espaço participativo) — o contêiner do processo. Exemplos: Processo Participativo (um ciclo de consulta com etapas), Assembleia, Conferência, Iniciativa (proposta de lei por assinaturas).
• Component (componente) — a ferramenta dentro do espaço. Exemplos: Proposals, Meetings, Budgets, Surveys, Blogs, Pages, Accountability, Debates, Sortitions.

Um app Decidim “gerado” é surpreendentemente fino: um punhado de arquivos de configuração mais o Gemfile. Todo o comportamento vem das dependências (engines). A customização de um projeto Decidim costuma virar uma engine própria — uma gem de caminho local que estende as views e classes do core sem fazer monkey-patch, geralmente com Deface (que reescreve trechos de HTML do core por seletor).

1.2 O terreno deste repositório

O repositório participa segue exatamente esse desenho — é um wrapper Rails fino sobre o Decidim, onde a customização vive quase toda em uma engine e em módulos externos.

Repare no que não existe: não há um diretório gordo de regras de negócio. O valor do produto mora na composição — identidade gov.br + pele GovBR + pacote de módulos + infraestrutura multi-tenant. É o inverso de “escrever tudo do zero”: a equipe estende um framework maduro e mantém, à parte, os módulos que precisaram divergir.

2Intuição

Duas ideias explicam quase todo o repositório. A primeira é arquitetural; a segunda é a forma como o produto foi construído.

2.1 Um Decidim, um banco, muitos órgãos

Suponha que o Ministério X e a Prefeitura Y queiram usar a mesma instância do Participa. Se cada um rodasse seu próprio servidor, seriam dois deploys, duas atualizações, dois bancos — caro e fragmentado. A alternativa é compartilhar o código e o servidor, isolando apenas os dados.

É isso que “one Decidim, one DB” significa: um banco PostgreSQL, mas um schema por organização. Schema, no Postgres, é um namespace de tabelas dentro do mesmo banco. Então as tabelas têm o mesmo formato nos dois schemas:

O ros-apartment faz o trabalho pesado: ao entrar uma requisição, ele descobre a organização pelo host e muda o search_path da conexão para o schema certo. Do ponto de vista do Decidim, parece que só existe uma organização. Existe uma pegadinha: as migrations precisam rodar em todos os schemas — daí as rake tasks apartment_sync / apartment_audit / apartment_repair_plan.

2.2 Três camadas sobrepostas

A segunda intuição vem do histórico: o Participa não foi “projetado de uma vez”. Ele ganhou identidade em três camadas que se empilharam ao longo dos meses — e é isso que o roadmap da seção 4 mostra.

1. Fundação multi-tenant (ago/2025) — “um Decidim, um banco, múltiplos schemas”.
2. Pele GovBR + identidade (ago–out/2025 e jun/2026) — login gov.br, login efêmero e o Design System do Governo Federal por cima da UI do Decidim.
3. Expansão de módulos (2025–2026) — o pacote que transforma a plataforma de “democracia digital básica” num ecossistema de participação.

3Top 10 funcionalidades

Se o repositório tivesse que ser resumido em dez entregas de valor, seriam estas — cada uma com a evidência no código e no histórico.

4Roadmap

O mesmo histórico, agora organizado na taxonomia pedida. Cada nível responde a uma pergunta diferente:

4.1 Os Cycles (janelas de execução)

O projeto não teve “sprints” formais, mas a cadência dos commits desenha janelas claras. Derivamos sete cycles a partir das datas reais:

4.2 Initiatives → Issues

Abaixo, as cinco Initiatives estratégicas. Para cada uma: os Projects com dono e escopo, o Cycle em que aconteceram, e a decomposição em Issues → Sub-issues concretas.

5Passeio pelo código

Agora, onde cada peça do roadmap vive no repositório. Agrupado para leitura linear, não por pasta.

5.1 A casca do app e a engine

O app/ da raiz guarda apenas overrides do core (Comments, Proposals, Reports, Matomo) e o entrypoint DecidimController. O grosso está na engine:

# decidim-govbr/lib/decidim/govbr/engine.rb (resumo)
initializer "decidim-govbr.webpacker.assets_path" do
  Decidim.register_assets_path File.expand_path("app/packs", root)
end

initializer "decidim-govbr.homepage_content_blocks" do
  Decidim::Govbr::Homepage::ContentBlocks.register_homepage_content_blocks!
end

initializer "decidim-govbr.optional_hero_text_and_cta",
            after: "decidim_core.homepage_content_blocks" do
  manifest = Decidim.content_blocks.for(:homepage).find { |b| b.name == :hero }
  manifest.cell = "decidim/govbr/homepage/content_block/hero"   # repointa o bloco do core
end

Note o padrão: a engine não recria o bloco hero — ela reaponta o manifest já registrado pelo core para a sua própria cell. Como ContentBlockRegistry#register não aceita nome duplicado, a única saída é mutar o manifest existente. É um detalhe de framework que explica vários comentários longos no código.

5.2 Multi-tenant

O config/initializers/apartment.rb é deliberadamente trivial — a mágica vive na gem decidim-apartment:

Rails.application.config.after_initialize do
  ActiveRecord::Migrator.migrations_paths = Rails.application.paths['db/migrate'].to_a
end

# config/application.rb — a razão de dump_schemas ser "public":
# sem isto, o dumper do Rails 8.1 prefixa toda tabela com o schema e o
# schema.rb deixa de carregar (create_table "public.decidim_users" …).
config.active_record.dump_schemas = "public"

5.3 Identidade: gov.br e efêmero

O login efêmero é quase todo declarativo — repare em ephemeral = true:

# config/initializers/ephemeral_auth.rb
Decidim::Verifications.register_workflow(:govbr_authorization_handler) do |workflow|
  workflow.ephemeral = true
  workflow.form = "GovbrAuthorizationHandler"
end

E a regra de elegibilidade, em Ruby direto:

# decidim-govbr/app/services/govbr_authorization_handler.rb
def unique_id
  Digest::SHA256.hexdigest("#{document_number}-#{Rails.application.secret_key_base}")
end

def validate_document_number
  cpf = document_number.gsub(/\D/, '')
  errors.add(:document_number, I18n.t('errors.messages.invalid_document')) unless cpf.length == 11
end

5.4 Content blocks: a home como produto

A cell de notícias mostra o contrato real — busca os posts publicados da organização atual:

# decidim-govbr/app/cells/decidim/govbr/homepage/content_block/blog_news_cell.rb
def recent_posts
  @recent_posts ||= Decidim::Blogs::Post
                    .published
                    .where(component: blogs_components)
                    .created_at_desc
                    .limit(4)
                    .to_a
end

5.5 Deploy e CI

O .gitlab-ci.yml tem seis estágios: security → build_dev_image → build_bump_image → build_prod_image → reports → release. Os quatro scanners rodam com allow_failure: true e geram um security-reports.zip. A imagem prod é construída só em tags, disparando um release com changelog gerado a partir dos commits.

5.6 Observabilidade

Três frentes em initializers separados: matomo.rb (somente o container do Tag Manager), posthog.rb e pyroscope.rb (profiling contínuo, só em produção). O Pyroscope substituiu o OpenTelemetry — uma decisão de custo/simplicidade registrada em c7b0b0d.

6Código ↔ valor: gems externas

Boa parte do valor não está neste repositório. Está em módulos mantidos à parte e consumidos por git. Para rastrear uma funcionalidade até o código, é preciso ir ao repositório externo, na revisão fixada no Gemfile.lock.

7Casos-limite e armadilhas

8Como ler isto

A página foi escrita para ser lida de cima para baixo, mas ela também funciona como referência: a seção 3 dá o resumo executivo, a 4 dá a navegação por investimento, a 5–6 dão o cruzamento código ↔ valor.

Há um quiz de cinco perguntas esperando você no chat — ele quer checar se a substância (e não o texto) ficou. Quando terminar de ler, diga que está pronto.