{"id":51889421,"url":"https://github.com/tailorgunjan93/knovex","last_synced_at":"2026-07-26T02:01:37.415Z","repository":{"id":359990320,"uuid":"1248091119","full_name":"tailorgunjan93/knovex","owner":"tailorgunjan93","description":"Knovex — AI-powered desktop knowledge base. Multi-format RAG, chat, summarizer, file reader, web search. Built on docnest.","archived":false,"fork":false,"pushed_at":"2026-06-14T17:41:24.000Z","size":3406,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T19:14:19.580Z","etag":null,"topics":["ai","desktop-app","document-management","electron","fastapi","fts5","knowledge-base","llm","local-first","python","rag","react","sqlite","streaming","typescript"],"latest_commit_sha":null,"homepage":"https://tailorgunjan93.github.io/knovex/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tailorgunjan93.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-24T07:12:22.000Z","updated_at":"2026-06-14T17:41:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tailorgunjan93/knovex","commit_stats":null,"previous_names":["tailorgunjan93/knovex"],"tags_count":56,"template":false,"template_full_name":null,"purl":"pkg:github/tailorgunjan93/knovex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tailorgunjan93%2Fknovex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tailorgunjan93%2Fknovex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tailorgunjan93%2Fknovex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tailorgunjan93%2Fknovex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tailorgunjan93","download_url":"https://codeload.github.com/tailorgunjan93/knovex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tailorgunjan93%2Fknovex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35898043,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-26T02:00:06.503Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","desktop-app","document-management","electron","fastapi","fts5","knowledge-base","llm","local-first","python","rag","react","sqlite","streaming","typescript"],"created_at":"2026-07-26T02:01:36.622Z","updated_at":"2026-07-26T02:01:37.403Z","avatar_url":"https://github.com/tailorgunjan93.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Knovex\n\n### AI-powered Desktop Knowledge Base\n\n*Secure · Fast · Reliable · Cost-Effective*\n\n[![Download](https://img.shields.io/badge/⬇_Download-Windows_·_macOS_·_Linux-DDA76A.svg)](https://tailorgunjan93.github.io/knovex/)\n[![Version](https://img.shields.io/badge/version-0.15.0-blue.svg)](CHANGELOG.md)\n[![CI](https://github.com/tailorgunjan93/knovex/actions/workflows/ci.yml/badge.svg)](https://github.com/tailorgunjan93/knovex/actions/workflows/ci.yml)\n[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)](#)\n[![Python](https://img.shields.io/badge/python-3.11+-green.svg)](#)\n[![License](https://img.shields.io/badge/license-MIT-orange.svg)](LICENSE)\n[![Powered by docnest](https://img.shields.io/badge/powered%20by-docnest--ai-purple.svg)](https://pypi.org/project/docnest-ai/)\n[![Read on DEV](https://img.shields.io/badge/dev.to-Read%20the%20Article-0A0A0A?logo=devdotto\u0026logoColor=white)](https://dev.to/gunjantailor/i-built-a-local-first-ai-desktop-knowledge-base-heres-what-i-learned-3o4a)\n\n**Knovex** is a local-first, AI-powered desktop knowledge base with an interactive learning engine.  \nDrop in your documents, ask questions, summarise, search the web, and turn complex topics into animated, gamified learning sessions — all running on your machine.\n\nBuilt on top of [docnest-ai](https://pypi.org/project/docnest-ai/) — a hybrid RAG engine with SQLite FTS5 + dense ANN + section-graph retrieval.\n\n### 📥 [Download Knovex](https://tailorgunjan93.github.io/knovex/)\n\nGet the latest installer for **Windows · macOS · Linux** from the download page:\n**https://tailorgunjan93.github.io/knovex/**\n(Already installed? The app auto-updates — or grab any version from [Releases](https://github.com/tailorgunjan93/knovex/releases).)\n\n\u003c/div\u003e\n\n---\n\n## What is Knovex?\n\nKnovex is a **local-first desktop app** that turns your documents — and any topic you're curious about — into something you can *question, search, and actually learn from*. Everything runs on your machine; your files never leave it unless you explicitly turn on web search.\n\nThink of it as three tools in one:\n\n- 🗂️ **A knowledge base** — drop in PDFs, Word docs, Markdown or CSVs. Knovex indexes them, lets you read them inline, and answers questions grounded in *your* content — with citations.\n- 💬 **An AI chat \u0026 summariser** — converse with your library, get cited answers, summarise a file or a whole collection, and optionally pull in live web results.\n- 🎓 **A learning engine** — turn any topic into quizzes, flashcards, guided walkthroughs, or **animated lessons** that build a concept up one idea at a time.\n\n**Who it's for:** students, researchers, and knowledge workers who want a private, offline place to keep what they know and genuinely learn it — without shipping their documents to someone else's cloud. Bring your own LLM key (OpenAI, Claude, Groq, Gemini, Cerebras, AWS Bedrock) or run fully offline with Ollama.\n\n\u003e Built on [docnest-ai](https://pypi.org/project/docnest-ai/) — a hybrid retrieval (RAG) engine that combines keyword search, semantic vectors, and a document section-graph.\n\n---\n\n## 🎬 A tour of the app\n\n\u003cdiv align=\"center\"\u003e\n\n| Knowledge Base | Reader |\n|:--:|:--:|\n| ![Knowledge Base](docs/media/app-kb.png) | ![Reader](docs/media/app-reader.png) |\n| \u003csub\u003eCollections of indexed documents, ready to search.\u003c/sub\u003e | \u003csub\u003eRead any file inline, with focus modes \u0026 highlights.\u003c/sub\u003e |\n\n| Chat — grounded in your docs | Progress |\n|:--:|:--:|\n| ![Chat](docs/media/app-chat.png) | ![Progress](docs/media/app-progress.png) |\n| \u003csub\u003eCited answers — every claim links back to a source.\u003c/sub\u003e | \u003csub\u003eStreaks, XP and an activity heatmap as you learn.\u003c/sub\u003e |\n\n| Learn — pick a format | Settings |\n|:--:|:--:|\n| ![Learn](docs/media/app-home.png) | ![Settings](docs/media/app-settings.png) |\n| \u003csub\u003eAny topic \u0026rarr; quiz, flashcards, guided or animated.\u003c/sub\u003e | \u003csub\u003eBring your own LLM key, or run offline with Ollama.\u003c/sub\u003e |\n\n\u003c/div\u003e\n\n### ✨ Animated lessons — the standout\n\nType any topic and Knovex builds an **animated lesson** that explains itself one idea at a time. The model declares the *structure* (a diagram type, the items, the connections); Knovex's layout engine draws every box, arrow and label — no overlap, correct direction — and narrates each beat in a caption beside the stage.\n\n\u003cdiv align=\"center\"\u003e\n\n![Animated lesson — the water cycle, built step by step](docs/media/animated-lesson.gif)\n\n\u003csub\u003eProgressive disclosure (one idea at a time) + signaling (the focus glows, the rest dim) — the way good explainers teach.\u003c/sub\u003e\n\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n![The full Learn workspace](docs/media/app-learn.png)\n\n\u003csub\u003eThe full Learn workspace — the animated lesson alongside its step outline and the concepts it pulled in.\u003c/sub\u003e\n\n\u003c/div\u003e\n\nThe engine picks the **right diagram for the topic** — a transformation, a hierarchy, or a step-by-step process:\n\n| Reaction — transformations | Tree — hierarchies | Flow — processes |\n|:--:|:--:|:--:|\n| ![Photosynthesis as a reaction](docs/media/diagram-reaction.png) | ![Branches of government as a tree](docs/media/diagram-tree.png) | ![How email is delivered as a flow](docs/media/diagram-flow.png) |\n\n---\n\n## Key Features\n\n### 📁 Knowledge Base + File Reader *(v0.3.0)*\n- Create multiple named knowledge bases with colours and emoji icons\n- Add PDF, DOCX, TXT, MD, CSV, UDF files via file picker or Electron drag-drop\n- Auto-ingestion powered by docnest (FTS5 + ANN indexing) — runs as a background task\n- File watcher automatically detects stale or missing tracked files\n- Click any indexed file → opens inline **FileViewer** with Q\u0026A sidebar\n- Pagination: 40 blocks/page for text formats; 1 page/block for PDF\n- SSE streaming Q\u0026A grounded in the file's indexed chunks\n- Supported block types: `paragraph`, `heading`, `table_row`, `code`, `page`\n\n### 💬 Chat + Summariser *(v0.4.0)*\n- Conversational QA against a selected KB with streaming token-by-token responses\n- Source citations — which file and section answered your question\n- Persistent chat sessions with full message history\n- Session sidebar with create, rename, delete, and export to Markdown\n- Web search toggle per message (DuckDuckGo free / Serper / Brave)\n- Summariser: brief (~150 words) or detailed (~600 words) of a file or entire KB\n- Blinking cursor animation, AbortController stop mid-stream\n\n### ✨ Learn Mode *(v0.6.0 – v0.15.0)*\n- **Multiple formats**: Quiz (interactive MCQ), Flashcards (spaced repetition), Mind Map (collapsible tree), Timeline (chronological events), Story (narrative markdown), ELI5, Speed Learn (bullet summary), Brainstorm (creative connections), **Guided** (step-by-step walkthrough via GuidedViewer)\n- **Animated lessons** *(v0.15.0)* — a structure-first *\"Mermaid\"* engine: the LLM declares a diagram (**flow · cycle · tree · compare · timeline · hub** or a directional **reaction**) plus per-step narration, and a pure layout engine (`frontend/src/lib/sceneLayout.ts`) computes every coordinate. The diagram builds one idea at a time (*progressive disclosure*), the active piece glows while the rest dim (*signaling*), and code topics step through the real snippet line by line. See [the tour above](#-a-tour-of-the-app).\n- **Gamification**: XP points, level progression (10 tiers), daily streaks, 10 achievement badges\n- All formats stream via SSE — JSON formats via LLM + parse + re-stream, text formats real-time\n- Per-question XP rewards in quiz mode; spaced-repetition interval scheduling for flashcards\n- **Session history sidebar** — reload any past session and interact with it\n- **Encrypted keys**: Fernet AES-128 symmetric encryption; key at `~/.config/Knovex/.knovex.key`; proven by 25 dedicated encryption tests\n\n### 📊 Progress Page *(v0.8.0)*\n- **4 stat cards**: Streak (fire trend, singular/plural days), XP (level badge, comma-formatted), Sessions (week-over-week delta), Active Days\n- **Daily activity heatmap** — 26 weeks of session activity, colour-coded by intensity\n- **Learning velocity chart** — sessions/week + active days/week dual-axis Recharts graph\n- All data from live API; zero-state renders cleanly when no sessions exist yet\n\n### ⚙️ Settings + Packaging *(v0.5.0)*\n- LLM: OpenAI, Anthropic (Claude), Groq, Gemini, Cerebras, AWS Bedrock, Ollama\n- Per-provider model selection from live catalogue; API key encrypted at rest with Fernet\n- Ollama auto-detect button — probes localhost:11434, lists installed models\n- Test Connection button with round-trip latency display\n- Web search engine: DuckDuckGo (free) / Serper / Brave + conditional API key field\n- Theme: Light / Medium / Dark (auto-applies without restart)\n- KB storage path picker via native OS folder dialog\n- **Desktop packaging**: PyInstaller backend binary + electron-builder installers\n  - Windows `.exe` (NSIS), macOS `.dmg`, Linux `.AppImage`\n  - Window state persistence (position + size saved across sessions)\n  - Tray → Settings navigates React Router via IPC\n- Build scripts: `scripts/build.ps1` (Windows) and `scripts/build.sh` (macOS/Linux)\n- Package CI/CD workflow: builds all 3 platforms on tag push, attaches assets to GitHub Release\n\n---\n\n## Architecture\n\nKnovex uses a **fully decoupled** frontend/backend architecture with SOLID compliance and the GoF adapter pattern for all third-party libraries.\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│  DESKTOP SHELL  (Electron 33)                                               │\n│  Spawns backend process, manages window lifecycle, tray, OS file dialogs    │\n│  ┌─────────────────────────────────────────────────────────────────────┐    │\n│  │  FRONTEND  (React 18 + MUI v6 + TypeScript + Vite 6)               │    │\n│  │  KnowledgeBase · Chat · Learn Mode · Settings                       │    │\n│  │  TanStack Query v5 (server state) · Zustand (UI state)             │    │\n│  └───────────────────────────┬─────────────────────────────────────────┘    │\n└──────────────────────────────│──────────────────────────────────────────────┘\n                               │  REST + SSE  (localhost:8765)\n┌──────────────────────────────▼──────────────────────────────────────────────┐\n│  BACKEND  (FastAPI + Python 3.11)                                           │\n│                                                                             │\n│  API Routes                                                                 │\n│  ├── /api/kb/**           KB CRUD + file management (13 endpoints)         │\n│  ├── /api/kb/**/content   File content rendering (paginated blocks)         │\n│  ├── /api/kb/**/ask       Inline Q\u0026A SSE stream                            │\n│  ├── /api/sessions/**     Chat session CRUD + SSE stream + export          │\n│  ├── /api/summarize/**    File / KB summariser SSE stream                  │\n│  ├── /api/search/web      Web search endpoint                              │\n│  ├── /api/settings/**     LLM + search config                              │\n│  └── /api/health          Liveness + Ollama probe                          │\n│                                                                             │\n│  Services (Facades)                                                         │\n│  ├── KBService        KB CRUD + ingestion orchestration                    │\n│  ├── ReaderService    File rendering + inline Q\u0026A                          │\n│  ├── ChatService      Session CRUD + FTS5 retrieval + SSE streaming        │\n│  ├── SummariserService File / KB summariser (brief / detailed)             │\n│  ├── SearchService    Web search facade (DDG / Serper / Brave)             │\n│  ├── IngestionService Strategy-pattern file parsing → chunk storage        │\n│  ├── LLMService       Unified LLM (stream / complete / test / models)      │\n│  ├── SettingsService  Encrypted settings read/write                        │\n│  └── WatcherService   Periodic stale/missing file scanner                  │\n│                                                                             │\n│  Anti-Corruption Adapters  (backend/adapters/)                             │\n│  ├── ILLMClient / LiteLLMAdapter     — wraps litellm                       │\n│  ├── IHttpClient / HttpxAdapter      — wraps httpx                         │\n│  ├── IPDFAdapter / PyMuPDFAdapter    — wraps fitz (PyMuPDF)                │\n│  ├── IParagraphAdapter / PythonDocxAdapter — wraps python-docx             │\n│  └── IWebSearchAdapter / DDG/Serper/BraveAdapter — wraps search libs       │\n│                                                                             │\n│  Storage                                                                    │\n│  └── SQLite (WAL mode) — kbs, files, chunks, chunks_fts (FTS5)             │\n│                                                                             │\n│  Events — in-process typed EventBus                                        │\n│  └── KBCreated · FileAdded · FileIngested · FileStale · Missing · Error   │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n### Design Patterns\n\n| Pattern | Where |\n|---------|-------|\n| Adapter (GoF) | `backend/adapters/` — anti-corruption layer for all 3rd-party libs |\n| Strategy | `IngestionService` parsers (`@register_parser` decorator) |\n| Template Method | `LLMProvider.complete()` / `stream()` delegate to `ILLMClient` |\n| Factory + Plugin | `LLMProviderFactory` + `@register_provider` self-registration |\n| Repository | `IKBRepository`, `IFileRepository`, `IChatRepository` — abstract storage |\n| Facade | `KBService`, `LLMService`, `ReaderService`, `ChatService`, `SummariserService`, `SearchService` |\n| Observer | `EventBus.emit_typed()` — typed in-process events |\n| Value Object | `ProviderCredentials`, `HttpResponse`, `PageContent`, `ParagraphContent` |\n\n---\n\n## Tech Stack\n\n| Layer | Technology | Purpose |\n|-------|-----------|---------|\n| Desktop Shell | Electron 33 | Cross-platform window, tray, OS dialogs |\n| Frontend | React 18 + TypeScript | UI components |\n| UI Library | MUI v6 | Design system |\n| State | Zustand + TanStack Query v5 | UI state + server state |\n| Build | Vite 6 | Fast dev + bundling |\n| Backend | FastAPI + Python 3.11 | REST API, SSE streaming, async |\n| RAG Engine | docnest-ai | Hybrid FTS5 + ANN retrieval |\n| LLM Bridge | LiteLLM (via adapter) | Unified multi-provider LLM |\n| Database | SQLite + FTS5 | Local storage, full-text search |\n| Web Search | duckduckgo-search / Serper / Brave | Live web results |\n| Encryption | cryptography (Fernet) | API key encryption at rest |\n| Packaging | PyInstaller + electron-builder | Distributable app |\n| E2E Testing | Playwright | Browser-driven end-to-end tests (mocked + real-backend SSE) |\n\n---\n\n## Project Structure\n\n```\nknovex/\n├── README.md\n├── CHANGELOG.md\n├── .gitignore\n│\n├── playwright.config.ts            Playwright E2E config (Vite dev server + Chromium)\n├── e2e/\n│   ├── learn.spec.ts               27 tests — Learn Mode visual + functional flows\n│   └── progress.spec.ts            34 tests — Progress Page layout + data accuracy\n│\n├── .github/\n│   └── workflows/\n│       ├── ci.yml          Python lint + test + frontend build (push / PR)\n│       ├── release.yml     GitHub Release on v* tag push\n│       └── package.yml     Builds Win/macOS/Linux installers + attaches to release\n│\n├── scripts/\n│   ├── build.ps1           Windows full build pipeline (lint → test → PyInstaller → NSIS)\n│   └── build.sh            macOS / Linux build pipeline\n│\n├── docs/\n│   ├── ARCHITECTURE.md\n│   ├── IMPLEMENTATION_PLAN.md\n│   ├── FEATURES.md\n│   ├── API_SPEC.md\n│   └── TECH_STACK.md\n│\n├── backend/                            FastAPI Python — standalone API\n│   ├── api/\n│   │   ├── health.py                   GET /api/health\n│   │   ├── settings.py                 GET|PUT /api/settings, test-llm, models, ollama\n│   │   ├── kb.py                       13 KB + file endpoints\n│   │   ├── reader.py                   GET /content, POST /ask (SSE)\n│   │   ├── chat.py                     8 chat endpoints (sessions + stream + export)\n│   │   ├── summarizer.py               POST /summarize/file, /summarize/kb\n│   │   ├── search.py                   POST /search/web\n│   │   └── tools.py                    Tool registry\n│   ├── backend_entry.py                PyInstaller entry point (uvicorn bootstrap)\n│   ├── knovex-backend.spec             PyInstaller build spec\n│   ├── adapters/                       Anti-corruption layer ← ALL 3rd-party here\n│   │   ├── llm_client.py               ILLMClient / LiteLLMAdapter / StubLLMClient\n│   │   ├── http_client.py              IHttpClient / HttpxAdapter / StubHttpClient\n│   │   ├── document_parsers.py         IPDFAdapter, IParagraphAdapter + stubs\n│   │   └── web_search.py               IWebSearchAdapter / DDG / Serper / Brave / Stub\n│   ├── core/\n│   │   ├── domain/\n│   │   │   ├── kb.py                   KB dataclass\n│   │   │   ├── file_record.py          FileRecord + FileStatus\n│   │   │   └── chat.py                 ChatSession + ChatMessage\n│   │   ├── providers/                  7 LLM providers (self-registering)\n│   │   ├── config.py                   AppConfig (pydantic-settings)\n│   │   ├── dependencies.py             FastAPI DI wiring\n│   │   ├── encryption.py               Fernet encryptor\n│   │   ├── chat_service.py             Chat facade (session CRUD + streaming QA)\n│   │   ├── ingestion_service.py        Strategy-based file parsing\n│   │   ├── kb_service.py               KB facade\n│   │   ├── llm_service.py              LLM facade\n│   │   ├── reader_service.py           File rendering + inline Q\u0026A\n│   │   ├── search_service.py           Web search facade\n│   │   ├── settings_service.py         Settings r/w\n│   │   ├── settings_store.py           JSON persistence\n│   │   ├── summarizer_service.py       File + KB summariser\n│   │   └── watcher_service.py          Stale/missing file scanner\n│   ├── events/\n│   │   ├── bus.py                      EventBus singleton\n│   │   └── types.py                    Typed event dataclasses\n│   ├── models/\n│   │   └── schemas.py                  All Pydantic request/response models\n│   ├── storage/\n│   │   ├── database.py                 SQLite schema + FTS5\n│   │   ├── sqlite_backend.py           Async SQLite backend\n│   │   └── repositories/\n│   │       ├── base.py                 IRepository[T] + EntityNotFoundError\n│   │       ├── chat_repository.py      IChatRepository + SQLiteChatRepository\n│   │       ├── kb_repository.py        IKBRepository + SQLiteKBRepository\n│   │       └── file_repository.py      IFileRepository + SQLiteFileRepository\n│   ├── requirements.txt\n│   ├── requirements-dev.txt            pytest, ruff, mypy, pytest-asyncio\n│   └── main.py\n│\n├── frontend/                           React + TypeScript — pure UI consumer\n│   └── src/\n│       ├── api/\n│       │   ├── client.ts               Axios instance\n│       │   ├── kb.api.ts               KB + file endpoints\n│       │   ├── reader.api.ts           Content + SSE ask stream\n│       │   ├── settings.api.ts         Settings + LLM config\n│       │   ├── chat.api.ts             Chat sessions + SSE stream + export\n│       │   ├── summarizer.api.ts       SSE file / KB summarise\n│       │   └── search.api.ts           Web search\n│       ├── components/\n│       │   ├── Layout/                 AppShell, Sidebar\n│       │   └── FileViewer/             Block renderer + pagination\n│       └── pages/\n│           ├── KnowledgeBase/          KB list + detail + file viewer + inline Q\u0026A\n│           ├── Chat/                   Session sidebar + streaming message thread\n│           ├── Learn/                  multiple formats + animated engine + session history\n│           ├── Progress/               Stats cards + heatmap + velocity chart\n│           └── Settings/              LLM + Search + App + Embedding tabs\n│\n├── desktop/                            Electron — thin shell only\n│   ├── main.js\n│   ├── preload.js\n│   └── package.json\n│\n└── tests/\n    ├── __init__.py\n    ├── test_imports.py                 Import smoke tests + route registration (all sprints)\n    ├── test_adapters.py                Adapter unit tests (all stubs, no network)\n    ├── test_reader.py                  ReaderService unit tests\n    └── test_chat.py                    ChatService + SearchService unit tests\n```\n\n---\n\n## ⌨️ Commands\n\nQuick reference, from a clone to a packaged installer:\n\n| Task | Command |\n|------|---------|\n| **Run backend** (dev) | `uvicorn backend.main:app --host 127.0.0.1 --port 8765 --reload` |\n| **Run frontend** (dev) | `cd frontend \u0026\u0026 npm run dev` |\n| **Backend tests** | `pytest tests/ -v` |\n| **Backend tests + coverage** | `pytest tests/ --cov=backend --cov-report=term-missing` |\n| **Frontend unit tests** | `cd frontend \u0026\u0026 npm test` |\n| **Frontend typecheck** | `cd frontend \u0026\u0026 npx tsc --noEmit` |\n| **Lint (Python)** | `ruff check backend/ tests/` |\n| **E2E (mocked API)** | `npx playwright test` |\n| **E2E (real backend, SSE)** | `KNOVEX_PYTHON=.venv/Scripts/python.exe npx playwright test --config playwright.config.realbackend.ts` |\n| **Build installer — Windows** | `.\\scripts\\build.ps1` *(add `-SkipTests`)* |\n| **Build installer — macOS/Linux** | `./scripts/build.sh` *(add `--skip-tests`)* |\n| **Cut a release** | bump version files → update `CHANGELOG.md` → `git tag vX.Y.Z \u0026\u0026 git push origin vX.Y.Z` |\n\n\u003e API docs (Swagger UI): **http://localhost:8765/api/docs** once the backend is running.\n\n---\n\n## Getting Started\n\n\u003e **Just want to use Knovex?** No build required — download the installer for your OS\n\u003e from **https://tailorgunjan93.github.io/knovex/**. The steps below are for running\n\u003e from source / development.\n\n### Prerequisites\n\n| Tool | Version | Install |\n|------|---------|---------|\n| Python | 3.11+ | [python.org](https://python.org) |\n| Node.js | 20+ | [nodejs.org](https://nodejs.org) |\n| npm | 10+ | bundled with Node.js |\n| git | any | [git-scm.com](https://git-scm.com) |\n\n### Backend Setup\n\n```bash\n# Clone the repo\ngit clone https://github.com/tailorgunjan93/knovex.git\ncd knovex\n\n# Create virtual environment\npython -m venv .venv\n.venv\\Scripts\\activate          # Windows\n# source .venv/bin/activate     # macOS / Linux\n\n# Install dependencies\npip install -r backend/requirements.txt\n\n# Start the backend (auto-creates DB on first run)\nuvicorn backend.main:app --host 127.0.0.1 --port 8765 --reload\n```\n\nAPI docs are available at **http://localhost:8765/api/docs** (Swagger UI).\n\n### Frontend Setup\n\n```bash\ncd frontend\nnpm install\nnpm run dev      # Vite dev server on http://localhost:5173\n```\n\nThe Vite proxy forwards all `/api/*` requests to `localhost:8765`.\n\n### Run Tests\n\n```bash\n# Install dev dependencies\npip install -r backend/requirements-dev.txt\n\n# Run all tests\npytest tests/ -v\n\n# With coverage\npytest tests/ --cov=backend --cov-report=term-missing\n```\n\n### Run E2E Tests\n\n```bash\n# Install Playwright browsers (first time only)\nnpx playwright install chromium\n\n# Run all 61 E2E tests (auto-starts Vite dev server)\nnpx playwright test\n\n# Interactive UI mode\nnpx playwright test --ui\n\n# Run a single spec\nnpx playwright test e2e/learn.spec.ts\n```\n\nE2E tests mock all `/api/*` calls via `page.route()` — no backend required.\nResults in `playwright-report/`. Failures attach screenshot + trace.\n\n### Lint\n\n```bash\nruff check backend/ tests/\n```\n\n### Build Desktop App\n\n**Windows** (PowerShell):\n```powershell\n.\\scripts\\build.ps1               # full pipeline → desktop/release/*.exe\n.\\scripts\\build.ps1 -SkipTests   # faster (skip pytest)\n```\n\n**macOS / Linux** (bash):\n```bash\n./scripts/build.sh                # full pipeline → desktop/release/*.dmg / .AppImage\n./scripts/build.sh --skip-tests  # faster\n```\n\nThe script runs: lint → tests → Vite frontend build → PyInstaller backend binary → electron-builder installer.\n\n---\n\n## CI/CD\n\n| Trigger | Workflow | Actions |\n|---------|----------|---------|\n| Push / PR to `main` | `ci.yml` | Python lint (ruff) + pytest + frontend TypeScript check + build |\n| Push `v*.*.*` tag | `release.yml` | Runs CI, then creates a GitHub Release with CHANGELOG excerpt |\n| Push `v*.*.*` tag | `package.yml` | Builds Win/macOS/Linux installers + attaches to GitHub Release |\n\nTo create a new release:\n\n```bash\ngit tag v0.4.0\ngit push origin v0.4.0\n```\n\n---\n\n## Roadmap\n\n### Phase 1 — Desktop App *(current)*\n\n- [x] Sprint 1 — Foundation (FastAPI + React + Electron shell) — `v0.1.0`\n- [x] Sprint 2 — Knowledge Base + File Ingestion + Adapter layer — `v0.2.0`\n- [x] Sprint 3 — File Reader + Inline Q\u0026A — `v0.3.0`\n- [x] Sprint 4 — Chat + Summariser + Web Search — `v0.4.0`\n- [x] Sprint 5 — Settings UI + Desktop Packaging — `v0.5.0`\n- [x] Sprint 6 — Learn Mode + Encryption Verification — `v0.6.0`\n- [x] Sprint 7 — Semantic Search (ONNX/OpenAI) + Copper Theme + Auto-updater — `v0.6.6`\n- [x] Sprint 8 — Progress Page + GuidedViewer + KB Browser Upload + E2E Test Suite (61 tests) — `v0.8.0`\n\n### Phase 2 — Cloud + Organisation + Agentic *(future)*\n\n- [ ] Knovex Cloud Portal (web admin — org key management, user management, analytics)\n- [ ] 3 deployment modes: Personal / Organisation (portal) / Self-hosted (Docker)\n- [ ] LangGraph agent orchestration\n- [ ] Visual workflow builder\n- [ ] Cloud deployment (Railway / AWS) — PostgreSQL on OUR infra, not user machines\n- [ ] Web app + mobile app (React Native — same backend API)\n- [ ] Team collaboration + shared KBs\n- [ ] Plugin / connector marketplace\n- [ ] Learn Mode: voice narration, social sharing, multiplayer sessions\n\n---\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [CHANGELOG.md](CHANGELOG.md) | Full version history with detailed change notes |\n| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | System architecture and design decisions |\n| [docs/IMPLEMENTATION_PLAN.md](docs/IMPLEMENTATION_PLAN.md) | Sprint plan with tasks and milestones |\n| [docs/FEATURES.md](docs/FEATURES.md) | Complete feature specification |\n| [docs/API_SPEC.md](docs/API_SPEC.md) | All API endpoints and data contracts |\n| [docs/TECH_STACK.md](docs/TECH_STACK.md) | Technology choices and rationale |\n\n## Article\n\n**[I Built a Local-First AI Desktop Knowledge Base — Here's What I Learned](https://dev.to/gunjantailor/i-built-a-local-first-ai-desktop-knowledge-base-heres-what-i-learned-3o4a)**  \nPublished on [DEV Community](https://dev.to) — covers the architecture decisions, lessons from shipping a PyInstaller + Electron desktop app, and the real bugs that shipped and had to be fixed.\n\n---\n\n## About\n\nBuilt by [Gunjan Tailor](https://github.com/tailorgunjan93) on top of [docnest-ai](https://pypi.org/project/docnest-ai/).\n\n*Secure · Fast · Reliable · Cost-Effective*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftailorgunjan93%2Fknovex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftailorgunjan93%2Fknovex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftailorgunjan93%2Fknovex/lists"}