# tommy0103/obelisk architecture

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

- Interactive diagram: https://gitdiagram.com/tommy0103/obelisk
- Repository: https://github.com/tommy0103/obelisk

## Overview

Obelisk turns local coding-agent histories into a shared SQLite index, then serves it to two audiences: agents query it through the CLI, while people browse it in the Electron app. The indexing path normalizes provider-specific data before persistence; the read path supports search, SQL, memories, and session details. The app adds session, memory, activity, recap, settings, and update experiences. A separate DeepSeek Harness plugin manages context-window handoffs. Some app wiring and several capabilities are documented but their implementation was not sampled, so those links are marked as documented or left unconnected.

Main entry points: [`app/src/renderer/src/router.js`](https://github.com/tommy0103/obelisk/blob/main/app/src/renderer/src/router.js) (View router), [`packages/core/src/core.ts`](https://github.com/tommy0103/obelisk/blob/main/packages/core/src/core.ts) (Core indexing), [`app/src/main/indexer-service.ts`](https://github.com/tommy0103/obelisk/blob/main/app/src/main/indexer-service.ts) (Index service), [`packages/cli/src/obelisk.ts`](https://github.com/tommy0103/obelisk/blob/main/packages/cli/src/obelisk.ts) (Obelisk CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_indexing["Indexing and storage"]
  node_index_service["Index service<br/>[indexer-service.ts]"]
  node_watcher["Adaptive watcher<br/>[index.ts]"]
  node_core["Core indexing<br/>[core.ts]"]
  node_parsing["Provider parsing<br/>[parsing.ts]"]
  node_providers["Provider adapters"]
  node_sqlite[("SQLite index<br/>[db.ts]")]
end

subgraph group_agent["Agent queries"]
  node_cli["Obelisk CLI<br/>[obelisk.ts]"]
  node_query["Query and attune<br/>[query.ts]"]
end

subgraph group_desktop["Desktop browsing"]
  node_desktop_app["Desktop shell<br/>[App.vue]"]
  node_renderer_entry["Renderer entry<br/>[main.js]"]
  node_router["View router<br/>[router.js]"]
  node_session_views["Session browsing<br/>[SessionDetail.vue]"]
  node_renderer_data["Renderer data<br/>[data.js]"]
  node_renderer_store["Shared UI state<br/>[store.js]"]
  node_memory_view["Memory browsing<br/>[MemoryList.vue]"]
  node_activity_view["Activity stats<br/>[Activity.vue]"]
  node_settings_view["Index settings<br/>[Settings.vue]"]
end

subgraph group_recap["Recap experience"]
  node_recap_views["Recap cards<br/>[RecapDetail.vue]"]
  node_recap_handlers["Recap handlers<br/>[recap-handlers.ts]"]
end

subgraph group_context["Context-window plugin"]
  node_dsh_plugin["Context-window plugin<br/>[context-window.ts]"]
  node_rollover["Rollover handling"]
  node_context_state["Rollover state"]
  node_related_files["Related-file validation"]
end

node_user(("User"))
node_coding_agents(("Coding agents"))
node_provider_histories["Provider histories"]

node_provider_histories -->|"watches"| node_index_service
node_index_service -->|"subscribes to changes"| node_watcher
node_index_service -.->|"indexes histories"| node_core
node_core -->|"uses adapters"| node_providers
node_providers -->|"uses shared parsing"| node_parsing
node_core -.->|"persists index"| node_sqlite
node_coding_agents -->|"runs queries"| node_cli
node_cli -->|"invokes core"| node_core
node_cli -->|"runs query scripts"| node_query
node_query -->|"reads and writes"| node_sqlite
node_user -->|"browses history"| node_desktop_app
node_renderer_entry -->|"mounts"| node_desktop_app
node_renderer_entry -->|"installs router"| node_router
node_router -->|"routes to"| node_session_views
node_router -->|"routes to"| node_memory_view
node_router -->|"routes to"| node_activity_view
node_router -->|"routes to"| node_settings_view
node_router -->|"routes to"| node_recap_views
node_session_views -->|"loads details"| node_renderer_data
node_renderer_data -->|"updates state"| node_renderer_store
node_user -->|"views recaps"| node_recap_views
node_recap_views -.->|"requests recap data"| node_recap_handlers
node_coding_agents -.->|"uses plugin"| node_dsh_plugin
node_dsh_plugin -->|"handles rollover"| node_rollover
node_rollover -->|"uses persisted state"| node_context_state
node_dsh_plugin -->|"validates references"| node_related_files

click node_index_service "https://github.com/tommy0103/obelisk/blob/main/app/src/main/indexer-service.ts"
click node_watcher "https://github.com/tommy0103/obelisk/blob/main/packages/adaptive-watcher/src/index.ts"
click node_core "https://github.com/tommy0103/obelisk/blob/main/packages/core/src/core.ts"
click node_parsing "https://github.com/tommy0103/obelisk/blob/main/packages/core/src/parsing.ts"
click node_providers "https://github.com/tommy0103/obelisk/tree/main/packages/core/src/providers"
click node_sqlite "https://github.com/tommy0103/obelisk/blob/main/packages/core/src/db.ts"
click node_cli "https://github.com/tommy0103/obelisk/blob/main/packages/cli/src/obelisk.ts"
click node_query "https://github.com/tommy0103/obelisk/blob/main/packages/core/src/query.ts"
click node_desktop_app "https://github.com/tommy0103/obelisk/blob/main/app/src/renderer/src/App.vue"
click node_renderer_entry "https://github.com/tommy0103/obelisk/blob/main/app/src/renderer/src/main.js"
click node_router "https://github.com/tommy0103/obelisk/blob/main/app/src/renderer/src/router.js"
click node_session_views "https://github.com/tommy0103/obelisk/blob/main/app/src/renderer/src/views/SessionDetail.vue"
click node_renderer_data "https://github.com/tommy0103/obelisk/blob/main/app/src/renderer/src/data.js"
click node_renderer_store "https://github.com/tommy0103/obelisk/blob/main/app/src/renderer/src/store.js"
click node_memory_view "https://github.com/tommy0103/obelisk/blob/main/app/src/renderer/src/views/MemoryList.vue"
click node_activity_view "https://github.com/tommy0103/obelisk/blob/main/app/src/renderer/src/views/Activity.vue"
click node_settings_view "https://github.com/tommy0103/obelisk/blob/main/app/src/renderer/src/views/Settings.vue"
click node_recap_views "https://github.com/tommy0103/obelisk/blob/main/app/src/renderer/src/views/RecapDetail.vue"
click node_recap_handlers "https://github.com/tommy0103/obelisk/blob/main/app/src/main/recap-handlers.ts"
click node_dsh_plugin "https://github.com/tommy0103/obelisk/blob/main/packages/dsh-plugin/src/context-window.ts"
click node_rollover "https://github.com/tommy0103/obelisk/blob/main/packages/dsh-plugin/src/context-window-rollover.ts"
click node_context_state "https://github.com/tommy0103/obelisk/blob/main/packages/dsh-plugin/src/context-window-state.ts"
click node_related_files "https://github.com/tommy0103/obelisk/blob/main/packages/dsh-plugin/src/context-window-related-files.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_index_service,node_watcher,node_core,node_parsing,node_providers,node_sqlite,node_user toneBlue
class node_cli,node_query toneAmber
class node_desktop_app,node_renderer_entry,node_router,node_session_views,node_renderer_data,node_renderer_store,node_memory_view,node_activity_view,node_settings_view toneMint
class node_recap_views,node_recap_handlers toneRose
class node_dsh_plugin,node_rollover,node_context_state,node_related_files,node_coding_agents,node_provider_histories toneIndigo
```

## Components

### Indexing and storage

- [Index service](https://github.com/tommy0103/obelisk/blob/main/app/src/main/indexer-service.ts): `app/src/main/indexer-service.ts`
- [Adaptive watcher](https://github.com/tommy0103/obelisk/blob/main/packages/adaptive-watcher/src/index.ts): `packages/adaptive-watcher/src/index.ts`
- [Core indexing](https://github.com/tommy0103/obelisk/blob/main/packages/core/src/core.ts): `packages/core/src/core.ts`
- [Provider parsing](https://github.com/tommy0103/obelisk/blob/main/packages/core/src/parsing.ts): `packages/core/src/parsing.ts`
- [Provider adapters](https://github.com/tommy0103/obelisk/tree/main/packages/core/src/providers): `packages/core/src/providers`
- [SQLite index](https://github.com/tommy0103/obelisk/blob/main/packages/core/src/db.ts): `packages/core/src/db.ts`

### Agent queries

- [Obelisk CLI](https://github.com/tommy0103/obelisk/blob/main/packages/cli/src/obelisk.ts): `packages/cli/src/obelisk.ts`
- [Query and attune](https://github.com/tommy0103/obelisk/blob/main/packages/core/src/query.ts): `packages/core/src/query.ts`

### Desktop browsing

- [Desktop shell](https://github.com/tommy0103/obelisk/blob/main/app/src/renderer/src/App.vue): `app/src/renderer/src/App.vue`
- [Renderer entry](https://github.com/tommy0103/obelisk/blob/main/app/src/renderer/src/main.js): `app/src/renderer/src/main.js`
- [View router](https://github.com/tommy0103/obelisk/blob/main/app/src/renderer/src/router.js): `app/src/renderer/src/router.js`
- [Session browsing](https://github.com/tommy0103/obelisk/blob/main/app/src/renderer/src/views/SessionDetail.vue): `app/src/renderer/src/views/SessionDetail.vue`
- [Renderer data](https://github.com/tommy0103/obelisk/blob/main/app/src/renderer/src/data.js): `app/src/renderer/src/data.js`
- [Shared UI state](https://github.com/tommy0103/obelisk/blob/main/app/src/renderer/src/store.js): `app/src/renderer/src/store.js`
- [Memory browsing](https://github.com/tommy0103/obelisk/blob/main/app/src/renderer/src/views/MemoryList.vue): `app/src/renderer/src/views/MemoryList.vue`
- [Activity stats](https://github.com/tommy0103/obelisk/blob/main/app/src/renderer/src/views/Activity.vue): `app/src/renderer/src/views/Activity.vue`
- [Index settings](https://github.com/tommy0103/obelisk/blob/main/app/src/renderer/src/views/Settings.vue): `app/src/renderer/src/views/Settings.vue`

### Recap experience

- [Recap cards](https://github.com/tommy0103/obelisk/blob/main/app/src/renderer/src/views/RecapDetail.vue): `app/src/renderer/src/views/RecapDetail.vue`
- [Recap handlers](https://github.com/tommy0103/obelisk/blob/main/app/src/main/recap-handlers.ts): `app/src/main/recap-handlers.ts`

### Context-window plugin

- [Context-window plugin](https://github.com/tommy0103/obelisk/blob/main/packages/dsh-plugin/src/context-window.ts): `packages/dsh-plugin/src/context-window.ts`
- [Rollover handling](https://github.com/tommy0103/obelisk/blob/main/packages/dsh-plugin/src/context-window-rollover.ts): `packages/dsh-plugin/src/context-window-rollover.ts`
- [Rollover state](https://github.com/tommy0103/obelisk/blob/main/packages/dsh-plugin/src/context-window-state.ts): `packages/dsh-plugin/src/context-window-state.ts`
- [Related-file validation](https://github.com/tommy0103/obelisk/blob/main/packages/dsh-plugin/src/context-window-related-files.ts): `packages/dsh-plugin/src/context-window-related-files.ts`

### Other components

- **User**
- **Coding agents**
- **Provider histories**

## Connections

- Provider histories → Index service: watches (evidence: `README.md`)
- Index service → Adaptive watcher: subscribes to changes (evidence: `app/src/main/indexer-service.ts`)
- Index service → Core indexing: indexes histories
- Core indexing → Provider adapters: uses adapters
- Provider adapters → Provider parsing: uses shared parsing (evidence: `packages/core/src/providers/codex.ts`)
- Core indexing → SQLite index: persists index
- Coding agents → Obelisk CLI: runs queries (evidence: `README.md`)
- Obelisk CLI → Core indexing: invokes core (evidence: `packages/cli/src/obelisk.ts`)
- Obelisk CLI → Query and attune: runs query scripts (evidence: `README.md`)
- Query and attune → SQLite index: reads and writes (evidence: `packages/core/src/query.ts`)
- User → Desktop shell: browses history (evidence: `README.md`)
- Renderer entry → Desktop shell: mounts (evidence: `app/src/renderer/src/main.js`)
- Renderer entry → View router: installs router (evidence: `app/src/renderer/src/main.js`)
- View router → Session browsing: routes to (evidence: `app/src/renderer/src/router.js`)
- View router → Memory browsing: routes to (evidence: `app/src/renderer/src/router.js`)
- View router → Activity stats: routes to (evidence: `app/src/renderer/src/router.js`)
- View router → Index settings: routes to (evidence: `app/src/renderer/src/router.js`)
- View router → Recap cards: routes to (evidence: `app/src/renderer/src/router.js`)
- Session browsing → Renderer data: loads details (evidence: `app/src/renderer/src/views/SessionDetail.vue`)
- Renderer data → Shared UI state: updates state (evidence: `app/src/renderer/src/data.js`)
- User → Recap cards: views recaps (evidence: `README.md`)
- Recap cards → Recap handlers: requests recap data
- Coding agents → Context-window plugin: uses plugin (evidence: `README.md`)
- Context-window plugin → Rollover handling: handles rollover (evidence: `packages/dsh-plugin/src/context-window.ts`)
- Rollover handling → Rollover state: uses persisted state (evidence: `packages/dsh-plugin/src/context-window-rollover.ts`)
- Context-window plugin → Related-file validation: validates references (evidence: `packages/dsh-plugin/src/context-window.ts`)
