# synvo-ai/local-cocoa architecture

> Architecture diagram of the GitHub repository synvo-ai/local-cocoa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/synvo-ai/local-cocoa
- Repository: https://github.com/synvo-ai/local-cocoa

## Overview

Local Cocoa is an on-device personal knowledge and AI assistant built as an Electron/React application with a documented FastAPI backend. The main user workflow is to select local folders for indexing, then ask questions or search across indexed content and review grounded results. The UI also exposes model setup, scanning and reports, notes, email, and MCP/plugin features. Backend implementation is not in the supplied tree; backend capabilities and ingestion/retrieval stages below are documented in the README, not verified from backend source.

Main entry points: [`src/renderer/components/MainAppView.tsx`](https://github.com/synvo-ai/local-cocoa/blob/main/src/renderer/components/MainAppView.tsx) (Main workspace), [`src/renderer/components/PluginWebview.tsx`](https://github.com/synvo-ai/local-cocoa/blob/main/src/renderer/components/PluginWebview.tsx) (Plugin UI), [`src/preload/preload.ts`](https://github.com/synvo-ai/local-cocoa/blob/main/src/preload/preload.ts) (Renderer API bridge), [`src/renderer/App.tsx`](https://github.com/synvo-ai/local-cocoa/blob/main/src/renderer/App.tsx) (App routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Desktop experience"]
  node_app["App routing<br/>[App.tsx]"]
  node_mainview["Main workspace<br/>[MainAppView.tsx]"]
  node_chat["Chat session<br/>[useChatSession.ts]"]
  node_quicksearch["Quick search"]
  node_retrieval["Retrieval results<br/>[RetrievalPanel.tsx]"]
  node_setup["Model setup<br/>[WelcomeSetup.tsx]"]
end

subgraph group_knowledge["Knowledge workflow"]
  node_knowledgebase[("Semantic memory")]
end

subgraph group_runtime["Local runtime"]
  node_ipcbridge["Renderer API bridge<br/>[preload.ts]"]
  node_fileipc["File operations<br/>[files.ts]"]
  node_scanipc["Scan operations<br/>[scan.ts]"]
  node_backendclient["Backend client<br/>[backendClient.ts]"]
  node_backend["Local AI backend"]
  node_models["Model management<br/>[modelManager.ts]"]
end

subgraph group_extensions["Extensions"]
  node_pluginmanager["Plugin lifecycle<br/>[pluginManager.ts]"]
  node_pluginui["Plugin UI<br/>[PluginWebview.tsx]"]
  node_email["Email plugin<br/>[EmailQAPage.tsx]"]
  node_notes["Notes workspace<br/>[NotesWorkspace.tsx]"]
  node_mcp["MCP integration<br/>[entry.ts]"]
end

subgraph group_insights["Scanning and insights"]
  node_scanview["Scan workspace<br/>[ScanWorkspace.tsx]"]
  node_yearreview["Year in Review"]
end

node_user(("User"))

node_user -->|"opens"| node_app
node_app -->|"routes to"| node_mainview
node_app -->|"routes to"| node_quicksearch
node_user -.->|"uses"| node_mainview
node_mainview -.->|"hosts chat"| node_chat
node_chat -.->|"calls window.api"| node_ipcbridge
node_quicksearch -.->|"searches through"| node_ipcbridge
node_ipcbridge -.->|"dispatches IPC"| node_fileipc
node_ipcbridge -.->|"dispatches IPC"| node_scanipc
node_fileipc -.->|"requests backend"| node_backendclient
node_scanipc -.->|"requests backend"| node_backendclient
node_backendclient -->|"calls local API"| node_backend
node_backend -->|"indexes and retrieves"| node_knowledgebase
node_backend -.->|"uses local models"| node_models
node_chat -.->|"shows results"| node_retrieval
node_setup -.->|"configures"| node_models
node_mainview -.->|"offers extensions"| node_pluginui
node_pluginmanager -->|"registers UI"| node_pluginui
node_pluginui -.->|"renders plugin"| node_email
node_pluginui -.->|"renders plugin"| node_notes
node_pluginui -.->|"hosts integration"| node_mcp
node_email -.->|"indexes mail"| node_knowledgebase
node_notes -.->|"adds note memory"| node_knowledgebase
node_mainview -.->|"offers scanning"| node_scanview
node_scanview -.->|"requests scans"| node_scanipc
node_scanview -.->|"opens report"| node_yearreview
node_yearreview -.->|"uses indexed content"| node_knowledgebase

click node_app "https://github.com/synvo-ai/local-cocoa/blob/main/src/renderer/App.tsx"
click node_mainview "https://github.com/synvo-ai/local-cocoa/blob/main/src/renderer/components/MainAppView.tsx"
click node_chat "https://github.com/synvo-ai/local-cocoa/blob/main/src/renderer/hooks/useChatSession.ts"
click node_quicksearch "https://github.com/synvo-ai/local-cocoa/blob/main/src/renderer/components/QuickSearchShell.tsx"
click node_retrieval "https://github.com/synvo-ai/local-cocoa/blob/main/src/renderer/components/RetrievalPanel.tsx"
click node_ipcbridge "https://github.com/synvo-ai/local-cocoa/blob/main/src/preload/preload.ts"
click node_fileipc "https://github.com/synvo-ai/local-cocoa/blob/main/src/main/ipc/files.ts"
click node_scanipc "https://github.com/synvo-ai/local-cocoa/blob/main/src/main/ipc/scan.ts"
click node_backendclient "https://github.com/synvo-ai/local-cocoa/blob/main/src/main/backendClient.ts"
click node_models "https://github.com/synvo-ai/local-cocoa/blob/main/src/main/modelManager.ts"
click node_setup "https://github.com/synvo-ai/local-cocoa/blob/main/src/renderer/components/WelcomeSetup.tsx"
click node_pluginmanager "https://github.com/synvo-ai/local-cocoa/blob/main/src/main/plugins/pluginManager.ts"
click node_pluginui "https://github.com/synvo-ai/local-cocoa/blob/main/src/renderer/components/PluginWebview.tsx"
click node_email "https://github.com/synvo-ai/local-cocoa/blob/main/plugins/synvo_ai_mail/frontend/renderer/EmailQAPage.tsx"
click node_notes "https://github.com/synvo-ai/local-cocoa/blob/main/plugins/synvo_ai_notes/frontend/renderer/NotesWorkspace.tsx"
click node_mcp "https://github.com/synvo-ai/local-cocoa/blob/main/plugins/synvo_ai_mcp/frontend/entry.ts"
click node_scanview "https://github.com/synvo-ai/local-cocoa/blob/main/src/renderer/components/ScanWorkspace.tsx"
click node_yearreview "https://github.com/synvo-ai/local-cocoa/blob/main/src/renderer/components/YearInReviewModal.tsx"

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_app,node_mainview,node_chat,node_quicksearch,node_retrieval,node_setup,node_user toneBlue
class node_knowledgebase toneAmber
class node_ipcbridge,node_fileipc,node_scanipc,node_backendclient,node_backend,node_models toneMint
class node_pluginmanager,node_pluginui,node_email,node_notes,node_mcp toneRose
class node_scanview,node_yearreview toneIndigo
```

## Components

### Desktop experience

- [App routing](https://github.com/synvo-ai/local-cocoa/blob/main/src/renderer/App.tsx): `src/renderer/App.tsx`
- [Main workspace](https://github.com/synvo-ai/local-cocoa/blob/main/src/renderer/components/MainAppView.tsx): `src/renderer/components/MainAppView.tsx`
- [Chat session](https://github.com/synvo-ai/local-cocoa/blob/main/src/renderer/hooks/useChatSession.ts): `src/renderer/hooks/useChatSession.ts`
- [Quick search](https://github.com/synvo-ai/local-cocoa/blob/main/src/renderer/components/QuickSearchShell.tsx): `src/renderer/components/QuickSearchShell.tsx`
- [Retrieval results](https://github.com/synvo-ai/local-cocoa/blob/main/src/renderer/components/RetrievalPanel.tsx): `src/renderer/components/RetrievalPanel.tsx`
- [Model setup](https://github.com/synvo-ai/local-cocoa/blob/main/src/renderer/components/WelcomeSetup.tsx): `src/renderer/components/WelcomeSetup.tsx`

### Knowledge workflow

- **Semantic memory**

### Local runtime

- [Renderer API bridge](https://github.com/synvo-ai/local-cocoa/blob/main/src/preload/preload.ts): `src/preload/preload.ts`
- [File operations](https://github.com/synvo-ai/local-cocoa/blob/main/src/main/ipc/files.ts): `src/main/ipc/files.ts`
- [Scan operations](https://github.com/synvo-ai/local-cocoa/blob/main/src/main/ipc/scan.ts): `src/main/ipc/scan.ts`
- [Backend client](https://github.com/synvo-ai/local-cocoa/blob/main/src/main/backendClient.ts): `src/main/backendClient.ts`
- **Local AI backend**
- [Model management](https://github.com/synvo-ai/local-cocoa/blob/main/src/main/modelManager.ts): `src/main/modelManager.ts`

### Extensions

- [Plugin lifecycle](https://github.com/synvo-ai/local-cocoa/blob/main/src/main/plugins/pluginManager.ts): `src/main/plugins/pluginManager.ts`
- [Plugin UI](https://github.com/synvo-ai/local-cocoa/blob/main/src/renderer/components/PluginWebview.tsx): `src/renderer/components/PluginWebview.tsx`
- [Email plugin](https://github.com/synvo-ai/local-cocoa/blob/main/plugins/synvo_ai_mail/frontend/renderer/EmailQAPage.tsx): `plugins/synvo_ai_mail/frontend/renderer/EmailQAPage.tsx`
- [Notes workspace](https://github.com/synvo-ai/local-cocoa/blob/main/plugins/synvo_ai_notes/frontend/renderer/NotesWorkspace.tsx): `plugins/synvo_ai_notes/frontend/renderer/NotesWorkspace.tsx`
- [MCP integration](https://github.com/synvo-ai/local-cocoa/blob/main/plugins/synvo_ai_mcp/frontend/entry.ts): `plugins/synvo_ai_mcp/frontend/entry.ts`

### Scanning and insights

- [Scan workspace](https://github.com/synvo-ai/local-cocoa/blob/main/src/renderer/components/ScanWorkspace.tsx): `src/renderer/components/ScanWorkspace.tsx`
- [Year in Review](https://github.com/synvo-ai/local-cocoa/blob/main/src/renderer/components/YearInReviewModal.tsx): `src/renderer/components/YearInReviewModal.tsx`

### Other components

- **User**

## Connections

- User → App routing: opens (evidence: `src/renderer/App.tsx`)
- App routing → Main workspace: routes to (evidence: `src/renderer/App.tsx`)
- App routing → Quick search: routes to (evidence: `src/renderer/App.tsx`)
- User → Main workspace: uses (evidence: `README.md`)
- Main workspace → Chat session: hosts chat
- Chat session → Renderer API bridge: calls window.api
- Quick search → Renderer API bridge: searches through
- Renderer API bridge → File operations: dispatches IPC
- Renderer API bridge → Scan operations: dispatches IPC
- File operations → Backend client: requests backend
- Scan operations → Backend client: requests backend
- Backend client → Local AI backend: calls local API (evidence: `README.md`)
- Local AI backend → Semantic memory: indexes and retrieves (evidence: `README.md`)
- Local AI backend → Model management: uses local models
- Chat session → Retrieval results: shows results
- Model setup → Model management: configures
- Main workspace → Plugin UI: offers extensions
- Plugin lifecycle → Plugin UI: registers UI (evidence: `src/main/plugins/pluginManager.ts`)
- Plugin UI → Email plugin: renders plugin
- Plugin UI → Notes workspace: renders plugin
- Plugin UI → MCP integration: hosts integration
- Email plugin → Semantic memory: indexes mail (evidence: `README.md`)
- Notes workspace → Semantic memory: adds note memory (evidence: `README.md`)
- Main workspace → Scan workspace: offers scanning
- Scan workspace → Scan operations: requests scans
- Scan workspace → Year in Review: opens report
- Year in Review → Semantic memory: uses indexed content
