---
name: project-mc2-architecture
description: "MC2 Architektur — Schichten, Key-Files, API-Endpunkte, wichtige Eigenheiten"
metadata: 
  node_type: memory
  type: project
  originSessionId: e6bf38ac-b5dc-4aaa-80c3-ad8dd078a1fe
---

## Stack-Schichten
```
Windows PC (192.168.178.98)
  └─ executor.py :7777  ← PC-Steuerung (FastAPI, manuell via start.bat)

AI Box (192.168.178.151) — Ryzen AI MAX+ 395, 122GB unified RAM
  ├─ llama-swap :8080       ← Engine (ROCm/HIP, lemonade-sdk/llamacpp-rocm)
  ├─ mission-control-2 :9001 ← MC2 (FastAPI + React, user-service)
  │    └─ /v1              ← Builtin Gateway (model:auto, OpenAI-kompatibel)
  ├─ hermes-gateway :8642   ← Hermes Agent (NousResearch, user-service)
  │    ├─ mcp_pc.py        ← MCP → executor.py auf Windows PC
  │    ├─ mcp_web.py       ← MCP → trafilatura Web-Fetch
  │    ├─ mcp_memory.py    ← MCP → SQLite Gedächtnis
  │    └─ mcp_mc.py        ← MCP → MC2 Stack-Management
  └─ hermes-webui :8787     ← nesquena hermes-webui (user-service)

Proxmox (192.168.178.108)  ← LXCs: adguard(100) npmplus(101) netbird(102) gitea(104)
```

---

## MC2 Key-Files
| Datei | Zweck |
|---|---|
| `backend/app.py` | FastAPI Einstieg, Router-Mounting |
| `backend/config.py` | Alle Env-Vars (LLAMA_SWAP_URL, HERMES_*, PC_EXECUTOR_URL, etc.) |
| `backend/services/agent.py` | `/api/agent/status` (gateway/webui/telegram/mcp/pc) |
| `backend/services/llamaswap.py` | llama-swap API, ROLE_IDS, Modell-CRUD |
| `backend/services/maintenance.py` | Updates, Logs, Restart, ROLE_MAP |
| `backend/services/sources.py` | CATEGORIES für Discover (roles: vision/coder/agent/scout) |
| `backend/gateway/gateway_proxy.py` | Builtin OpenAI-Gateway, model:auto Routing |
| `frontend/src/lib/api.ts` | TypeScript-Interfaces für alle API-Responses |
| `frontend/src/lib/queries.ts` | React-Query Hooks (useModels, useAgentStatus, etc.) |
| `mcp/mcp_pc.py` | PC-Control MCP-Server |
| `mcp/mcp_web.py` | Web-Fetch MCP-Server (trafilatura) |
| `mcp/mcp_memory.py` | Shared Memory MCP-Server |

---

## Wichtige Eigenheiten / Gotchas
- **Python 3.14 auf Box** → LiteLLM unmöglich (uvloop scheitert). MC2 hat eigenen Gateway.
- **mcp_pc.py / mcp_web.py müssen Hermes-Venv nutzen** (nicht MC2-Venv). Python 3.11 vs 3.14 TaskGroup-Kompatibilität.
- **Builtin-Gateway Port:** MC2 läuft auf `:9001`, der `/v1`-Endpunkt ist Teil von MC2 (nicht separater Dienst).
- **MC_PORT vs tatsächlicher Port:** In Env ist `MC_PORT=9000`, aber der User-Service hört auf `:9001` (Port in Unit-Definition). Beim SSH-Deploy immer `:9001` verwenden.
- **llama-swap Config braucht sudo** zum Schreiben (`/etc/llama-swap/config.yaml`), aber `hitonabi` ist in `adm`-Gruppe → journalctl ohne sudo lesbar.
- **ROLE_IDS** in llamaswap.py = `{"vision", "coder", "agent", "scout"}` (reasoning entfernt 2026-06-27).
- **Discover-CATEGORIES** in sources.py: vision / coder / agent / scout (kein reasoning mehr).
- **API_SERVER_KEY:** in `~/.hermes/.env` auf der Box

---

## /api/agent/status Felder (Stand 2026-06-27)
```python
{
  "gateway_reachable": bool,    # Hermes :8642
  "webui_reachable": bool,      # hermes-webui :8787
  "brain_model": str,           # aus ~/.hermes/config.yaml
  "has_config": bool,
  "has_skills": bool,
  "has_memories": bool,
  "telegram_enabled": bool,     # TELEGRAM_BOT_TOKEN gesetzt?
  "mcp_server_count": int,      # enabled MCP-Server in config.yaml
  "pc_executor_reachable": bool # 192.168.178.98:7777/health
}
```