# manjunatha-kv01/ctrlcove architecture

> Architecture diagram of the GitHub repository manjunatha-kv01/ctrlcove, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/manjunatha-kv01/ctrlcove
- Repository: https://github.com/manjunatha-kv01/ctrlcove

## Overview

1. **System shape: a local-first desktop memory platform**
   - CYMOS is a **Tauri v2 desktop app** with a **Rust backend** and **React + TypeScript frontend**.
   - The product boundary is not just the desktop UI: it also includes a **Chrome browser extension** and a **local REST API** for external integrations.

2. **Primary entrypoints and runtime boundaries**
   - `src-tauri/src/main.rs` and `src-tauri/src/lib.rs` define the native application core.
   - `src/main.tsx` mounts the React app, while `src/App.tsx` and the page modules define the user-facing navigation.
   - The browser extension lives under `extensions/browser/` and communicates separately from the desktop UI, likely through the local API or direct capture actions.

3. **Capture layer: how data enters the system**
   - The repo is centered on turning everyday artifacts into “memories”: clipboard content, text selections from the extension, and potentially richer content like images, code, files, and URLs.
   - `src-tauri/src/clipboard.rs` is the native ingestion boundary for clipboard-driven capture.
   - The extension’s `background.js`, `popup.html`, and `popup.js` represent the browser-side capture path.

4. **Persistence layer: local database as the system of record**
   - `src-tauri/src/database.rs` is the main storage boundary.
   - The README indicates **SQLite** is used for clips, metrics, tasks, and related metadata, with local-only persistence as a core design choice.
   - This database is the canonical store feeding history, favorites, tags, statistics, and search experiences in the UI.

5. **AI understanding pipeline: local LLM orchestration**
   - `src-tauri/src/ollama.rs` is the integration point to **Ollama**, which the repo uses for local inference.
   - `src-tauri/src/embeddings.rs` handles embedding generation, with the README specifically calling out `nomic-embed-text`.
   - This layer converts raw captured items into summaries, metadata, keywords, topic labels, and other AI-enriched fields.

6. **Semantic memory and retrieval**
   - The semantic search path is a distinct subsystem, not just a text filter.
   - `src-tauri/src/embeddings.rs` and `src-tauri/src/api.rs` likely support embedding-backed retrieval, similarity lookup, and “similar memories” features.
   - UI components such as `SemanticSearchBar.tsx` and `SimilarMemories.tsx` show that semantic retrieval is a first-class user flow.

7. **Knowledge graph subsystem**
   - `src-tauri/src/graph.rs` is the graph construction and relationship-extraction boundary.
   - The README describes automatic entity/relationship extraction and an interactive graph explorer.
   - This subsystem turns memories into connected nodes/edges for later exploration in the `KnowledgeGraph` page.

8. **Agent layer: specialized task execution**
   - `src-tauri/src/agents.rs` appears to coordinate multiple AI agents for domain-specific tasks.
   - The product positioning includes memory, research, planning, coding, learning, and documentation agents.
   - This is a separate orchestration tier above the core summarization/search pipeline, aimed at multi-step reasoning and task decomposition.

9. **Autonomous background processing**
   - `src-tauri/src/scheduler.rs` is the automation loop for periodic maintenance.
   - The README describes a tokio-based cron-like process that embeds items, extracts graph relationships, processes duplicates, and tracks health metrics.
   - This background engine is what makes the system feel “alive” even when the user is not actively interacting with it.

10. **Local API boundary for external tools**
   - `src-tauri/src/api.rs` is the integration surface for non-desktop clients.
   - The README explicitly calls out a **local REST API on localhost:11435**, intended for IDEs, terminal tooling, and other integrations.
   - This makes CYMOS a platform with a service boundary, not just a standalone GUI app.

11. **Frontend application structure**
   - The React app is organized around functional surfaces rather than a single monolith: dashboard, history, favorites, tags, timeline, statistics, settings, semantic search, knowledge graph, assistant, and agent console.
   - Components like `ClipboardList`, `ClipboardCard`, `SearchBar`, `Sidebar`, `AiStatusBar`, and `ImagePreview` suggest a data-centric UI focused on browsing, filtering, and inspecting captured memories.
   - The frontend is a consumer of backend state rather than the source of truth.

