Project / Architecture
The map shows the big parts. Architecture shows how they work together.
This page does not try to republish all of ARCHITECTURE.md. It takes two structures the canonical document declares explicitly — the four layers and the system-change pipeline — and makes the flow readable without inventing future interfaces.
Four canonical layers
The architecture is layered to preserve clear boundaries.
The titles below are extracted directly from ARCHITECTURE.md. The short copy beside them only explains each layer’s public role; it does not create a new technical contract.
Four canonical layers
- 1
Layer 1
Distribution foundation
Distribution base and boundaries that exist before graphical experiences.
- 2
Layer 2
Felunyx platform
State, policy, and services shared across interfaces and profiles.
- 3
Layer 3
Desktop experiences
Official graphical experiences that consume the same platform.
- 4
Layer 4
Delivery and recovery infrastructure
Installation, updates, recovery, and the path that carries system changes with evidence.
System change
A destructive action does not jump straight to “execute”.
The canonical pipeline has eleven ordered steps. It starts by normalizing the request, moves through resolution, risk, proposal, and confirmation, then ends by verifying and recording the result.
- Step 1
normalize the request
- Step 2
resolve source candidates
- Step 3
calculate dependencies and conflicts
- Step 4
classify risk
- Step 5
decide snapshot scope
- Step 6
present an exact proposal
- Step 7
request confirmation
- Step 8
execute source-specific stages in a controlled order
- Step 9
verify results
- Step 10
record action history
- Step 11
set reboot-pending state when required
This flow explains high-level policy. Service names, D-Bus interfaces, crates, and internal storage belong to the phase specifications that actually approve them — not to this page.