first version of the knowledge base :)

00 - About/design-principles.md

@@ -0,0 +1,65 @@
+---
+title: Design Principles
+description: Architectural and operational design principles used to shape Den Vault content and the systems it describes
+tags:
+  - about
+  - design
+  - architecture
+category: about
+created: 2026-03-14
+updated: 2026-03-14
+---
+
+# Design Principles
+
+## Summary
+
+Den Vault favors design principles that make systems easier to understand, operate, and recover. These principles apply to both the infrastructure being documented and the way documentation itself is structured.
+
+## Why it matters
+
+Without stable design principles, infrastructure turns into a collection of local optimizations that are difficult to audit and harder to maintain. Shared principles make it easier to evaluate tools, architecture choices, and documentation quality consistently.
+
+## Core concepts
+
+- Systems should be understandable by inspection
+- Keep it durable: back up, migrate, repair, and replace
+- Leave room for care in interfaces, naming, and operational ergonomics
+- Stay practical when choosing tradeoffs and tooling
+- Clear trust boundaries
+- Minimal exposed surface area
+- Declarative configuration where possible
+- Explicit ownership of data, identity, and ingress paths
+- Observability and recovery designed in from the start
+
+## Practical usage
+
+These principles usually lead to patterns such as:
+
+- Private administrative access through VPN or dedicated management networks
+- Reverse proxies and DNS as shared platform services
+- Container and VM workloads with documented persistence boundaries
+- Backup and restore strategy treated as a design requirement
+- Low-dependency site and service architecture when that improves long-term maintainability
+
+## Best practices
+
+- Prefer one clear pattern over multiple overlapping ones
+- Keep the path of a request or dependency easy to trace
+- Design around failure domains, not only nominal behavior
+- Make operational boundaries visible in diagrams, inventory, and docs
+- Treat usability and readability as part of technical quality
+
+## Pitfalls
+
+- Mixing management, storage, and user traffic without a reasoned boundary
+- Depending on defaults without documenting them
+- Building fragile chains of dependencies for simple services
+- Adding security controls that cannot be operated consistently
+- Making systems colder, more complex, or more abstract than the problem requires
+
+## References
+
+- [The Twelve-Factor App](https://12factor.net/)
+- [NGINX: Reverse Proxy](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/)
+- [Prometheus overview](https://prometheus.io/docs/introduction/overview/)