Scope

These were my "slides" for the team's architecture meetup on 2026-09-17. They propose a radical cut of abstractions in the fediversity repo, namely everything considering composition of NixOS configurations. Attendees were @kiara, @toonn, @patricia and @kerstin.

Please note that the directory structure is only there to symbolise code ownership, plugging this together in an actual setup would probably look very different.

Motivation

The current state of things is a collection of abstractions over regular NixOS modules that has grown bigger than the size of the Nixpkgs lib attribute (currently 43k LOC). For reference, the entire module system is only a small part of Nixpkgs lib. I think that this scale of abstractions will create mostly two problems;

Risk of adoption by hosting providers

Organisations like hosting providers will be very careful to base their business model on software like fediversity.

• They risk losing their customers when availability is not as promised

• They risk security incidents, potentially involving legal consequences

• They risk losing their reputation for other services they offer, if they can't measure up to expectations

• Also on the other hand we can't offer any legal liability for the software, something that would make it easier for the hosting provider to accept complexity.

Making hosting providers accept NixOS is already a huge leap for them. And NixOS is an organisation that exists for 20 years, is used by tens of thousands of people and is maintained by thousands.

Making them accept a similar size of abstractions on top of NixOS that is maintained by such a small team would be a risk orders of magnitude bigger than adopting NixOS.

Onboarding of new developers to the team is difficult

Team growth will be difficult, as engaging with these systems to the point of new engineers being able to contribute and maintain will take considerable time and energy. Personally It took me 5 months to aquire a conceptual understanding, and I'm still far from being able to explain, let alone improve on these interfaces.

Idea

One application per container, default is to just run everything in the same container, hosting provider can adjust.

All the composition just happens inside NixOS modules, removing the need for contracts, resources, components, setups, groups.

We focus instead on testing infrastructure for our modules, the deployment framework, docs for hosting providers, a graphical user interface for operators.

├── fediversity
│   ├── generic-node.nix
│   └── mastodon.nix
├── hosting-provider
│   ├── container-info.nix
│   ├── generic-node.nix
│   └── mastodon.nix
└── operator
    └── mastodon.nix

Potential difficulties

The proposal tries to keep containers self-contained by default. While not explicitly disallowed, horizontal information flow of Nix configuration between containers is not specified by the proposal. This would need to be solved in case that being a hard requirement.