# nkavt/locket architecture

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

- Interactive diagram: https://gitdiagram.com/nkavt/locket
- Repository: https://github.com/nkavt/locket

## Overview

Locket is a local-first desktop planner: people organize projects and tickets, add comments and images, and keep the workspace in a local SQLite database. The renderer presents project, ticket, and settings routes; its state layer selects the Electron bridge or local-storage backend. In the desktop runtime, Electron exposes data operations over IPC and shares services with the built-in MCP server, allowing agents to work on the same workspace. The README documents the major capabilities; some feature implementations and IPC wiring were not sampled, so those links are documented rather than inferred from module names.

Main entry points: [`src/state/useAppStateStore.ts`](https://github.com/nkavt/locket/blob/main/src/state/useAppStateStore.ts) (Workspace state), [`electron/services`](https://github.com/nkavt/locket/tree/main/electron/services) (Workspace services), [`electron/mcp/http.ts`](https://github.com/nkavt/locket/blob/main/electron/mcp/http.ts) (MCP HTTP host), [`electron/main.ts`](https://github.com/nkavt/locket/blob/main/electron/main.ts) (Electron main)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_renderer["Desktop interface"]
  node_routes["App routes<br/>[router.tsx]"]
  node_state["Workspace state"]
  node_backend["Data backends<br/>[backend.ts]"]
end

subgraph group_domain["Workspace features"]
  node_project_ui["Projects UI"]
  node_ticket_ui["Tickets UI"]
  node_comments_ui["Comments UI"]
  node_images_ui["Image attachments"]
  node_settings_ui["Settings UI"]
end

subgraph group_runtime["Electron runtime"]
  node_main["Electron main<br/>[main.ts]"]
  node_ipc["Data IPC<br/>[data.ts]"]
  node_services["Workspace services"]
  node_attachment_service["Attachment service<br/>[attachments.ts]"]
  node_tray["Menu bar controls<br/>[index.ts]"]
end

subgraph group_storage["Local persistence"]
  node_file_store["Image file store<br/>[store.ts]"]
  node_database[("SQLite workspace")]
end

subgraph group_agents["Agent access"]
  node_mcp_host["MCP HTTP host<br/>[http.ts]"]
  node_mcp_server["MCP server<br/>[server.ts]"]
  node_mcp_tools["Project and ticket tools"]
  node_mcp_resources["MCP resources<br/>[resources.ts]"]
end

node_person(("Person"))
node_agent(("MCP agent"))

node_person -->|"uses"| node_routes
node_routes -.->|"reads workspace"| node_state
node_state -->|"selects backend"| node_backend
node_backend -.->|"uses Electron bridge"| node_ipc
node_state -.->|"serves project state"| node_project_ui
node_state -.->|"serves ticket state"| node_ticket_ui
node_state -.->|"serves comment state"| node_comments_ui
node_state -.->|"serves attachment state"| node_images_ui
node_state -.->|"serves settings"| node_settings_ui
node_main -->|"registers handlers"| node_ipc
node_ipc -->|"delegates data operations"| node_services
node_services -->|"reads and writes"| node_database
node_services -->|"exports attachment operations"| node_attachment_service
node_attachment_service -.->|"manages image files"| node_file_store
node_main -->|"initializes"| node_database
node_main -->|"creates host"| node_mcp_host
node_mcp_host -->|"serves MCP requests"| node_mcp_server
node_mcp_server -->|"registers tools"| node_mcp_tools
node_mcp_server -->|"registers resources"| node_mcp_resources
node_mcp_tools -->|"uses shared services"| node_services
node_agent -->|"sends MCP requests"| node_mcp_host
node_mcp_host -->|"status controls"| node_tray
node_person -->|"controls server"| node_tray

click node_routes "https://github.com/nkavt/locket/blob/main/src/router.tsx"
click node_state "https://github.com/nkavt/locket/blob/main/src/state/useAppStateStore.ts"
click node_backend "https://github.com/nkavt/locket/blob/main/src/state/backend.ts"
click node_project_ui "https://github.com/nkavt/locket/tree/main/src/features/projects"
click node_ticket_ui "https://github.com/nkavt/locket/tree/main/src/features/tickets"
click node_comments_ui "https://github.com/nkavt/locket/tree/main/src/features/comments"
click node_images_ui "https://github.com/nkavt/locket/tree/main/src/features/attachments"
click node_settings_ui "https://github.com/nkavt/locket/tree/main/src/features/settings"
click node_main "https://github.com/nkavt/locket/blob/main/electron/main.ts"
click node_ipc "https://github.com/nkavt/locket/blob/main/electron/ipc/data.ts"
click node_services "https://github.com/nkavt/locket/tree/main/electron/services"
click node_attachment_service "https://github.com/nkavt/locket/blob/main/electron/services/attachments.ts"
click node_file_store "https://github.com/nkavt/locket/blob/main/electron/attachments/store.ts"
click node_database "https://github.com/nkavt/locket/tree/main/electron/db"
click node_mcp_host "https://github.com/nkavt/locket/blob/main/electron/mcp/http.ts"
click node_mcp_server "https://github.com/nkavt/locket/blob/main/electron/mcp/server.ts"
click node_mcp_tools "https://github.com/nkavt/locket/tree/main/electron/mcp/tools"
click node_mcp_resources "https://github.com/nkavt/locket/blob/main/electron/mcp/resources.ts"
click node_tray "https://github.com/nkavt/locket/blob/main/electron/tray/index.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_routes,node_state,node_backend toneBlue
class node_project_ui,node_ticket_ui,node_comments_ui,node_images_ui,node_settings_ui toneAmber
class node_main,node_ipc,node_services,node_attachment_service,node_tray toneMint
class node_file_store,node_database toneRose
class node_mcp_host,node_mcp_server,node_mcp_tools,node_mcp_resources,node_person,node_agent toneIndigo
```

## Components

### Desktop interface

- [App routes](https://github.com/nkavt/locket/blob/main/src/router.tsx): `src/router.tsx`
- [Workspace state](https://github.com/nkavt/locket/blob/main/src/state/useAppStateStore.ts): `src/state/useAppStateStore.ts`
- [Data backends](https://github.com/nkavt/locket/blob/main/src/state/backend.ts): `src/state/backend.ts`

### Workspace features

- [Projects UI](https://github.com/nkavt/locket/tree/main/src/features/projects): `src/features/projects`
- [Tickets UI](https://github.com/nkavt/locket/tree/main/src/features/tickets): `src/features/tickets`
- [Comments UI](https://github.com/nkavt/locket/tree/main/src/features/comments): `src/features/comments`
- [Image attachments](https://github.com/nkavt/locket/tree/main/src/features/attachments): `src/features/attachments`
- [Settings UI](https://github.com/nkavt/locket/tree/main/src/features/settings): `src/features/settings`

### Electron runtime

- [Electron main](https://github.com/nkavt/locket/blob/main/electron/main.ts): `electron/main.ts`
- [Data IPC](https://github.com/nkavt/locket/blob/main/electron/ipc/data.ts): `electron/ipc/data.ts`
- [Workspace services](https://github.com/nkavt/locket/tree/main/electron/services): `electron/services`
- [Attachment service](https://github.com/nkavt/locket/blob/main/electron/services/attachments.ts): `electron/services/attachments.ts`
- [Menu bar controls](https://github.com/nkavt/locket/blob/main/electron/tray/index.ts): `electron/tray/index.ts`

### Local persistence

- [Image file store](https://github.com/nkavt/locket/blob/main/electron/attachments/store.ts): `electron/attachments/store.ts`
- [SQLite workspace](https://github.com/nkavt/locket/tree/main/electron/db): `electron/db`

### Agent access

- [MCP HTTP host](https://github.com/nkavt/locket/blob/main/electron/mcp/http.ts): `electron/mcp/http.ts`
- [MCP server](https://github.com/nkavt/locket/blob/main/electron/mcp/server.ts): `electron/mcp/server.ts`
- [Project and ticket tools](https://github.com/nkavt/locket/tree/main/electron/mcp/tools): `electron/mcp/tools`
- [MCP resources](https://github.com/nkavt/locket/blob/main/electron/mcp/resources.ts): `electron/mcp/resources.ts`

### Other components

- **Person**
- **MCP agent**

## Connections

- Person → App routes: uses (evidence: `README.md`)
- App routes → Workspace state: reads workspace
- Workspace state → Data backends: selects backend (evidence: `src/state/useAppStateStore.ts`)
- Data backends → Data IPC: uses Electron bridge
- Workspace state → Projects UI: serves project state
- Workspace state → Tickets UI: serves ticket state
- Workspace state → Comments UI: serves comment state
- Workspace state → Image attachments: serves attachment state
- Workspace state → Settings UI: serves settings
- Electron main → Data IPC: registers handlers (evidence: `electron/main.ts`)
- Data IPC → Workspace services: delegates data operations (evidence: `electron/ipc/data.ts`)
- Workspace services → SQLite workspace: reads and writes (evidence: `electron/services/projects.ts`)
- Workspace services → Attachment service: exports attachment operations (evidence: `electron/services/index.ts`)
- Attachment service → Image file store: manages image files
- Electron main → SQLite workspace: initializes (evidence: `electron/main.ts`)
- Electron main → MCP HTTP host: creates host (evidence: `electron/main.ts`)
- MCP HTTP host → MCP server: serves MCP requests (evidence: `electron/mcp/http.ts`)
- MCP server → Project and ticket tools: registers tools (evidence: `electron/mcp/server.ts`)
- MCP server → MCP resources: registers resources (evidence: `electron/mcp/server.ts`)
- Project and ticket tools → Workspace services: uses shared services (evidence: `electron/mcp/tools/tickets.ts`)
- MCP agent → MCP HTTP host: sends MCP requests (evidence: `README.md`)
- MCP HTTP host → Menu bar controls: status controls (evidence: `electron/tray/index.ts`)
- Person → Menu bar controls: controls server (evidence: `electron/tray/index.ts`)
