kevinveenbirkenbachandClaude Opus 5
d8caa45420
Sphinx prefers nothing: dir/index and dir/README are two independent documents. The preference lives wherever something maps a folder onto a page, and this repository had two such places disagreeing. local.file_headings has always hidden README.md from a directory carrying an index.rst, while yesterday's resolver saw README only, so a link led to the page the sidebar hides. Both now try index.rst, index.md, README.md, README.rst in that order. The extension is renamed accordingly, and the tuple lives once in the lint package rather than a third time. That also repairs two links this branch degraded: roles/ holds an index.rst and no README, so a README-only rule reported every reference to it as broken and they were turned into code spans. Three links stay code spans on purpose. Their text names something the target is not - a suite, a file - so resolving them would restore a misleading reference rather than a working one. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
7.0 KiB
Repository Architecture 🏗️
This page explains how Infinito.Nexus is put together so contributors know where a change belongs and why the repository is shaped the way it is.
The short version:
- Git is the control plane.
- Ansible decides what should exist.
- Docker Compose runs the service layer.
- Bundles assemble roles into real deployments.
- Make targets expose stable, human-facing commands.
- Docs keep humans and AI agents aligned.
What This Repository Actually Is 🤔
Infinito.Nexus is not one application. It is a repository of building blocks for deploying, operating, and maintaining self-hosted systems.
The architecture is built around one simple idea: keep the parts small, explicit, and reusable, then combine them into a full stack only when a bundle needs them.
The Building Blocks 🧱
Roles 📦
Roles are the smallest meaningful unit.
A role usually owns one capability:
sys-*for host setup, OS tuning, cleanup, certificates, and maintenancesvc-*for shared services such as databases, proxies, mail, DNS, VPN, backups, and identity supportweb-app-*for end-user applicationsdev-*for development toolingdsk-*for workstation setupweb-svc-*andweb-opt-*for web-facing helpers and redirects
For example, web-app-nextcloud owns the Nextcloud deployment, sys-svc-webserver-https owns the HTTPS plumbing, and sys-ctl-cln-docker handles Docker cleanup.
A role MUST be able to answer four questions clearly:
- What does it install or configure?
- What is optional?
- What does it depend on?
- How is it turned off?
If a role cannot answer those questions, it is probably doing too much.
Bundles and Inventories 🗂️
Bundles are the assembly layer.
inventories/bundles/servers/ describes concrete deployment shapes such as a personal server, a community hub, or a sovereign cloud setup. They decide which roles are active together and which ones stay out.
For example, the repository already has server bundles such as community-hub, personal-nexus, and sovereign-cloud. Each one combines the same building blocks in a different way for a different operating model.
That means the bundle is not where logic lives. It is where the architecture becomes a real deployment.
Runtime ⚙️
Most application roles use Docker Compose for the running services.
That separation matters:
- Ansible prepares the host and renders the desired state.
- Compose starts the application containers.
- The role keeps the app-specific wiring close to the app.
- The host stays responsible for host-level concerns.
That is why you will find host work in sys-* roles and app work in web-app-* roles instead of one giant deployment script.
Entry Points 🚪
People and CI MUST interact with the repo through stable commands, not through improvised command sequences.
The main entry points are:
Those layers keep local development, CI, and production behavior closer together.
Why The Architecture Looks Like This 🤔
Composition Over Monolith 🔧
The repository prefers many focused parts over one giant playbook.
Why:
- smaller diffs
- easier reviews
- safer rollbacks
- more reuse across bundles
- less accidental coupling
Integration Over Forced Migration 🔗
This platform tries to connect existing services instead of demanding a full rewrite.
That is why the repo has:
- proxy roles
- IAM roles
- backup and cleanup roles
- DNS and TLS helpers
- encryption support
- application-specific glue code
The idea is to fit into existing environments instead of replacing everything at once.
Security By Default 🔒
Security is not a separate project here; it is part of normal composition.
The common pieces are:
- TLS through reverse proxy roles
- centralized identity through LDAP and SSO roles
- secrets through Ansible Vault
- VPN and network exposure controls
- optional full-disk encryption via hetzner-arch-luks
The point is to make the safe path the natural path.
Low-Resource Awareness 💡
A good architecture is still usable on smaller machines.
That is why the repo favors:
- enabling only the services you need
- testing one role at a time when possible
- cleanup roles for Docker, disks, and caches
- docs that explain how to scale down the stack
This is not an afterthought. It is part of the design.
Reversible Changes ↩️
Architectures age well when they make it obvious what can be enabled, disabled, or replaced.
If a service can be removed without rewriting the whole stack, the design is usually healthy. If removing one part breaks everything else, the boundaries are probably too weak.
Concrete Examples 💡
Adding A New Application ➕
A new app MUST:
- create a
web-app-*role - define its templates and defaults
- identify shared dependencies such as database, proxy, or identity
- add it to the relevant bundle
- document how to deploy, operate, and troubleshoot it
Introducing A Shared Service 🔧
A new shared service MUST:
- create the role
- keep host setup separate from consumer setup
- expose only the configuration the dependent roles need
- document the service contract and lifecycle
See base.md for the full service registration, loading, and injection model.
Changing An Existing Deployment ✏️
For a normal change, contributors MUST:
- update the role first
- update the bundle only if composition changes
- update docs if the operator workflow changes
- update tests if the contract changes
If you skip those steps, the repository becomes harder to understand for the next person.
See workflow.md for the full contribution flow.
What This Architecture Is Not 🚫
- not a single monolithic application
- not a place where one role owns every concern
- not a hidden "just run this shell script" system
- not a repo where docs can drift away from behavior
- not a one-size-fits-all production template
How To Navigate The Repo 🗺️
If you are trying to understand a change, start here:
- roles/ for behavior
- inventories/bundles/ for deployment shapes
- Makefile and scripts/ for supported commands
- lint.md for code and framework rules
- base.md for service registration, loading, and injection
- testing.md for refactoring, debugging, and testing
- docs/contributing/ for workflow and constraints
- tests/ for the expected contracts
If you can explain a change across those areas, you probably understand the architecture.
The Core Idea 💡
Infinito.Nexus works best when the pieces stay small, the boundaries stay explicit, and the docs stay honest.