Project Structure
Relevant source files
The following files were used as context for generating this wiki page:
Nyansa organizes its components as a Docker Compose stack to provide a self-hosted "second brain" environment. The project separates concerns into orchestration, automation, AI services, and infrastructure management scripts.
Sources: README.md:10-15, README.md:214-235
System Architecture
The project uses a Docker-based architecture where services communicate over an internal network named nyansa. Only the Caddy reverse proxy remains accessible from the host or external network, enforcing security boundaries for internal components like the vector store and LLM engine.
The diagram illustrates the data flow between the user interface, the workflow engine (n8n), the custom RAG service (memory-api), and the underlying data stores.
Sources: README.md:58-96
Core Components
The project structure defines the roles of various technologies used to process and store vault data.
| Component | Technology | Primary Role |
|---|---|---|
| Workflow Engine | n8n | Orchestrates AI agents and automations. |
| LLM Inference | Ollama | Runs local models (qwen2.5:3b, nomic-embed-text). |
| Vector Database | Qdrant | Stores note embeddings and metadata. |
| RAG Service | memory-api | Parses, chunks, and indexes Obsidian notes. |
| Persistence | PostgreSQL | Stores n8n internal state and credentials. |
| Access Control | Caddy | Manages HTTPS, authentication, and routing. |
Sources: README.md:100-112
Service Directory Structure
The repository maintains a flat organizational structure for configuration and a nested structure for custom services.
Root Level Files
docker-compose.yml: Defines the service stack, volumes, and network profiles..env.example: Provides a template for required secrets and paths.
Services Directory (/services)
Contains custom-built applications. Currently, this includes memory-api, a Node.js/TypeScript application.
memory-api/src/: Contains core logic for parsing (markdown/), ingestion (ingest/), and the search API (app.ts).memory-api/test/: Includes Vitest suites for validating chunking and ingestion logic.
Automation and Scripts (/scripts, /hooks)
The project includes shell scripts for lifecycle management.
backup.sh/restore.sh: Handle stateful volume and database backups.build-publish.sh: Creates immutable release folders for deployment.check-exposure.sh: Validates firewall and port rules.post-receive: Implements push-to-deploy logic on the server.
Sources: README.md:214-235, scripts/build-publish.sh:16-32
Data Ingestion Flow
The memory-api service implements a specialized pipeline to transform Markdown files into searchable vectors. This process is structured into four distinct phases: scanning, planning, processing (parsing/chunking), and storage.
The ingestion process ensures incremental updates by comparing file hashes against stored metadata in Qdrant.
Sources: services/memory-api/README.md:46-55, services/memory-api/src/ingest/ingest.ts:114-142
Deployment Structure
Production environments use an immutable folder structure created by the build-publish.sh script. This ensures the running code matches a specific Git commit and excludes development files.
/opt/nyansa/
├── releases/
│ ├── <sha1>/ # Immutable release folder
│ └── <sha2>/ # Previous release
└── current -> releases/<sha1>/ # Symbolic link to active release
The build-publish.sh script copies only the RUNTIME_PATHS into the release folder, including:
- Docker configurations (
docker-compose.yml) - Caddy configuration files
- Pre-configured n8n data
memory-apisource code and build manifests
Sources: README.md:144-155, scripts/build-publish.sh:16-32
Summary
The Nyansa project structure facilitates a secure, local-first AI environment by isolating services within a private Docker network and providing robust scripts for backup and deployment. The organization of the memory-api service specifically supports a RAG (Retrieval-Augmented Generation) workflow over private Obsidian vaults.
Sources: README.md:10-15, README.md:120-140