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

35
diagrams/README.md Normal file
View File

@@ -0,0 +1,35 @@
# Diagrams
This directory contains additional architecture diagrams beyond the main C4 diagrams.
## Available Diagrams
| File | Description |
|------|-------------|
| [gpu-allocation.mmd](gpu-allocation.mmd) | GPU workload distribution |
| [data-flow-chat.mmd](data-flow-chat.mmd) | Chat request data flow |
| [data-flow-voice.mmd](data-flow-voice.mmd) | Voice request data flow |
## Rendering Diagrams
### VS Code
Install the "Markdown Preview Mermaid Support" extension.
### CLI
```bash
# Using mmdc (Mermaid CLI)
npx @mermaid-js/mermaid-cli mmdc -i diagram.mmd -o diagram.png
```
### Online
Use [Mermaid Live Editor](https://mermaid.live)
## Diagram Conventions
1. Use `.mmd` extension for Mermaid diagrams
2. Include title as comment at top of file
3. Use consistent styling classes
4. Keep diagrams focused (one concept per diagram)