Architecture
How better-vault is built, the decisions behind it and where the code lives, for people and AI coding agents who want to contribute to the web or desktop app.
better-vault is a Next.js 16 App Router app that uses the Vercel AI SDK for every model call. This page is a short tour; AGENTS.md in the repository holds the full rules.
Web and desktop
The same code serves both apps. In a browser, notebooks are stored in IndexedDB through Dexie. The desktop app wraps the web app in Electron: it runs a standalone build of the Next.js server on the user's computer and keeps notebooks in a SQLite file, which the page reaches through Electron's IPC.
Both stores sit behind one interface in lib/db/backend.ts, and the database tests run against each of them. A change to the web app therefore reaches the desktop app without extra work, as long as it passes those tests and the desktop build.
Design decisions
| Decision | What it means |
|---|---|
| Local-first | Data stays on the user's device, in IndexedDB or the desktop's SQLite file. No server database, no auth. |
| Bring your own key | Keys are stored on the device and sent in each request's body. Routes never log or store them. |
| Provider web search only | Web mode uses the provider's built-in search tool and no third-party search API. |
| AI SDK for every call | Generation never calls a provider's HTTP API directly; listing models is the one exception. |
| No audio or video overviews | They are out of scope. |
| Mermaid for diagrams | Mind maps and diagrams are Mermaid text, validated and rendered with Pele. |
| Anatomy figures generated each time | No ready-made figures are shipped. |
| Provider image models | Pictures come from the provider's image model through the AI SDK. |
| Local tools | The Whiteboard is made in the browser, with no route and no model. |
Code map
app/ the notebook app (pages and API routes)
app/api/chat streamText: Sources (grounded) or Web (provider search)
app/api/studio one Studio generation, validated against the tool's schema
app/api/models list a provider's models with the user's key
app/api/sources/parse PDF / web page → plain text
components/workspace the notebook screen: top bar, sheets, tabs, prompt, views
studio/ Studio tools: registry, shared dialog fields, one folder per tool
lib/ai providers, model catalog, web-search tools, prompts
lib/db data functions, the storage interface, Dexie and SQLite stores
lib/grounding chunking, retrieval and citations
locales/<lng>/*.json interface translations
desktop/ the Electron app: main process, preload, packaging (its own npm project)
site/ this website and documentation (its own Next.js project)Rules the code follows
The interface uses Panel UI first and falls back to shadcn only for what Panel lacks, with colours from theme tokens and icons from Hugeicons. Every interface string goes through i18next and lives in locales/en/*.json. Layout uses logical CSS such as ms-*, pe-* and text-start, so right-to-left languages work.
Checks
Run the app's checks before you open a pull request:
npm run lint && npm run typecheck && npm test && npm run i18n:check && npm run buildWhen you change the server, storage or anything the desktop app depends on, also run the desktop checks. The first command installs the website and desktop projects once:
npm run setup
npm run desktop:checknpm run desktop:dev opens the desktop app on the app's dev server, and npm run site:dev opens this website.
Commits follow Conventional Commits.
Roadmap
What better-vault has shipped and what comes next: the desktop app, a notebook guide, notes, more source types, deep research and editing Studio outputs.
Add a Studio tool
Create a new Studio tool in better-vault: a definition, a server prompt and output schema, an options dialog and a viewer, registered on client and server.