feat: add comprehensive architecture documentation
- Add AGENT-ONBOARDING.md for AI agents - Add ARCHITECTURE.md with full system overview - Add TECH-STACK.md with complete technology inventory - Add DOMAIN-MODEL.md with entities and bounded contexts - Add CODING-CONVENTIONS.md with patterns and practices - Add GLOSSARY.md with terminology reference - Add C4 diagrams (Context and Container levels) - Add 10 ADRs documenting key decisions: - Talos Linux, NATS, MessagePack, Multi-GPU strategy - GitOps with Flux, KServe, Milvus, Dual workflow engines - Envoy Gateway - Add specs directory with JetStream configuration - Add diagrams for GPU allocation and data flows Based on analysis of homelab-k8s2 and llm-workflows repositories and kubectl cluster-info dump data.
This commit is contained in:
242
GLOSSARY.md
Normal file
242
GLOSSARY.md
Normal file
@@ -0,0 +1,242 @@
|
||||
# 📖 Glossary
|
||||
|
||||
> **Terminology and abbreviations used in the DaviesTechLabs homelab**
|
||||
|
||||
## A
|
||||
|
||||
**ADR (Architecture Decision Record)**
|
||||
: A document that captures an important architectural decision, including context, decision, and consequences.
|
||||
|
||||
**Argo Events**
|
||||
: Event-driven automation for Kubernetes that triggers workflows based on events from various sources.
|
||||
|
||||
**Argo Workflows**
|
||||
: A container-native workflow engine for orchestrating parallel jobs on Kubernetes.
|
||||
|
||||
**Authentik**
|
||||
: Self-hosted identity provider supporting SAML, OIDC, and other protocols.
|
||||
|
||||
## B
|
||||
|
||||
**BGE (BAAI General Embedding)**
|
||||
: A family of embedding models from BAAI used for semantic search and RAG.
|
||||
|
||||
**Bounded Context**
|
||||
: A DDD concept defining a boundary within which a particular domain model applies.
|
||||
|
||||
## C
|
||||
|
||||
**C4 Model**
|
||||
: A hierarchical approach to software architecture diagrams: Context, Container, Component, Code.
|
||||
|
||||
**Cilium**
|
||||
: eBPF-based networking, security, and observability for Kubernetes.
|
||||
|
||||
**CloudNative-PG**
|
||||
: Kubernetes operator for PostgreSQL databases.
|
||||
|
||||
**CNI (Container Network Interface)**
|
||||
: Standard for configuring network interfaces in Linux containers.
|
||||
|
||||
## D
|
||||
|
||||
**DDD (Domain-Driven Design)**
|
||||
: Software design approach focusing on the core domain and domain logic.
|
||||
|
||||
## E
|
||||
|
||||
**Embedding**
|
||||
: A vector representation of text, used for semantic similarity and search.
|
||||
|
||||
**Envoy Gateway**
|
||||
: Kubernetes Gateway API implementation using Envoy proxy.
|
||||
|
||||
**External Secrets Operator (ESO)**
|
||||
: Kubernetes operator that syncs secrets from external stores (Vault, etc.).
|
||||
|
||||
## F
|
||||
|
||||
**Falco**
|
||||
: Runtime security tool that detects anomalous activity in containers.
|
||||
|
||||
**Flux CD**
|
||||
: GitOps toolkit for Kubernetes, continuously reconciling cluster state with Git.
|
||||
|
||||
## G
|
||||
|
||||
**GitOps**
|
||||
: Operational practice using Git as the single source of truth for declarative infrastructure.
|
||||
|
||||
**GPU Device Plugin**
|
||||
: Kubernetes plugin that exposes GPU resources to containers.
|
||||
|
||||
## H
|
||||
|
||||
**HelmRelease**
|
||||
: Flux CRD for managing Helm chart releases declaratively.
|
||||
|
||||
**HTTPRoute**
|
||||
: Kubernetes Gateway API resource for HTTP routing rules.
|
||||
|
||||
## I
|
||||
|
||||
**InferenceService**
|
||||
: KServe CRD for deploying ML models with autoscaling and traffic management.
|
||||
|
||||
## J
|
||||
|
||||
**JetStream**
|
||||
: NATS persistence layer providing streaming, key-value, and object stores.
|
||||
|
||||
## K
|
||||
|
||||
**KServe**
|
||||
: Kubernetes-native platform for deploying and serving ML models.
|
||||
|
||||
**Kubeflow**
|
||||
: ML toolkit for Kubernetes, including pipelines, training operators, and more.
|
||||
|
||||
**Kustomization**
|
||||
: Flux CRD for applying Kustomize overlays from Git sources.
|
||||
|
||||
## L
|
||||
|
||||
**LLM (Large Language Model)**
|
||||
: AI model trained on vast text data, capable of generating human-like text.
|
||||
|
||||
**Longhorn**
|
||||
: Cloud-native distributed storage for Kubernetes.
|
||||
|
||||
## M
|
||||
|
||||
**MessagePack (msgpack)**
|
||||
: Binary serialization format, more compact than JSON.
|
||||
|
||||
**Milvus**
|
||||
: Open-source vector database for similarity search and AI applications.
|
||||
|
||||
**MLflow**
|
||||
: Platform for managing the ML lifecycle: experiments, models, deployment.
|
||||
|
||||
**MinIO**
|
||||
: S3-compatible object storage.
|
||||
|
||||
## N
|
||||
|
||||
**NATS**
|
||||
: Cloud-native messaging system for microservices, IoT, and serverless.
|
||||
|
||||
**Node Feature Discovery (NFD)**
|
||||
: Kubernetes add-on for detecting hardware features on nodes.
|
||||
|
||||
## P
|
||||
|
||||
**Pipeline**
|
||||
: In ML context, a DAG of components that process data and train/serve models.
|
||||
|
||||
**Premium User**
|
||||
: User tier with enhanced features (more RAG docs, priority routing).
|
||||
|
||||
## R
|
||||
|
||||
**RAG (Retrieval-Augmented Generation)**
|
||||
: AI technique combining document retrieval with LLM generation for grounded responses.
|
||||
|
||||
**Reranker**
|
||||
: Model that rescores retrieved documents based on relevance to a query.
|
||||
|
||||
**ROCm**
|
||||
: AMD's open-source GPU computing platform (alternative to CUDA).
|
||||
|
||||
## S
|
||||
|
||||
**Schematic**
|
||||
: Talos Linux concept for defining system extensions and configurations.
|
||||
|
||||
**SOPS (Secrets OPerationS)**
|
||||
: Tool for encrypting secrets in Git repositories.
|
||||
|
||||
**STT (Speech-to-Text)**
|
||||
: Converting spoken audio to text (e.g., Whisper).
|
||||
|
||||
**Strix Halo**
|
||||
: AMD's unified memory architecture for APUs with large GPU memory.
|
||||
|
||||
## T
|
||||
|
||||
**Talos Linux**
|
||||
: Minimal, immutable Linux distribution designed specifically for Kubernetes.
|
||||
|
||||
**TTS (Text-to-Speech)**
|
||||
: Converting text to spoken audio (e.g., XTTS/Coqui).
|
||||
|
||||
## V
|
||||
|
||||
**Valkey**
|
||||
: Redis-compatible in-memory data store (Redis fork).
|
||||
|
||||
**vLLM**
|
||||
: High-throughput LLM serving engine with PagedAttention.
|
||||
|
||||
**VIP (Virtual IP)**
|
||||
: IP address shared among multiple hosts for high availability.
|
||||
|
||||
**Volcano**
|
||||
: Kubernetes batch scheduler for high-performance workloads (ML, HPC).
|
||||
|
||||
**VRM**
|
||||
: File format for 3D humanoid avatars.
|
||||
|
||||
## W
|
||||
|
||||
**Whisper**
|
||||
: OpenAI's speech recognition model.
|
||||
|
||||
## X
|
||||
|
||||
**XTTS**
|
||||
: Coqui's multi-language text-to-speech model with voice cloning.
|
||||
|
||||
---
|
||||
|
||||
## Acronyms Quick Reference
|
||||
|
||||
| Acronym | Full Form |
|
||||
|---------|-----------|
|
||||
| ADR | Architecture Decision Record |
|
||||
| API | Application Programming Interface |
|
||||
| BGE | BAAI General Embedding |
|
||||
| CI/CD | Continuous Integration/Continuous Deployment |
|
||||
| CRD | Custom Resource Definition |
|
||||
| DAG | Directed Acyclic Graph |
|
||||
| DDD | Domain-Driven Design |
|
||||
| ESO | External Secrets Operator |
|
||||
| GPU | Graphics Processing Unit |
|
||||
| HA | High Availability |
|
||||
| HPA | Horizontal Pod Autoscaler |
|
||||
| LLM | Large Language Model |
|
||||
| ML | Machine Learning |
|
||||
| NATS | (not an acronym, named after message passing in Erlang) |
|
||||
| NFD | Node Feature Discovery |
|
||||
| OIDC | OpenID Connect |
|
||||
| RAG | Retrieval-Augmented Generation |
|
||||
| RBAC | Role-Based Access Control |
|
||||
| ROCm | Radeon Open Compute |
|
||||
| S3 | Simple Storage Service |
|
||||
| SAML | Security Assertion Markup Language |
|
||||
| SOPS | Secrets OPerationS |
|
||||
| SSO | Single Sign-On |
|
||||
| STT | Speech-to-Text |
|
||||
| TLS | Transport Layer Security |
|
||||
| TTS | Text-to-Speech |
|
||||
| UUID | Universally Unique Identifier |
|
||||
| VIP | Virtual IP |
|
||||
| VRAM | Video Random Access Memory |
|
||||
|
||||
---
|
||||
|
||||
## Related Documents
|
||||
|
||||
- [ARCHITECTURE.md](ARCHITECTURE.md) - System overview
|
||||
- [TECH-STACK.md](TECH-STACK.md) - Technology details
|
||||
- [DOMAIN-MODEL.md](DOMAIN-MODEL.md) - Entity definitions
|
||||
Reference in New Issue
Block a user