The AGPL-3.0 licence
Waterfall is published under the GNU AGPL v3.0 only. You are free to use, study, modify and redistribute it. What sets the AGPL apart is the network: if you make a modified version of Waterfall available to users, for example as an online service, you must give them access to the source code of that version.
For a company that installs Waterfall for its own teams, this changes nothing in day-to-day use: the data remains its own, on its own servers.
What the repository holds
| Directory | Contents |
|---|---|
docs/spec | The specification: more than two hundred requirements, its Word and draw.io sources, its Markdown rendering, and the reviews that shaped it. |
docs/api | The interface contract in OpenAPI, the inventory of operations and the design decisions. |
docs/roadmap | The roadmap: the epics in their build order, their user stories and their design. |
docs/dev | The development guide and the coding rules for each language. |
backend/ | The business core, the API service and the background worker, in Python. |
frontend/ | The Next.js application, its client generated from the contract, its end-to-end journeys. |
fixtures/ | The worked examples from the specification, and the data served by the fake service. |
deploy/ | Packaging: Compose for development today, Helm later. |
The technical stack
Each choice is argued in the specification rather than simply asserted:
- Interface: Next.js and TypeScript, grids built on TanStack Table, charts with Apache ECharts.
- Service: FastAPI and Python, a single modular core and a background worker.
- Data: PostgreSQL as the single source of truth, Redis for caching and the task queue, S3-compatible storage for files in transit and backups.
- Identity: an identity provider shipped with the platform (Keycloak), which holds local accounts, federates an LDAP or Active Directory directory, or brokers to an external provider.
- Deployment: Helm for Kubernetes, Docker Compose for development and small installations.
The API contract is written by hand and is authoritative: the interface client is generated from it, the fake service serves its examples, and the CI chain will reject a service whose responses depart from it.
Two languages, one rule
The specification and the documentation are in French: it is a formal requirements document, and translating it would duplicate the source of truth. The contract, the code and the README are in English. Issues and pull requests are welcome in either language. The software’s interface itself is planned in French and English, at each user’s choice.
Contributing
The Contribute page presents the ways to take part, profile by profile: testing, reviewing the specification, developing. The repository’s contribution guide sets out the rules in detail. In short:
- On the specification, a contribution takes the form of a finding: a location (paragraph or requirement identifier), an exact quotation, and a proposed wording. A finding without a proposal is a finding someone else will have to rewrite.
- On the API contract, an interface change is first a change to the contract; the code follows.
- A feature proposal goes through the “Question or proposal” issue template. It only becomes a user story when it enters an epic.
- Code arrives in batches, each reviewed and checked by the CI chain before being merged.
You work on long-running projects and the way Waterfall handles revisions, contract amendments or risk provisions makes you react? Business feedback on the specification is as useful a contribution as a line of code.
Trying the mockup
The interface mockup runs on a development machine, against a fake service that serves the examples from the contract. Once you have cloned the repository and installed the prerequisites (uv, Node 24, Docker), the make dev command serves it at http://localhost:3000. It is not the product yet: the screens are there, the calculations arrive with the following epics.