# layernorm/overlay-desktop architecture

> Architecture diagram of the GitHub repository layernorm/overlay-desktop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/layernorm/overlay-desktop
- Repository: https://github.com/layernorm/overlay-desktop

## Overview

Overlay Desktop is a macOS desktop client for chat, voice input, notes, files, and permissioned agent operations. A user works in the renderer; the preload bridge exposes desktop capabilities to the main process, which owns host operations and coordinates local or server-backed services. A central agent-policy layer checks tool authorization and approval requirements. Other major branches include browser sessions, notebook and knowledge management, transcription, account and billing, and hosted AI. The README documents product boundaries; sampled source confirms selected internals, so uncertain module-to-module wiring is omitted.

Main entry points: [`src/preload/index.ts`](https://github.com/layernorm/overlay-desktop/blob/main/src/preload/index.ts) (Preload bridge), [`src/main/ipc/chat-ipc.ts`](https://github.com/layernorm/overlay-desktop/blob/main/src/main/ipc/chat-ipc.ts) (Chat IPC), [`src/main/services/chat-service.ts`](https://github.com/layernorm/overlay-desktop/blob/main/src/main/services/chat-service.ts) (Chat service), [`src/main/services/agent/agent-service.ts`](https://github.com/layernorm/overlay-desktop/blob/main/src/main/services/agent/agent-service.ts) (Agent service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Desktop interface"]
  node_renderer["React renderer<br/>[App.tsx]"]
  node_notebook["Notebook UI<br/>[notes.tsx]"]
  node_notebookcontroller["Notebook editor"]
  node_browserui["Browser interface<br/>[BrowserPanel.tsx]"]
end

subgraph group_runtime["Electron runtime"]
  node_preload["Preload bridge<br/>[index.ts]"]
  node_main["Main process<br/>[index.ts]"]
  node_chatipc["Chat IPC<br/>[chat-ipc.ts]"]
  node_agentipc["Agent IPC<br/>[agent-ipc.ts]"]
  node_knowledgeipc["Knowledge IPC<br/>[knowledge-ipc.ts]"]
end

subgraph group_intelligence["Chat and knowledge"]
  node_chatservice["Chat service<br/>[chat-service.ts]"]
  node_unifiedchat["Unified chat"]
  node_gateway["LLM gateway<br/>[index.ts]"]
  node_context["Context engine<br/>[ContextEngine.ts]"]
  node_memory["Cloud memory"]
  node_ingestion["Document ingestion"]
end

subgraph group_host["Host capabilities"]
  node_browser["Browser manager<br/>[browser-manager.ts]"]
  node_policy["Agent policy"]
  node_agent["Agent service<br/>[agent-service.ts]"]
  node_approval["Native approval"]
  node_transcription["Transcription service"]
  node_parakeet["Parakeet engine"]
end

subgraph group_account["Account services"]
  node_account["Account and billing"]
  node_securestorage[("Secure storage")]
end

node_user(("Desktop user"))
node_server{{"Overlay Server"}}

node_user -->|"uses"| node_renderer
node_renderer -->|"requests capabilities"| node_preload
node_preload -->|"bridges IPC"| node_main
node_main -->|"dispatches"| node_chatipc
node_chatipc -->|"handles chat"| node_chatservice
node_chatservice -->|"requests responses"| node_unifiedchat
node_unifiedchat -->|"routes model requests"| node_gateway
node_gateway -->|"connects hosted models"| node_server
node_chatservice -->|"builds context"| node_context
node_context -->|"retrieves memories"| node_memory
node_user -->|"edits notes"| node_notebook
node_notebook -->|"updates editor state"| node_notebookcontroller
node_preload -->|"bridges knowledge IPC"| node_knowledgeipc
node_knowledgeipc -->|"imports documents"| node_ingestion
node_user -->|"browses"| node_browserui
node_browserui -->|"controls browser"| node_browser
node_chatipc -->|"invokes agent operations"| node_agent
node_agent -->|"checks tool access"| node_policy
node_agent -->|"requests approval"| node_approval
node_user -->|"provides voice input"| node_transcription
node_transcription -.->|"transcribes locally"| node_parakeet
node_user -->|"manages account"| node_account
node_account -->|"checks account and entitlements"| node_server
node_account -->|"stores session secrets"| node_securestorage

click node_renderer "https://github.com/layernorm/overlay-desktop/blob/main/src/renderer/src/App.tsx"
click node_preload "https://github.com/layernorm/overlay-desktop/blob/main/src/preload/index.ts"
click node_main "https://github.com/layernorm/overlay-desktop/blob/main/src/main/index.ts"
click node_chatipc "https://github.com/layernorm/overlay-desktop/blob/main/src/main/ipc/chat-ipc.ts"
click node_agentipc "https://github.com/layernorm/overlay-desktop/blob/main/src/main/ipc/agent-ipc.ts"
click node_chatservice "https://github.com/layernorm/overlay-desktop/blob/main/src/main/services/chat-service.ts"
click node_unifiedchat "https://github.com/layernorm/overlay-desktop/blob/main/src/main/services/ai/unified-chat-service.ts"
click node_gateway "https://github.com/layernorm/overlay-desktop/blob/main/packages/overlay-llm-gateway/src/index.ts"
click node_context "https://github.com/layernorm/overlay-desktop/blob/main/src/main/services/context/ContextEngine.ts"
click node_memory "https://github.com/layernorm/overlay-desktop/blob/main/src/main/services/memory/CloudMemoryService.ts"
click node_ingestion "https://github.com/layernorm/overlay-desktop/blob/main/src/main/services/memory/DocumentIngestionService.ts"
click node_notebook "https://github.com/layernorm/overlay-desktop/blob/main/packages/overlay-modules-react/src/notes.tsx"
click node_notebookcontroller "https://github.com/layernorm/overlay-desktop/blob/main/packages/overlay-app-core/src/notebook-editor-controller.ts"
click node_knowledgeipc "https://github.com/layernorm/overlay-desktop/blob/main/src/main/ipc/knowledge-ipc.ts"
click node_browserui "https://github.com/layernorm/overlay-desktop/blob/main/src/renderer/src/components/browser/BrowserPanel.tsx"
click node_browser "https://github.com/layernorm/overlay-desktop/blob/main/src/main/services/browser-manager.ts"
click node_policy "https://github.com/layernorm/overlay-desktop/blob/main/src/main/services/security/agent-policy/agent-policy-engine.ts"
click node_agent "https://github.com/layernorm/overlay-desktop/blob/main/src/main/services/agent/agent-service.ts"
click node_approval "https://github.com/layernorm/overlay-desktop/blob/main/src/main/services/security/agent-policy/approval-coordinator.ts"
click node_transcription "https://github.com/layernorm/overlay-desktop/blob/main/src/main/services/transcription-request.ts"
click node_parakeet "https://github.com/layernorm/overlay-desktop/blob/main/ParakeetServer/Sources/ParakeetCore/ParakeetEngine.swift"
click node_account "https://github.com/layernorm/overlay-desktop/blob/main/src/main/services/subscription-service.ts"
click node_securestorage "https://github.com/layernorm/overlay-desktop/blob/main/src/main/services/security/safe-storage-service.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_renderer,node_notebook,node_notebookcontroller,node_browserui,node_user toneBlue
class node_preload,node_main,node_chatipc,node_agentipc,node_knowledgeipc toneAmber
class node_chatservice,node_unifiedchat,node_gateway,node_context,node_memory,node_ingestion,node_server toneMint
class node_browser,node_policy,node_agent,node_approval,node_transcription,node_parakeet toneRose
class node_account,node_securestorage toneIndigo
```

## Components

### Desktop interface

- [React renderer](https://github.com/layernorm/overlay-desktop/blob/main/src/renderer/src/App.tsx): `src/renderer/src/App.tsx`
- [Notebook UI](https://github.com/layernorm/overlay-desktop/blob/main/packages/overlay-modules-react/src/notes.tsx): `packages/overlay-modules-react/src/notes.tsx`
- [Notebook editor](https://github.com/layernorm/overlay-desktop/blob/main/packages/overlay-app-core/src/notebook-editor-controller.ts): `packages/overlay-app-core/src/notebook-editor-controller.ts`
- [Browser interface](https://github.com/layernorm/overlay-desktop/blob/main/src/renderer/src/components/browser/BrowserPanel.tsx): `src/renderer/src/components/browser/BrowserPanel.tsx`

### Electron runtime

- [Preload bridge](https://github.com/layernorm/overlay-desktop/blob/main/src/preload/index.ts): `src/preload/index.ts`
- [Main process](https://github.com/layernorm/overlay-desktop/blob/main/src/main/index.ts): `src/main/index.ts`
- [Chat IPC](https://github.com/layernorm/overlay-desktop/blob/main/src/main/ipc/chat-ipc.ts): `src/main/ipc/chat-ipc.ts`
- [Agent IPC](https://github.com/layernorm/overlay-desktop/blob/main/src/main/ipc/agent-ipc.ts): `src/main/ipc/agent-ipc.ts`
- [Knowledge IPC](https://github.com/layernorm/overlay-desktop/blob/main/src/main/ipc/knowledge-ipc.ts): `src/main/ipc/knowledge-ipc.ts`

### Chat and knowledge

- [Chat service](https://github.com/layernorm/overlay-desktop/blob/main/src/main/services/chat-service.ts): `src/main/services/chat-service.ts`
- [Unified chat](https://github.com/layernorm/overlay-desktop/blob/main/src/main/services/ai/unified-chat-service.ts): `src/main/services/ai/unified-chat-service.ts`
- [LLM gateway](https://github.com/layernorm/overlay-desktop/blob/main/packages/overlay-llm-gateway/src/index.ts): `packages/overlay-llm-gateway/src/index.ts`
- [Context engine](https://github.com/layernorm/overlay-desktop/blob/main/src/main/services/context/ContextEngine.ts): `src/main/services/context/ContextEngine.ts`
- [Cloud memory](https://github.com/layernorm/overlay-desktop/blob/main/src/main/services/memory/CloudMemoryService.ts): `src/main/services/memory/CloudMemoryService.ts`
- [Document ingestion](https://github.com/layernorm/overlay-desktop/blob/main/src/main/services/memory/DocumentIngestionService.ts): `src/main/services/memory/DocumentIngestionService.ts`

### Host capabilities

- [Browser manager](https://github.com/layernorm/overlay-desktop/blob/main/src/main/services/browser-manager.ts): `src/main/services/browser-manager.ts`
- [Agent policy](https://github.com/layernorm/overlay-desktop/blob/main/src/main/services/security/agent-policy/agent-policy-engine.ts): `src/main/services/security/agent-policy/agent-policy-engine.ts`
- [Agent service](https://github.com/layernorm/overlay-desktop/blob/main/src/main/services/agent/agent-service.ts): `src/main/services/agent/agent-service.ts`
- [Native approval](https://github.com/layernorm/overlay-desktop/blob/main/src/main/services/security/agent-policy/approval-coordinator.ts): `src/main/services/security/agent-policy/approval-coordinator.ts`
- [Transcription service](https://github.com/layernorm/overlay-desktop/blob/main/src/main/services/transcription-request.ts): `src/main/services/transcription-request.ts`
- [Parakeet engine](https://github.com/layernorm/overlay-desktop/blob/main/ParakeetServer/Sources/ParakeetCore/ParakeetEngine.swift): `ParakeetServer/Sources/ParakeetCore/ParakeetEngine.swift`

### Account services

- [Account and billing](https://github.com/layernorm/overlay-desktop/blob/main/src/main/services/subscription-service.ts): `src/main/services/subscription-service.ts`
- [Secure storage](https://github.com/layernorm/overlay-desktop/blob/main/src/main/services/security/safe-storage-service.ts): `src/main/services/security/safe-storage-service.ts`

### Other components

- **Desktop user**
- **Overlay Server**

## Connections

- Desktop user → React renderer: uses
- React renderer → Preload bridge: requests capabilities
- Preload bridge → Main process: bridges IPC
- Main process → Chat IPC: dispatches
- Chat IPC → Chat service: handles chat
- Chat service → Unified chat: requests responses
- Unified chat → LLM gateway: routes model requests
- LLM gateway → Overlay Server: connects hosted models
- Chat service → Context engine: builds context
- Context engine → Cloud memory: retrieves memories
- Desktop user → Notebook UI: edits notes
- Notebook UI → Notebook editor: updates editor state
- Preload bridge → Knowledge IPC: bridges knowledge IPC
- Knowledge IPC → Document ingestion: imports documents
- Desktop user → Browser interface: browses
- Browser interface → Browser manager: controls browser
- Chat IPC → Agent service: invokes agent operations
- Agent service → Agent policy: checks tool access
- Agent service → Native approval: requests approval
- Desktop user → Transcription service: provides voice input
- Transcription service → Parakeet engine: transcribes locally
- Desktop user → Account and billing: manages account
- Account and billing → Overlay Server: checks account and entitlements
- Account and billing → Secure storage: stores session secrets