Decidim Rails engines and changing internal APIs

Two commands and a Rails app with political structure inside

Decidim is a participatory democracy framework written in Ruby on Rails, originally developed for the Barcelona City government online and offline participation website. Installing the libraries gives you a generator and gems for building web applications like the example applications or the public demo.

The getting started path is two commands:

gem install decidim
decidim decidim_application

The framework's own summary is that it installs a gem, generates a Rails app, and that is the idea. What you do not get from a quickstart is the shape of the domain, which is the actual product: participatory processes, assemblies, and the components that hang off them.

That is also the differentiator against a generic forum or a petition platform. Decidim's modules are not plugins you bolt on arbitrarily, they are the vocabulary of a participation process, and adopting the framework means adopting that vocabulary.

There is a governance layer around the code as well. All members of the Decidim community agree with a published social contract, or Code of Democratic Guarantees, and contribution happens on Metadecidim, described as Decidim's own instance of Decidim used to improve Decidim. Development chat runs on Matrix rooms.

Roughly twenty engines, each a Rails engine

The top-level tree is the clearest map of the system. Every component is a separate Rails engine in the repository: decidim-accountability, decidim-admin, decidim-ai, decidim-api, decidim-assemblies, decidim-blogs, decidim-budgets, decidim-collaborative_texts, decidim-comments, decidim-conferences, decidim-core, decidim-debates, decidim-demographics, decidim-design, decidim-dev, decidim-elections, decidim-forms and decidim-generators, among others.

Read that list as the feature set. Budgets means participatory budgeting, with proposals and voting attached. Assemblies are deliberative groups. Conferences, debates, collaborative texts and blogs are the participation formats. Comments is the comment engine that other components embed. Elections and accountability are the components where scrutiny and result tracking live, and those two are why the framework is heavier than a forum.

The README describes a module as a Rails engine with Decidim-specific APIs for registering with the menus, integrating with spaces such as Participatory Processes or Assemblies, and hooking into /admin or /api. That is the extension mechanism, and the README is unusually candid about its stability: until v1.0.0 the project is under development and these internal APIs can change.

For anyone writing a module, the practical consequence is that you target a Decidim version, not a stable API surface, and the README tells you to check version compatibility and test extensively.

Front-end toolchain is part of the upgrade cost

Decidim is not only a Rails gem. The repository ships a Node toolchain for the front end, and package.json shows what that means in practice: engines for Node 24.18.0 or later and npm 11.16.0 or later, a browserslist config extended from @decidim/browserslist-config, React 19 pinned in dependencies, and a jest test setup with jsdom.

The scripts are the maintenance surface. Linting runs eslint over the decidim-* directories, stylelint and prettier check the SCSS, linthtml covers the ERB templates and cells, and markdownlint runs over the markdown. test:ci chains lint and test, which is the command to run before opening a pull request.

There is more linting configuration in the repository than most Rails projects carry: .erb_lint.yml with its own linters directory, .rubocop.yml with a .rubocop_todo.yml, .stylelintignore, .markdownlint.yml, .linthtmlrc.js, .csslintrc, .spelling.yml and .prettierignore, plus .coderabbit.yaml and a qlty maintainability configuration. Repository-wide formatting rules are enforced through shared config packages referenced as local file dependencies.

Practically: upgrading Decidim means matching Ruby, Rails, Node and npm expectations together, and the .devcontainer directory exists precisely because that combination is fiddly enough to want a fixed environment.

AGPL-3.0 is the licence decision, not a detail

Decidim is licensed AGPL-3.0, with the text in LICENSE-AGPLv3.txt, and that shapes who can use it and how.

The AGPL extends copyleft to network use: if you run a modified Decidim and let users interact with it over a network, you owe those users the corresponding source of your modifications. For a public institution publishing its platform, that is the intended outcome. For a company that modifies Decidim for a hosted service and lets users interact with it over a network, publishing the corresponding source makes proprietary deployment a poor fit.

The README points at a reference on starting open for governments, which tells you the licence is chosen for the sector, not for convenience.

Version history is the other cost signal. The default branch is develop, and recent tags show parallel maintenance lines: v0.32.1 released on 2026-07-30 while v0.31.7 shipped on 2026-09-03 and v0.31.6 on 2026-07-06, which is a stable line and a newer line moving at once. The last push was on 2026-10-15 and the repository is not archived, so work is continuous.

For an operator, that means an upgrade policy question rather than a technical one: CHANGELOG.md, RELEASE_NOTES.md and the migration path between lines are what you need to budget for.

Identity verification is where participation platforms get contentious

The README's module section links two separate documentation pages that most projects would merge: identity verifications and authorizations on one side, authentication options on the other. The split matters.

Authentication is how someone logs in. Authorization in Decidim is how the platform decides whether that verified identity is allowed to take a given action, which for a participation platform can mean voting, proposing, or sitting on a governing body. The authorizations documentation is a separate page from authentication options, and the modules page has its own auth section, so the extension surface here is broader than a login box.

The README links to a list of OmniAuth strategies.

This is the part of Decidim that most affects a procurement decision, because it decides whether a proposal counts and who may vote. The README itself does not describe the flows, and the documentation site is where you would read them before committing to a design that mixes open registration with verified voting.

The parallel concern is content: decidim-ai is an engine in the tree, and decidim-demographics collects participation data. Both are worth reviewing against your own policy before enabling them.

What it costs to run, and who should not choose it

Decidim is a heavy dependency and the README signals that with a Rails app per installation, roughly twenty engines, a Node toolchain, a demo site that can spin up on demand, and separate documentation for installation, customization and authoring guides.

If your need is comments and threads, a forum does it with less machinery. If your need is a survey, a survey tool does it. Decidim is worth its weight when the requirement is genuinely participatory: proposals with support thresholds, debates, assemblies, budgets where residents allocate a sum, and meetings with accountability tracking. Barcelona is the reference deployment and the reason the domain model exists.

Two practical cautions. First, pre-1.0 internal APIs: the README says outright that module APIs can change, so a custom module is maintenance you own, and it recommends extensive testing. Second, the social contract is a governance commitment, not a technical feature; teams that only want the tooling and not the participation model may find the constraints on identity, verification and moderation to be overhead.

The project is verified as a Digital Public Good, and it is funded partly through OpenCollective as members and partners, which tells you the maintenance model is institutional funding rather than commercial support. That is a strength for public bodies and a risk for anyone who needs a support contract with response times.

Editorial conclusion

Decidim suits a city, an organisation or an agency that wants a participation platform with proposals, debates, budgets and assemblies already modelled, and that can commit to Rails upgrades. It is the wrong choice if your requirement is a generic community forum, since the domain model is deliberately specific, and it is a poor fit for a closed-source product because the AGPL-3.0 licence reaches modifications you deploy. Verify first what your Ruby and Node versions are against the engine requires, and read RELEASE_NOTES.md before every upgrade, since module compatibility is version-specific and internal APIs are documented as unstable until v1.0.0.

Frequently asked questions

Official sources

1. decidim/decidim on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases