Contributing to Rhinvoice (for developers)

For developers

This page is for people who want to change Rhinvoice or contribute to it. To use Rhinvoice you do not need any of it; start with Installation.

Rhinvoice is open source on GitHub under the AGPL. Bug reports, tax rules with their official source and pull requests are welcome. Read CONTRIBUTING.md first, and open an issue before a large change.

Where to start

• CONTRIBUTING.md: ways to help, development setup, rules for pull requests
• Contributor License Agreement: accepted by ticking its box in your first pull request; you keep the copyright of your work
• Architecture decisions in docs/adr: read the ADR of the area you change
• Adding a country: one country profile, guided by tests (overview for everyone: More countries)
• Changelog
• Questions and ideas: GitHub discussions; bugs: issues
• Security issues go through a private report, never a public issue: SECURITY.md

Tech stack

The backend is Python 3.13 with FastAPI, SQLAlchemy 2 and Alembic on PostgreSQL, in layers (api → infrastructure → application → domain) that import-linter checks. The frontend is React with TypeScript and Vite, TanStack Router and Query and Tailwind CSS, with an API client generated from the OpenAPI schema. PDFs are rendered from HTML by Gotenberg and turned into PDF/A-3b with pypdf, the Swiss QR-bill from qrbill, the EPC QR code from segno, and backups from restic in a container of its own.

Development

Requirements: Python 3.13 with uv, Node.js 22 with pnpm, Docker.

make install        # dependencies
make dev-backend    # database on :5433 + API on :8000 (auto-reload)
make dev-frontend   # Vite on :5173, proxies /api to the backend
make demo           # demo customers, articles and documents
make qa             # the full quality gate (also what CI runs)
make help           # all targets

The quality gate: make qa

Rhinvoice handles money and legal documents, so every change passes make qa, which is also what CI runs. A pull request with a red gate is not reviewed.

Area	Tools
Backend	ruff (ALL), mypy –strict, pyright strict, import-linter, pytest with 100 % line and branch coverage, hypothesis, real PostgreSQL, schemathesis, mutmut (≥ 90 %), pip-audit
Frontend	TypeScript strict, ESLint strict type-checked with jsx-a11y, dependency-cruiser, Vitest with 100 % coverage, pnpm audit
E2E	Playwright against the production image, axe-core (WCAG 2.2 AA) in every test, screenshots light/dark × desktop/mobile
E-invoices	KoSIT validator and Mustang on every sample

A few rules from CONTRIBUTING.md: money is never a float, time comes from the Clock, issued documents stay immutable, and everything in code is English.

Questions

Where is the source code of Rhinvoice?

On GitHub at github.com/rhinvoice/rhinvoice, under the GNU Affero General Public License v3.0 or later.

Do I have to sign something to contribute?

Yes. Before the first pull request is merged, you accept the Contributor License Agreement by ticking its box in the pull request. You keep the copyright of your work.

Can I add a country to Rhinvoice?

Yes. Everything that differs between countries lives in one country profile per country. The guide docs/adding-a-country.md walks through it, guided by tests. Open an issue with the official sources first.