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:
2026-02-01 14:30:05 -05:00
parent 4d4f6f464c
commit 832cda34bd
26 changed files with 3805 additions and 2 deletions

69
CONTEXT-DIAGRAM.mmd Normal file
View File

@@ -0,0 +1,69 @@
%% C4 Context Diagram - Level 1
%% DaviesTechLabs Homelab System Context
%%
%% To render: Use Mermaid Live Editor or VS Code Mermaid extension
graph TB
subgraph users["External Users"]
dev["👤 Developer<br/>(Billy)"]
family["👥 Family Members"]
agents["🤖 AI Agents"]
end
subgraph external["External Systems"]
cf["☁️ Cloudflare<br/>DNS + Tunnel"]
gh["🐙 GitHub<br/>Source Code"]
ghcr["📦 GHCR<br/>Container Registry"]
hf["🤗 Hugging Face<br/>Model Registry"]
end
subgraph homelab["🏠 DaviesTechLabs Homelab"]
direction TB
subgraph apps["Application Layer"]
companions["💬 Companions<br/>AI Chat"]
voice["🎤 Voice Assistant"]
media["🎬 Media Services<br/>(Jellyfin, *arr)"]
productivity["📝 Productivity<br/>(Nextcloud, Gitea)"]
end
subgraph platform["Platform Layer"]
k8s["☸️ Kubernetes Cluster<br/>Talos Linux"]
end
subgraph ai["AI/ML Layer"]
inference["🧠 Inference Services<br/>(vLLM, Whisper, XTTS)"]
workflows["⚙️ Workflow Engines<br/>(Kubeflow, Argo)"]
vectordb["📚 Vector Store<br/>(Milvus)"]
end
end
%% User interactions
dev --> |manages| productivity
dev --> |develops| k8s
family --> |uses| media
family --> |chats| companions
agents --> |queries| inference
%% External integrations
cf --> |routes traffic| apps
gh --> |GitOps sync| k8s
ghcr --> |pulls images| k8s
hf --> |downloads models| inference
%% Internal relationships
apps --> platform
ai --> platform
companions --> inference
voice --> inference
workflows --> inference
inference --> vectordb
%% Styling
classDef external fill:#f9f,stroke:#333,stroke-width:2px
classDef homelab fill:#bbf,stroke:#333,stroke-width:2px
classDef user fill:#bfb,stroke:#333,stroke-width:2px
class cf,gh,ghcr,hf external
class companions,voice,media,productivity,k8s,inference,workflows,vectordb homelab
class dev,family,agents user