LocalLens

Build it from scratch

A ten-step walkthrough that starts at an empty folder and ends with a working local-AI chat app.

The walkthrough rebuilds LocalLens from the inside out. Each step adds one file (step 0 sets up the project shell), explains why the file exists, shows the minimum code, and points you at the next step.

The order is deliberate. It mirrors the import direction of the codebase, so no step depends on a file you haven't written yet.

The ten steps

  1. Project setup — bun init, install dependencies, set up the configs and scripts.
  2. Domain types and AppError — the shared vocabulary every other file imports.
  3. Chunking and the grounded prompt — the retrieval-side helpers that don't yet know about the SDK.
  4. The QVAC gateway — load models, ingest, search, stream completions.
  5. The JSON store — persist brains and chunks to .locallens/store.json.
  6. File adapters — local folder walk and browser file-picker normalization.
  7. The application workflow — wire everything together in LocalLensApp.
  8. The CLI — the no-UI entry point.
  9. The Bun server — the optional HTTP surface.
  10. The browser UI — a thin layer over the server.

The teachable path

The walkthrough covers the parts that teach the architecture. It doesn't explain every CSS rule or every UI helper. The full source is on GitHub — read it once you've gone through these pages.

Why this order

Each step depends only on what came before:

project shell → bun init, deps, configs (no source yet)
domain.ts     → no internal imports
rag.ts        → imports domain
qvac.ts       → imports domain
store.ts      → imports domain
files.ts      → imports domain
locallens.ts  → imports domain, files, qvac, rag, store
cli.ts        → imports domain, locallens
server.ts     → imports domain, locallens
ui/           → talks to server.ts over HTTP

Build in this order and bun run typecheck stays green after every step.

On this page

The ten stepsWhy this order