Architecture

FilDOS is an Electron + React + TypeScript app built with electron-vite. It has three layers plus a shared contract, and a deliberately strict boundary between them.

The four layers

src/shared/     Types + IPC channel names imported by ALL layers   (alias @shared)
src/main/       Main process — all filesystem & database access lives here
src/preload/    contextBridge — the ONLY surface the renderer can call
src/renderer/   The React app                                      (alias @ = src/renderer/src)

The renderer never imports Node or Electron and never touches the disk directly. It calls a small, typed set of preload APIs — window.fsapi, window.watcher, window.tags, window.recents, window.views, window.prefs, window.llm, window.chats, window.graph, and so on — each defined in src/preload/index.ts and typed in src/preload/index.d.ts.

Security model

These three settings are non-negotiable and must never be weakened:

Setting	Value
`contextIsolation`	`true`
`sandbox`	`true`
`nodeIntegration`	`false`

Because the renderer is fully sandboxed, every capability it has is something the preload layer explicitly, and narrowly, exposes.

Main process modules

Module	Responsibility
`index.ts`	App lifecycle, `BrowserWindow`, window-bounds persistence
`fs/service.ts`	Pure fs logic: list, info, create/rename/copy/move/duplicate, folder size, recursive tokenized search
`fs/handlers.ts`	Registers every `ipcMain.handle`; wraps errors into `Result`
`fs/watch.ts`	Single non-recursive `fs.watch` on the focused dir, debounced
`fs/thumbnails.ts`	`nativeImage` thumbnails as data URLs, cached in memory
`db/`	SQLite metadata + AI index (see Data Layer)
`prefs.ts`	Preferences in the SQLite `prefs` table (JSON values)
`ai/`	Embeddings, indexer, search, knowledge graph, and the LLM (see AI Pipeline)

Renderer state

State is React context, no Redux:

state/navigation.tsx — current path, back/forward/up history, sort, view mode, column widths, search query, refresh token (useReducer).
state/clipboard.tsx / state/undo.tsx / state/toast.tsx — copy/cut, the undo stack, and notifications.
hooks/useFileActions.ts — all mutations funnel through here; each runs the IPC call, toasts, refreshes, and pushes an inverse onto the undo stack.
hooks/useTags.ts — all tag mutations funnel through here so the sidebar, dots, menus, and info panel stay in sync.

Page views like Recents, Tag Files, Canvas, and Ask AI are history entries — the toolbar Back/Forward arrows traverse them alongside folders.

Repository layout

src/            The desktop app: Electron main / preload / renderer
  shared/       Types and IPC channel names shared by every layer
  main/         Main process: filesystem, database, and the AI layer
  preload/      contextBridge: the only surface the renderer can call
  renderer/     The React app
docs/           Product docs (Mintlify)
website/        The landing site (Next.js)

The IPC Contract

The Result-typed spine that connects renderer to disk.

Data Layer

SQLite via node:sqlite + Drizzle, with zero native deps.

Get Started

Features

Under the Hood

Resources

The four layers

Security model

Main process modules

Renderer state

Repository layout

Next

The IPC Contract

Data Layer

​The four layers

​Security model

​Main process modules

​Renderer state

​Repository layout

​Next

The IPC Contract

Data Layer

The four layers

Security model

Main process modules

Renderer state

Repository layout

Next