NotAShelf/circus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: update API routes; minor wording fixes

Browse source 
Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: I8baf9c2c307b96a5668e19fb11d5e83b6a6a6964
This commit is contained in:
raf 2026-02-05 22:14:15 +03:00
commit ea94adb6d1
Signed by: NotAShelf
GPG key ID: 29D95B64378DB4BF
2 changed files with 128 additions and 72 deletions
Download patch file Download diff file Expand all files Collapse all files

30
docs/DESIGN.md
View file

@ -31,32 +31,18 @@ In Hydra:
Hydra pulls changes from version control, re-evaluates Nix expressions, and
triggers builds when inputs change.
---
FC _more or less_ commits to this design, with minimal tweaks for modernity and
UX. Most critically, FC is not designed to be used alongside Nixpkgs. Indeed,
you _could_ do it and I am more than willing to try and support this use case
but it is far from the main goal. The primary purpose of FC is to be a
distributed, declarative CI that **has learned from Hydra's mistakes**.
FC commits to this design with minimal tweaks. Most critically, FC is not
designed to be used alongside Nixpkgs. Sure you can do it, but that is not the
main goal. The main goal is a distributed, declarative CI that has learned from
Hydra's mistakes.
## On Hydra
### Component Interactions and Data Flow
Hydra follows a tightly-coupled architecture with three main daemons:
```ascii
Git Repository -> Evaluator -> Database -> Queue Runner -> Build Hosts -> Results -> Database -> Web UI
```plaintext
Git Repository -> Evaluator -> Database -> Queue Runner -> Build Hosts -> Results -> Database - Web UI
```
In this flow, the responsible components are as follows:
1. **hydra-server** (Perl, Catalyst): Web interface and REST API
2. **hydra-evaluator**: Polls Git repos, evaluates Nix expressions, creates
`.drv` files
3. **hydra-queue-runner**: Dispatches builds to available builders via SSH/Nix
remote
4. **Database (PostgreSQL)**: Central state management for all components
While simple on paper, this design leads to several issues. Besides the single
point of failure (the database), the tight coupling leads to requiring shared
database state and contributes to the lack of horizontal scaling in Hydra. Also
worth nothing that the evaluator must complete before the queue runner can
dispatch, the dependencies are synchronous.