---
title: Architecture
area: infrastructure
tags: [infrastructure, homelab, assistant, integrations, automation, diagrams]
created: 2026-03-18
updated: 2026-04-16
status: active
related: [[Infrastructure/Services/Docker Services]], [[Infrastructure/Automation/Cron Jobs]], [[Infrastructure/Automation/n8n Workflows]]
---

# Architecture

High-level map of Will's homelab + assistant stack. For operational details (IPs, credential paths, commands), see TOOLS.md in the assistant workspace.

Operational note: the shared Obsidian vault lives on a `virtiofs` mount and is touched by both the host Obsidian user (`claw`) and the VM assistant user (`openclaw`); collaborative note folders need write permissions that work for both sides.

See sub-notes for details:
- [[Infrastructure/Services/Docker Services]]
- [[Infrastructure/Automation/Cron Jobs]]
- [[Infrastructure/Automation/n8n Workflows]]

## Current deployment

- The assistant currently runs in a VM on Will's laptop.
- Planned later move: main host.
- Shared note workspace lives in `will/will-shared-zap/` inside the Obsidian vault tree.

## Networking

- **Primary host LAN IP:** `192.168.153.130`
- **Secondary host LAN IP:** `192.168.153.140` (stale/unreachable from VM as of 2026-04-15)
- **Previous host LAN IPs:** `192.168.153.113`, `192.168.153.117`
- **Tailscale IP:** `100.123.88.127`
- **Separate MinIO endpoint:** `192.168.153.253:9000`

## Diagram set

Primary diagram:
- [[Infrastructure/Architecture - Master.canvas|Architecture - Master]]

Supporting views:
- [[Infrastructure/Architecture - Overview.canvas|Architecture - Overview]]
- [[Infrastructure/Architecture - Service Topology.canvas|Architecture - Service Topology]]
- [[Infrastructure/Architecture - Automation Flow.canvas|Architecture - Automation Flow]]

Recommended reading order:
1. Master for the whole system
2. Overview for a lighter top-level pass
3. Service Topology for runtime and dependencies
4. Automation Flow for messaging, memory, backups, and orchestration

Why Canvas: it gives much better layout control in Obsidian than Mermaid for this kind of infra map, and it avoids the clipping/rendering issues we kept hitting.
## Core service layers

### Memory / search
- **Memory index:** Ollama `nomic-embed-text` via sqlite-vec, hybrid BM25 + vector retrieval
- **Index sources:** workspace `memory/`, session transcripts, `will/will-shared-zap/` vault

### Search / retrieval
- **SearXNG** on `18803` for local-first search
- **Brave MCP** on `18802` for fallback / second opinion
- **Ollama embeddings** on `18807` for memory search

### Automation / orchestration
- **OpenClaw runtime:** main assistant in a VM
- **Current main interactive session model:** `gpt-5.4`
- **Local LLM runtime:** llama.cpp on `18806` serving `gemma-3-12b-it-q4_0.gguf`
- **n8n-agent:** `18808` for scheduled/API-native workflows

### Speech / media
- **Whisper server:** `18801`
- **Kokoro TTS:** `18805`

## Storage / repos

### MinIO
- Bucket: `zap`
- Purpose: full `~/.openclaw` backups every 6 hours
- Accessed at `192.168.153.253:9000`

### Gitea
- Repo host: `gitea-http.taildb3494.ts.net`
- Repo: `will/swarm-zap.git`
- Purpose: workspace backup / review / sync point

## Kubernetes

- Small Raspberry Pi cluster
- Shared namespace: `swarm`
- Keep workloads lightweight and scoped

## Key integrations

- **Telegram:** primary interrupt / reminder / mobile channel
- **Discord:** deeper technical work and scoped threads
- **Obsidian:** shared vault `will/will-shared-zap/` under `/mnt/swarm-common/obsidian-vault/`
- **Google Workspace:** Gmail / Calendar / Drive / Tasks via `gog`

## Operating decisions worth keeping

- Search: SearXNG first, then Brave-backed fallback only when needed
- n8n vs cron: use n8n when it has the right native node or API path, keep shell-heavy local tasks in OpenClaw or OS cron
- Shared vault is human-readable layer; workspace memory remains source of truth

## OpenClaw local model provider migration
- Date: 2026-04-15
- Local llama.cpp Gemma model is now exposed as `local/gemma-3-12b-local`
- Previous namespace was `litellm/gemma-3-12b-local`
- Migration required two config changes in `~/.openclaw/openclaw.json`:
  - move the model from `models.providers.litellm.models` to a dedicated `models.providers.local` pointing at `http://192.168.153.130:18806/v1`
  - update stale explicit model ref in `agents.defaults.models` from `litellm/gemma-3-12b-local` to `local/gemma-3-12b-local`
- Lesson: changing provider blocks alone may not change the live model catalog or Control UI if old `provider/model` refs remain in defaults/fallback maps
- Verify with: `openclaw models list | grep -i -E "gemma|local/"`
