Files

T

Claude 9b18e2710d 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

3.7 KiB

Raw Blame History

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)
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.

Dual-context routing

Every input is classified work or personal before any side effect (task creation, calendar write). See 04 — Integration matrix and 06 — Classification logic.

3.7 KiB Raw Blame History