Architecture
Nyxever is structured as a layered platform. Each layer is independently deployable,
documented, and replaceable. The architecture reflects a deliberate philosophy:
complexity that can't be explained is complexity that can't be trusted.
It is a designed system with explicit dependencies between layers, documented reasoning
behind every technology choice, and configuration that can be explained from first
principles. Every component can be traced from its purpose down to its implementation.
Nyxever is also explicitly a learning platform. The architecture is designed to be
understandable by anyone willing to read the documentation and follow the reasoning,
and that learning is shared openly.
⚠ Full platform architecture document in progress.
Design Principles
These principles guide every design decision in Nyxever. When they conflict, the ordering
below is the tiebreaker.
Understandability first
A configuration that works but cannot be explained is a liability. Every non-obvious
choice must be documented. If a parameter exists in a config file, there is a reason —
and that reason belongs in the docs, not in someone's head.
Right tool, documented reason
Tools are chosen on fit, operability, cost and risk. Open source is preferred where it
is a real equivalent. Every component, open source or not, has an Architecture Decision
Record explaining why it was chosen and a documented exit path for replacing it.
No hidden complexity
Abstractions are acceptable when they reduce genuine cognitive load. Abstractions that
hide behavior, obscure errors, or make debugging harder are rejected. The platform
should feel thin, not magic.
Deliberate technology choices
Technologies are chosen because they solve the problem at hand. Every major technology
choice has an Architecture Decision Record explaining the alternatives considered and
the reasoning. Choices still under evaluation are marked as open until decided.
Correctness over convenience
Correctness and security take priority over ease of use. Production certificates come
from a managed PKI, secrets are stored encrypted with audited access, and firewall
rules allow only the traffic a service needs.
⚠ Extended principles documentation in progress.
Layer Model
Nyxever is organized into six operational layers. Each layer depends on the layers
below it and provides services to the layers above. The ordering reflects the actual dependency graph of a working infrastructure stack.
01 — Compute
Proxmox VE (KVM/QEMU virtual machines and LXC containers, clustered with Corosync)
and Kubernetes for container orchestration. The foundation everything else runs on.
Provides isolated execution environments with CPU, memory, and storage allocation.
02 — Networking
Traffic segmentation, encrypted tunnels, and service-to-service authentication.
Depends on compute for the nodes that run network services. Provides the secure
communication fabric for all other layers.
03 — Storage
Distributed block, file, object, and local storage on Ceph and ZFS. Depends on compute
(for Ceph OSDs and metadata servers) and networking (for replication traffic). Provides durable,
distributed data persistence.
04 — Identity
PKI, secrets management, and authentication. Depends on compute, networking, and
storage. Provides the trust infrastructure that all services use to authenticate
each other and protect credentials.
05 — Human + AI
AI inference (local or hosted, decided per use case) and human-in-the-loop workflows. Depends on compute
(especially GPU resources), networking, storage, and identity. Provides AI
capabilities within the security boundary.
06 — Observability
Metrics, logs, and alerting. Depends on all other layers — it monitors them.
Provides the visibility needed to operate the platform reliably and diagnose
failures quickly.
⚠ Layer interaction diagrams and detailed dependency documentation in progress.
Architecture Decisions
Significant technology choices in Nyxever are documented as Architecture Decision
Records (ADRs). An ADR captures the context of a decision, the options that were
considered, the rationale for the choice made, and the consequences — including
tradeoffs and what was accepted as a result.
ADRs are durable documentation that survives personnel changes, rewrites, and time. A decision that looks arbitrary six months later often
has an ADR that explains why it was the right call at the time — or why circumstances
have changed and the decision should be revisited.
Reading ADRs before contributing
Before proposing significant changes to any layer, read the relevant ADRs. Understanding
what was decided and why makes your proposal stronger and the review faster. A PR that
re-litigates a closed decision without new information is unlikely to merge.
⚠ ADR index and full decision records available in the source repository.