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.