- TypeScript 93.4%
- JavaScript 3.3%
- CSS 1.4%
- Astro 1.3%
- Dockerfile 0.6%
|
All checks were successful
Modaka Sovereign CI / Test & Build Validation (push) Successful in 1m27s
Modaka Sovereign CI / Test & Build Validation (pull_request) Successful in 1m33s
Build and Publish OCI Image / Build & Push ARM64 OCI Image (pull_request) Successful in 1m45s
Build and Publish OCI Image / Build & Push ARM64 OCI Image (push) Successful in 1m19s
Reviewed-on: #3 |
||
|---|---|---|
| .agents | ||
| .forgejo/workflows | ||
| .tycho | ||
| .vscode | ||
| .yarn | ||
| bin | ||
| design-notes | ||
| docs | ||
| public | ||
| scratch | ||
| src | ||
| .dockerignore | ||
| .env.dist | ||
| .gitignore | ||
| .yarnrc.yml | ||
| AGENTS.md | ||
| astro.config.mjs | ||
| CLAUDE.md | ||
| Containerfile | ||
| HOWTO.md | ||
| LICENSE | ||
| OKF_AGENT_PROMPT.md | ||
| package.json | ||
| README.md | ||
| sonar-project.properties | ||
| tsconfig.json | ||
| vitest.config.ts | ||
| yarn.lock | ||
Modaka — Local-First Second Brain, Knowledge Hub & OKF Engine
Modaka is a decentralized, local-first, touch-optimized digital knowledge base and personal AI copilot built on Astro 5, React and Quatrain Core. The language model behind it is chosen by configuration (see Model Providers). It organizes your notes, audio transcripts, PDFs, images, and web research using the standardized OKF (Open Knowledge Format v0.1) structure backed by local Git storage.
🧭 Core Engineering Principles
1. Local-First Architecture
- Single Source of Truth: The local disk (
.modaka-data) is the primary reading and search target. - Instant Synchronization: Modaka bypasses indexing caches on read operations, ensuring that manual filesystem edits, file renames, or external note additions are visible immediately in the UI and to the LLM.
2. OKF (Open Knowledge Format v0.1) Compliance
Every document imported or generated is stored as clean, human-and-AI-readable Markdown:
- Flat YAML Frontmatter: Bounded by
---. Null, empty string (""), or undefined fields are omitted. - Semantic Concept Kinds: The
typefield specifies the functional nature of the knowledge item (e.g.,specification,guide,screenshot,invoice,recipe,note,concept). - Human-Readable Slugs: File and directory names use lowercase slugified titles instead of obscure UUIDs (e.g.,
/content/technology/ai/okf-spec.md).
3. Progressive Disclosure Navigation
- Recursive Indices: Every category directory contains an auto-generated
index.mdfile listing child subcategories and concept documents. - Token Efficiency: AI agents and LLM tools navigate the knowledge graph step-by-step using Markdown links without overwhelming their context window.
4. Hybrid Search Engine Integration (@quatrain/searchengine-qmd)
- Integrates QMD (Query Markup Documents) hybrid search combining BM25 term matching, vector semantic search, and category filtering.
- Exposed natively via the
/api/searchAPI endpoint and consumable by external agents.
5. Resilient Background Processing
- Asynchronous task processing powered by SQLite Queue (
@quatrain/queue-sqlite). - Ingestion tasks (PDF OCR, Audio Transcription, Web Scraping, Wikipedia Auto-Linking) run safely in the background with progress reporting and automatic retries.
🏗️ System Architecture
graph TD
UI["Astro / React PWA Dashboard"] -->|Upload PDF / Image / Audio / Web| UploadAPI["API Server Endpoints"]
UI -->|Hybrid Query| SearchAPI["/api/search Endpoint"]
UI -->|Chat & Contextual AI| ChatAPI["/api/chat Endpoint"]
UploadAPI -->|Enqueue Task| Queue["SQLite Queue Manager"]
Queue -->|Background Worker| Ingestion["Quatrain Ingestion Adapters"]
Ingestion -->|OCR / Audio / Web| LLM["AI port (@quatrain/ai)"]
SearchAPI -->|Search Query| QMD["@quatrain/searchengine-qmd Adapter"]
QMD -->|Hybrid Rank| Disk[("Local OKF Filesystem")]
Ingestion -->|Persist OKF Markdown| OKFAdapter["OKFBackendAdapter"]
OKFAdapter -->|Save & Auto-Index| Disk
OKFAdapter -->|Git Stage & Commit| GitStorage["GitStorageAdapter"]
GitStorage <-->|Async Push/Pull| RemoteGit[("Remote Git Repository")]
🌟 Key Application Features
📊 Multi-Mode Analytics & Knowledge Graph
The Stats module offers three distinct visualization perspectives:
- Synthetic Metrics Table: Live counters of documents, media files, hyperlinks, and category distribution.
- Interactive Link Network Graph: Dynamic SVG visualization mapping cross-document relationships with hover tooltips and category color-coding.
- AI Metrics & Conversation Log: History of past chat sessions with token consumption estimations, average response latency, and instant one-click export to OKF Markdown documents.
🔍 QMD Hybrid Search API
Run multi-modal queries across your knowledge base:
GET /api/search?q=ISO+27001&category=certification&mode=hybrid&limit=10
🎙️ Multi-Format Ingestion Pipelines
- Audio Notes: Transcribes live or uploaded audio recordings (
.wav,.m4a,.mp3) and derives structured summaries. - Multimodal OCR: Extracts text from scanned PDFs and images with a multimodal model (Gemini today, see Roadmap).
- Web Crawling: Scrapes web pages, strips boilerplate navigation, extracts Markdown body text, and recursively processes sub-links.
- Wikipedia Concept Auto-Linking: Identifies proper nouns in documents and automatically pulls Wikipedia summaries to build concept pages under
content/concepts/.
🛠️ Monorepo & Core Package Dependencies
Modaka relies directly on the Quatrain Core modular ecosystem, published as @quatrain/* npm packages. To work against a local Core checkout, set CORE_DIR to its packages/ directory.
| Package | Role & Responsibility |
|---|---|
@quatrain/core |
Core runtime container and singleton registry. |
@quatrain/backend |
Abstract backend persistence layer and query builders. |
@quatrain/okf |
Open Knowledge Format adapter and recursive index.md generator. |
@quatrain/searchengine |
Abstract search engine contract and registry manager. |
@quatrain/searchengine-qmd |
QMD (Query Markup Documents) hybrid BM25/Vector search adapter. |
@quatrain/ai |
Provider-agnostic AI port. |
@quatrain/ai-gemini |
Gemini adapter for the AI port. |
@quatrain/ai-openai |
OpenAI-compatible adapter (OpenAI, Mistral, Groq, OpenRouter, Ollama, any compatible endpoint). |
@quatrain/ingestion-ocr |
Multimodal document OCR processing pipeline. |
@quatrain/ingestion-audio |
Audio transcription and metadata extraction. |
@quatrain/queue-sqlite |
SQLite-backed background task queue. |
@quatrain/storage-git |
Git repository transport layer for version control. |
🚀 Quick Start Guide
Prerequisites
- Node.js:
>= 22.0.0 - Package Manager: Yarn Berry or Bun
- A language model: an API key for a hosted provider, or a local OpenAI-compatible server (see Model Providers)
Environment Configuration (.env)
Create a .env file in the root directory:
# User configuration file written by the settings screen (model provider, see below)
MODAKA_CONFIG_PATH=/absolute/path/to/user_config.json
# Only for the gemini provider
GEMINI_API_KEY=your_google_gemini_api_key_here
GEMINI_MODEL=gemini-2.5-flash
GIT_MODE=local
GIT_LOCAL_PATH=/absolute/path/to/modaka-data
DOCUMENT_STORAGE_PATH=/absolute/path/to/modaka-documents
OKF_STORAGE_PATH=/absolute/path/to/modaka-data/content
S3_BUCKET=documents
Installation & Local Server
# Install dependencies
yarn install
# Run development server
yarn dev
The application will be accessible at http://localhost:4321.
Running Tests
Execute the Vitest suite:
yarn test
Model Providers
Chat and the structuring of ingested content go through the @quatrain/ai port. The provider is chosen in the settings screen, which writes the user configuration file (MODAKA_CONFIG_PATH), or directly in that file:
{
"llm": {
"active": "ollama",
"providers": {
"ollama": { "model": "llama3.1", "endpoint": "http://localhost:11434/v1" }
}
}
}
active |
Adapter | Default endpoint | API key |
|---|---|---|---|
gemini |
@quatrain/ai-gemini |
required (GEMINI_API_KEY or apiKey) |
|
openai |
@quatrain/ai-openai |
https://api.openai.com/v1 |
required |
mistral |
@quatrain/ai-openai |
https://api.mistral.ai/v1 |
required |
groq |
@quatrain/ai-openai |
https://api.groq.com/openai/v1 |
required |
openrouter |
@quatrain/ai-openai |
https://openrouter.ai/api/v1 |
required |
ollama / llama |
@quatrain/ai-openai |
http://localhost:11434/v1 |
none |
Any other OpenAI-compatible server (llama.cpp, vLLM, LM Studio) works with endpoint set to its /v1 URL.
Current limits, tracked in the Roadmap: OCR and audio transcription still require a Gemini model, and text-to-speech uses ElevenLabs, OpenAI or the browser's speech synthesis.
Roadmap
In progress or planned; not available yet:
- Local models for every capability: OCR, transcription and text-to-speech through the AI port, so that a fully local setup needs no hosted provider; local embeddings.
- Traceability: event log of LLM-judge verdicts, of the sources consulted for each answer, of human confirmations (reviewer, date), and of provenance events at ingestion (creation, update, validation, summary, transcription, transfer to a downstream instance). Today the history of a document is its Git history.
- Governed sharing: filtered subsets delivered to downstream instances as Git forks, with feedback flowing back upstream.
- Q/A regression tests replayed on every ingestion.
📄 License
Copyright © 2026 Quatrain Technologies SAS.
This project is licensed under the AGPL-3.0-only license. See the LICENSE file for details.