Reorganize /docs with numbered TOC; deployment rewrite for actual homelab

- /docs/ now contains 12 numbered guides + index.md (navigator). - Old duplicates removed: nexa-core/doc/, DEPLOYMENT.md, PLAN.md, config/{classification_logic,workflows_spec}.md. - 09-deployment.md targets the running infra (LXC 104 docker host, Zoraxy at 192.168.1.4, existing Memos/n8n/LiteLLM/Nextcloud/Qdrant) rather than spinning a parallel stack; minimal-config approach. - 11-open-questions.md tracks user-info-required blockers. - 12-optimization-opportunities.md captures homelab tweaks. - CLAUDE.md added so future agent runs know repo conventions and infra.
2026-05-04 21:18:28 +00:00
parent 18d2360ad9
commit 9b18e2710d
19 changed files with 618 additions and 754 deletions
@@ -0,0 +1,63 @@
+# 03 — Architecture Overview
+
+A one-page mental model. For details follow the cross-links.
+
+## Topology
+
+```
+                         ┌────────────────┐
+   voice / typing ──────▶│     Memos      │◀──── Nexa replies as comments
+                         │  (interface)   │
+                         └───────┬────────┘
+                                 │ webhook (- [ ] / #nexa:*)
+                                 ▼
+                         ┌────────────────┐
+   IMAP / RSS / NC  ────▶│      n8n       │◀──── workflows live in
+   Karakeep / Bluesky    │  (logic)       │      ./nexa-core/n8n-workflows
+                         └───┬────────┬───┘
+                  classify ▲ │        │ ▲ retrieve
+                           │ ▼        ▼ │
+                       ┌──────────┐  ┌──────────┐
+                       │  SAIA    │  │  Qdrant  │
+                       │ LiteLLM  │  │  vector  │
+                       └──────────┘  └────┬─────┘
+                                          │ optional
+                                          ▼
+                                     ┌──────────┐
+                                     │  Graph   │  (Neo4j or Ontotext —
+                                     │   DB     │   see open questions)
+                                     └──────────┘
+                                 │
+                                 ▼ writes
+                  ┌──────────────────────────────┐
+                  │  Nextcloud (Tasks, Calendar, │
+                  │  Mail, Files / Obsidian)     │
+                  └──────────────────────────────┘
+```
+
+## Components
+
+| Component | Role | Where it runs (today) |
+|-----------|------|-----------------------|
+| **Memos** | Interface, voice input, webhook source | docker host LXC 104 → `memos.nuclide.systems` |
+| **n8n** | Workflow / logic engine | docker host LXC 104 → `n8n.nuclide.systems` |
+| **SAIA / LiteLLM** | Model gateway, embeddings, classification | docker host LXC 104 → `ai.nuclide.systems` (LiteLLM internal :4000) |
+| **Qdrant** | Vector memory (semantic recall) | docker host LXC 104 (existing `qdrant_scientific` may be reused — see [11](./11-open-questions.md)) |
+| **Graph DB** | Structural memory (deferred) | not yet deployed |
+| **Nextcloud** | Tasks, calendar, mail, files | dedicated LXC 105 → `nc.nuclide.systems` |
+| **ntfy** | Push channel for system alerts | docker host → `ntfy.nuclide.systems` |
+| **Backrest** | Backup orchestration | LXC 103 |
+| **Zoraxy** | Reverse proxy + TLS | LXC 108 (`192.168.1.4:8000`) |
+| **AdGuard DNS** | Internal name resolution | LXC 102 |
+| **Home Assistant** | Voice + house automation | VM 100 (HAOS) |
+
+## Two-pillar memory
+
+- **Qdrant** answers *"what is similar / relevant?"* (cosine search over embeddings).
+- **Graph DB** answers *"who, what depends on what, how is it structured?"* (Cypher / SPARQL).
+
+Both pillars are queried in parallel for `#nexa:ask` and merged before SAIA generates the final answer. See [08 — GraphRAG architecture](./08-graphrag-architecture.md).
+
+## Dual-context routing
+
+Every input is classified `work` or `personal` before any side effect (task creation, calendar write). See [04 — Integration matrix](./04-integration-matrix.md) and [06 — Classification logic](./06-classification-logic.md).