Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
Nyansa is a self-hosted AI "second brain" system designed to run on private infrastructure. It integrates local Large Language Models (LLMs), a vector database, and a workflow engine to process and query an Obsidian vault. The system prioritizes data privacy and local execution, ensuring that notes, models, and processed data remain under user control.
The core architecture utilizes Docker Compose to manage a stack of specialized services connected via an internal network. The primary entry points for users are Open WebUI for chat and n8n for workflow orchestration. A custom TypeScript service, memory-api, handles Retrieval-Augmented Generation (RAG) by indexing vault content into semantic vectors.
Sources: README.md:9-15, README.md:21-25
System Components
Nyansa consists of several interconnected services that handle specific roles within the stack.
| Component | Role | Technology |
|---|---|---|
| Open WebUI | User chat interface for interacting with LLMs. | Docker Image |
| n8n | Workflow orchestration and AI agent logic. | Node.js / Docker |
| memory-api | RAG service for vault ingestion and semantic search. | TypeScript / Node.js 24 |
| Ollama | Local LLM and embedding inference engine. | C++ / Docker |
| Qdrant | Vector database for storing note chunks and metadata. | Rust / Docker |
| PostgreSQL | Persistent state storage for n8n. | SQL Database |
| Caddy | Reverse proxy and HTTPS provider (Public or Tailscale). | Go / Docker |
Sources: README.md:68-81, services/memory-api/package.json:7-10
Service Interaction Flow
The following diagram illustrates how external requests and internal data flows move between the primary components.
The system isolates internal services from direct internet access. Only Caddy is reachable externally. Internal services like PostgreSQL, Qdrant, Ollama, and memory-api publish no ports to the host.
Sources: README.md:43-66, README.md:89-91
RAG Pipeline (memory-api)
The memory-api service implements the RAG pipeline. It transforms raw Markdown files from the Obsidian vault into searchable vector embeddings.
Ingestion Logic
The Ingestor class coordinates the transformation process. It follows an incremental logic where only modified notes are re-embedded, identified by a SHA-256 hash of the raw file.
- Scanning: The service lists all
.mdfiles in the configuredVAULT_PATH. - Parsing:
parseNoteextracts YAML frontmatter, H1 titles, tags, and wikilinks. - Chunking:
chunkNotesplits the note body into sections based on ATX headings. - Embedding: Chunks are sent to Ollama using the
nomic-embed-textmodel. - Storage: Vectors and metadata are stored in Qdrant as
ChunkPointobjects.
Sources: services/memory-api/src/ingest/ingest.ts:55-125, services/memory-api/src/markdown/parse.ts:13-35, services/memory-api/README.md:73-86
Data Structures
The system uses specific interfaces to maintain consistency across the pipeline.
Network and Security Architecture
Security is enforced through network isolation and mandatory authentication.
Access Profiles
Nyansa supports three access modes:
- Local: Services bind to
localhostfor development and local usage. - Public: Caddy provides Let's Encrypt certificates and basic auth for the n8n editor.
- Tailscale: No public ports are opened; access is restricted to a Tailscale tailnet.
Internal Security
- Bearer Tokens:
memory-apirequires a 32+ character token for all operations except health checks. - API Keys: Qdrant is protected by an API key injected into n8n and
memory-apiat runtime. - Read-Only Mounts: The Obsidian vault is mounted read-only into
memory-apito prevent accidental modification during ingestion.
Sources: README.md:28-35, README.md:95-115, services/memory-api/src/config.ts:5-15
Configuration Management
Environment variables define the operational parameters for all services. These are validated using Zod schemas within the TypeScript services to ensure runtime stability.
| Variable | Default Value | Description |
|---|---|---|
MEMORY_API_PORT | 8080 | Port for the internal RAG service. |
CHUNK_MAX_CHARS | 1500 | Maximum character length for a single vector chunk. |
EMBEDDING_MODEL | nomic-embed-text | Model used for generating vector embeddings. |
VAULT_PATH | /vault | Internal mount point for the Obsidian vault. |
Sources: services/memory-api/src/config.ts:4-16, services/memory-api/README.md:104-115
Summary
The Nyansa architecture provides a robust, local-first foundation for AI-assisted knowledge management. By decoupling note parsing and vector storage into the memory-api service, the system enables efficient RAG capabilities while maintaining the privacy of the underlying Obsidian vault. The use of Docker profiles and Caddy ensures flexible deployment across local, public, and private network environments.