12. **User-facing product surfaces map to backend subsystems**
   - `MemoryAssistant` likely fronts the RAG/chat experience over stored memories.
   - `AgentConsole` and `AutonomousDashboard` map to agents and background automation.
   - `Collections`, `Tags`, `Timeline`, `Statistics`, and `Favorites` are all different projections over the same underlying memory store.

13. **Deployment and platform constraints**
   - The architecture is intentionally **offline-first** and **privacy-first**: local desktop runtime, local DB, local model inference, and no required cloud dependency.
   - Tauri provides the native shell, permissions/capability boundary, and system integration across Windows/macOS/Linux.
   - The browser extension is an auxiliary acquisition layer rather than a separate backend.

14. **Data flow summary**
   - Capture from clipboard/extension/API enters Rust backend.
   - Backend persists to SQLite and enriches items via Ollama and embeddings.
   - Enriched data feeds semantic search, graph extraction, agent workflows, and autonomous maintenance.
   - The React UI renders multiple views over that shared memory store, while external tools can access selected functions via the local REST API.

Main entry points: [`src-tauri/src/lib.rs`](https://github.com/manjunatha-kv01/ctrlcove/blob/main/src-tauri/src/lib.rs) (Core lib), [`src-tauri/src/database.rs`](https://github.com/manjunatha-kv01/ctrlcove/blob/main/src-tauri/src/database.rs) (Database), [`src/App.tsx`](https://github.com/manjunatha-kv01/ctrlcove/blob/main/src/App.tsx) (App shell), [`extensions/browser/background.js`](https://github.com/manjunatha-kv01/ctrlcove/blob/main/extensions/browser/background.js) (Background)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop app"]
  node_main_tsx(("App mount<br/>react entry<br/>[main.tsx]"))
  node_app_tsx["App shell<br/>react shell<br/>[App.tsx]"]
  node_components["UI components<br/>react components"]
  node_dashboard_pages["Views<br/>react pages"]
  node_assistant_pages["Memory surfaces<br/>react pages"]
end

subgraph group_backend["Rust backend"]
  node_src_tauri_main(("Main<br/>tauri entry<br/>[main.rs]"))
  node_src_tauri_lib["Core lib<br/>tauri core<br/>[lib.rs]"]
  node_clipboard["Clipboard<br/>capture<br/>[clipboard.rs]"]
  node_database[("Database<br/>sqlite store<br/>[database.rs]")]
  node_api["Local API<br/>rest api<br/>[api.rs]"]
  node_embeddings["Embeddings<br/>ai pipeline<br/>[embeddings.rs]"]
  node_ollama["Ollama<br/>llm bridge<br/>[ollama.rs]"]
  node_graph{{"Knowledge graph<br/>graph engine<br/>[graph.rs]"}}
  node_agents["Agents<br/>agent orchestration<br/>[agents.rs]"]
  node_scheduler["Scheduler<br/>automation loop<br/>[scheduler.rs]"]
end

subgraph group_extension["Browser extension"]
  node_browser_bg["Background<br/>extension worker<br/>[background.js]"]
  node_browser_popup["Popup UI<br/>extension ui<br/>[popup.html]"]
  node_browser_manifest["Manifest<br/>extension config<br/>[manifest.json]"]
end

node_src_tauri_main -->|"starts"| node_src_tauri_lib
node_src_tauri_lib -->|"captures"| node_clipboard
node_src_tauri_lib -->|"persists"| node_database
node_src_tauri_lib -->|"serves"| node_api
node_src_tauri_lib -->|"enriches"| node_embeddings
node_src_tauri_lib -->|"extracts"| node_graph
node_src_tauri_lib -->|"orchestrates"| node_agents
node_src_tauri_lib -->|"automates"| node_scheduler
node_embeddings -->|"uses"| node_ollama
node_embeddings -->|"indexes"| node_database
node_graph -->|"reads/writes"| node_database
node_agents -->|"reads"| node_database
node_agents -->|"uses"| node_ollama
node_scheduler -->|"triggers"| node_embeddings
node_scheduler -->|"triggers"| node_graph
node_main_tsx -->|"mounts"| node_app_tsx
node_app_tsx -->|"composes"| node_components
node_app_tsx -->|"navigates"| node_dashboard_pages
node_app_tsx -->|"navigates"| node_assistant_pages
node_browser_manifest -->|"loads"| node_browser_bg
node_browser_bg -->|"controls"| node_browser_popup
node_browser_bg -->|"captures"| node_api
node_browser_bg -->|"ingests"| node_database

click node_src_tauri_main "https://github.com/manjunatha-kv01/ctrlcove/blob/main/src-tauri/src/main.rs"
click node_src_tauri_lib "https://github.com/manjunatha-kv01/ctrlcove/blob/main/src-tauri/src/lib.rs"
click node_clipboard "https://github.com/manjunatha-kv01/ctrlcove/blob/main/src-tauri/src/clipboard.rs"
click node_database "https://github.com/manjunatha-kv01/ctrlcove/blob/main/src-tauri/src/database.rs"
click node_api "https://github.com/manjunatha-kv01/ctrlcove/blob/main/src-tauri/src/api.rs"
click node_embeddings "https://github.com/manjunatha-kv01/ctrlcove/blob/main/src-tauri/src/embeddings.rs"
click node_ollama "https://github.com/manjunatha-kv01/ctrlcove/blob/main/src-tauri/src/ollama.rs"
click node_graph "https://github.com/manjunatha-kv01/ctrlcove/blob/main/src-tauri/src/graph.rs"
click node_agents "https://github.com/manjunatha-kv01/ctrlcove/blob/main/src-tauri/src/agents.rs"
click node_scheduler "https://github.com/manjunatha-kv01/ctrlcove/blob/main/src-tauri/src/scheduler.rs"
click node_main_tsx "https://github.com/manjunatha-kv01/ctrlcove/blob/main/src/main.tsx"
click node_app_tsx "https://github.com/manjunatha-kv01/ctrlcove/blob/main/src/App.tsx"
click node_components "https://github.com/manjunatha-kv01/ctrlcove/tree/main/src/components"
click node_dashboard_pages "https://github.com/manjunatha-kv01/ctrlcove/tree/main/src/pages"
click node_assistant_pages "https://github.com/manjunatha-kv01/ctrlcove/tree/main/src/pages"
click node_browser_bg "https://github.com/manjunatha-kv01/ctrlcove/blob/main/extensions/browser/background.js"
click node_browser_popup "https://github.com/manjunatha-kv01/ctrlcove/blob/main/extensions/browser/popup.html"
click node_browser_manifest "https://github.com/manjunatha-kv01/ctrlcove/blob/main/extensions/browser/manifest.json"

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_main_tsx,node_app_tsx,node_components,node_dashboard_pages,node_assistant_pages toneBlue
class node_src_tauri_main,node_src_tauri_lib,node_clipboard,node_database,node_api,node_embeddings,node_ollama,node_graph,node_agents,node_scheduler toneAmber
class node_browser_bg,node_browser_popup,node_browser_manifest toneMint
```

## Components

### Desktop app

Tauri shell plus React UI

- [App mount](https://github.com/manjunatha-kv01/ctrlcove/blob/main/src/main.tsx): react entry · Frontend bootstrap and mount point · `src/main.tsx`
- [App shell](https://github.com/manjunatha-kv01/ctrlcove/blob/main/src/App.tsx): react shell · Top-level navigation and layout · `src/App.tsx`
- [UI components](https://github.com/manjunatha-kv01/ctrlcove/tree/main/src/components): react components · Shared browsing, search, and preview widgets · `src/components`
- [Views](https://github.com/manjunatha-kv01/ctrlcove/tree/main/src/pages): react pages · Dashboard, history, favorites, tags, timeline, stats, settings · `src/pages`
- [Memory surfaces](https://github.com/manjunatha-kv01/ctrlcove/tree/main/src/pages): react pages · Semantic search, assistant, knowledge graph, agents, automation · `src/pages`

### Rust backend

Native capture, storage, AI, and automation

- [Main](https://github.com/manjunatha-kv01/ctrlcove/blob/main/src-tauri/src/main.rs): tauri entry · Native application entrypoint · `src-tauri/src/main.rs`
- [Core lib](https://github.com/manjunatha-kv01/ctrlcove/blob/main/src-tauri/src/lib.rs): tauri core · Tauri command wiring and backend initialization · `src-tauri/src/lib.rs`
- [Clipboard](https://github.com/manjunatha-kv01/ctrlcove/blob/main/src-tauri/src/clipboard.rs): capture · Native clipboard ingestion boundary · `src-tauri/src/clipboard.rs`
- [Database](https://github.com/manjunatha-kv01/ctrlcove/blob/main/src-tauri/src/database.rs): sqlite store · Local system of record for memories and metadata · `src-tauri/src/database.rs`
- [Local API](https://github.com/manjunatha-kv01/ctrlcove/blob/main/src-tauri/src/api.rs): rest api · Local localhost integration surface · `src-tauri/src/api.rs`
- [Embeddings](https://github.com/manjunatha-kv01/ctrlcove/blob/main/src-tauri/src/embeddings.rs): ai pipeline · Embedding generation and semantic indexing · `src-tauri/src/embeddings.rs`
- [Ollama](https://github.com/manjunatha-kv01/ctrlcove/blob/main/src-tauri/src/ollama.rs): llm bridge · Local model inference integration · `src-tauri/src/ollama.rs`
- [Knowledge graph](https://github.com/manjunatha-kv01/ctrlcove/blob/main/src-tauri/src/graph.rs): graph engine · Entity and relationship extraction · `src-tauri/src/graph.rs`
- [Agents](https://github.com/manjunatha-kv01/ctrlcove/blob/main/src-tauri/src/agents.rs): agent orchestration · Specialized task and reasoning coordination · `src-tauri/src/agents.rs`
- [Scheduler](https://github.com/manjunatha-kv01/ctrlcove/blob/main/src-tauri/src/scheduler.rs): automation loop · Periodic background processing and maintenance · `src-tauri/src/scheduler.rs`

### Browser extension

Chrome acquisition surface

- [Background](https://github.com/manjunatha-kv01/ctrlcove/blob/main/extensions/browser/background.js): extension worker · Extension-side capture and coordination · `extensions/browser/background.js`
- [Popup UI](https://github.com/manjunatha-kv01/ctrlcove/blob/main/extensions/browser/popup.html): extension ui · Browser extension popup and controls · `extensions/browser/popup.html`
- [Manifest](https://github.com/manjunatha-kv01/ctrlcove/blob/main/extensions/browser/manifest.json): extension config · Extension runtime and permissions configuration · `extensions/browser/manifest.json`

## Connections

- Main → Core lib: starts · Bootstraps the native app runtime
- Core lib → Clipboard: captures · Routes native clipboard ingestion
- Core lib → Database: persists · Stores captured memories and metadata
- Core lib → Local API: serves · Exposes local REST endpoints
- Core lib → Embeddings: enriches · Generates semantic vectors and metadata
- Core lib → Knowledge graph: extracts · Builds relationship graphs from memories
- Core lib → Agents: orchestrates · Coordinates higher-level agent workflows
- Core lib → Scheduler: automates · Runs periodic background maintenance
- Embeddings → Ollama: uses · Calls local model inference
- Embeddings → Database: indexes · Writes embedding-backed search data
- Knowledge graph → Database: reads/writes · Derives and stores relationships
- Agents → Database: reads · Uses stored memories as task context
- Agents → Ollama: uses · Leverages local LLM capabilities
- Scheduler → Embeddings: triggers · Reprocesses items in the background
- Scheduler → Knowledge graph: triggers · Refreshes relationships asynchronously
- App mount → App shell: mounts · Bootstraps the React application
- App shell → UI components: composes · Uses shared UI widgets
- App shell → Views: navigates · Hosts core browsing and management views
- App shell → Memory surfaces: navigates · Hosts semantic and agent-centric views
- Manifest → Background: loads · Defines the extension runtime
- Background → Popup UI: controls · Coordinates extension UI actions
- Background → Local API: captures · Sends browser-derived data to the local backend
- Background → Database: ingests · Feeds captured content into the local store
