# hydra-db/open-glean architecture

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

- Interactive diagram: https://gitdiagram.com/hydra-db/open-glean
- Repository: https://github.com/hydra-db/open-glean

## Overview

Open Glean is an AI workspace over Hydra DB: users connect credentials, choose a database or collection scope, then ask questions against their knowledge and receive streamed, cited answers. Deep Research expands this into planned sub-questions and live progress; other major capabilities include context management, integrations, collections, and a knowledge mindmap. The graph combines sampled client/server relationships with documented capabilities; some feature-page internals and the exact Deep Research client-to-server wiring were not sampled.

Main entry points: [`lib/api.ts`](https://github.com/hydra-db/open-glean/blob/main/lib/api.ts) (Hydra client), [`app/(app)/chat/[id]/page.tsx`](https://github.com/hydra-db/open-glean/blob/main/app/(app)/chat/%5Bid%5D/page.tsx) (Chat workspace), [`lib/qa.ts`](https://github.com/hydra-db/open-glean/blob/main/lib/qa.ts) (Q&A engine), [`app/(app)/settings/page.tsx`](https://github.com/hydra-db/open-glean/blob/main/app/(app)/settings/page.tsx) (Settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Workspace"]
  node_ask_ui["Ask composer<br/>[AskSearchBar.tsx]"]
  node_chat_ui["Chat workspace<br/>[page.tsx]"]
  node_scope_ui["Scope switcher<br/>[ScopeSwitcher.tsx]"]
  node_research_ui["Research timeline"]
  node_context_ui["Context manager<br/>[page.tsx]"]
  node_collections_ui["Collections<br/>[page.tsx]"]
  node_integrations_ui["Integrations<br/>[page.tsx]"]
  node_mindmap_ui["Knowledge mindmap<br/>[page.tsx]"]
  node_settings_ui["Settings<br/>[page.tsx]"]
end

subgraph group_query["Question answering"]
  node_qa_engine["Q&amp;A engine<br/>[qa.ts]"]
  node_research_engine["Research planner<br/>[route.ts]"]
  node_citations["Citation rendering<br/>[citations.ts]"]
end

subgraph group_connect["Connections and context"]
end

subgraph group_server["Server services"]
  node_browser_api["Hydra client<br/>[api.ts]"]
  node_hydra_proxy["Hydra proxy<br/>[route.ts]"]
  node_hydra_sdk["Hydra SDK<br/>[client.ts]"]
  node_llm_proxy["LLM chat API<br/>[route.ts]"]
  node_llm_service["LLM service<br/>[llmServer.ts]"]
  node_auth_api["Key management API<br/>[route.ts]"]
  node_session["Encrypted session<br/>[session.ts]"]
  node_chat_api["Chat persistence API<br/>[route.ts]"]
end

subgraph group_state["Persistence"]
  node_config_store["Browser config<br/>[config.tsx]"]
  node_chat_store["Conversation state<br/>[chat.tsx]"]
  node_mongo[("MongoDB persistence<br/>[mongo.ts]")]
end

node_user(("User"))
node_hydra_db[("Hydra DB")]
node_llm_provider{{"LLM provider"}}

node_user -->|"asks"| node_ask_ui
node_ask_ui -->|"starts query"| node_qa_engine
node_chat_ui -->|"runs Q&amp;A"| node_qa_engine
node_qa_engine -->|"retrieves context"| node_browser_api
node_browser_api -->|"proxies requests"| node_hydra_proxy
node_hydra_proxy -->|"delegates requests"| node_hydra_sdk
node_hydra_sdk -->|"queries"| node_hydra_db
node_qa_engine -->|"requests streamed answer"| node_llm_proxy
node_llm_proxy -->|"uses"| node_llm_service
node_llm_service -->|"calls completions"| node_llm_provider
node_qa_engine -->|"builds citations"| node_citations
node_citations -->|"renders sources"| node_chat_ui
node_chat_ui -.->|"starts research"| node_research_engine
node_research_engine -.->|"retrieves research context"| node_hydra_sdk
node_research_engine -->|"plans and synthesizes"| node_llm_service
node_research_ui -->|"shows progress"| node_chat_ui
node_user -->|"connects account"| node_settings_ui
node_settings_ui -->|"submits credentials"| node_auth_api
node_auth_api -->|"stores credentials"| node_session
node_auth_api -->|"verifies Hydra key"| node_hydra_sdk
node_config_store -->|"loads key status"| node_auth_api
node_scope_ui -.->|"sets query scope"| node_browser_api
node_context_ui -->|"manages knowledge"| node_browser_api
node_collections_ui -->|"searches collection"| node_browser_api
node_integrations_ui -->|"manages connectors"| node_browser_api
node_mindmap_ui -->|"loads knowledge graph"| node_browser_api
node_chat_ui -->|"updates conversations"| node_chat_store
node_chat_store -.->|"persists chats"| node_chat_api
node_chat_api -->|"reads and writes"| node_mongo
node_user -->|"chooses model"| node_settings_ui
node_settings_ui -->|"stores preferences"| node_config_store

click node_ask_ui "https://github.com/hydra-db/open-glean/blob/main/components/AskSearchBar.tsx"
click node_chat_ui "https://github.com/hydra-db/open-glean/blob/main/app/(app)/chat/%5Bid%5D/page.tsx"
click node_scope_ui "https://github.com/hydra-db/open-glean/blob/main/components/ScopeSwitcher.tsx"
click node_research_ui "https://github.com/hydra-db/open-glean/blob/main/components/ResearchTimeline.tsx"
click node_context_ui "https://github.com/hydra-db/open-glean/blob/main/app/(app)/context/page.tsx"
click node_collections_ui "https://github.com/hydra-db/open-glean/blob/main/app/(app)/collections/%5Bslug%5D/page.tsx"
click node_integrations_ui "https://github.com/hydra-db/open-glean/blob/main/app/(app)/integrations/page.tsx"
click node_mindmap_ui "https://github.com/hydra-db/open-glean/blob/main/app/(app)/mindmap/page.tsx"
click node_settings_ui "https://github.com/hydra-db/open-glean/blob/main/app/(app)/settings/page.tsx"
click node_qa_engine "https://github.com/hydra-db/open-glean/blob/main/lib/qa.ts"
click node_research_engine "https://github.com/hydra-db/open-glean/blob/main/app/api/research/route.ts"
click node_citations "https://github.com/hydra-db/open-glean/blob/main/lib/citations.ts"
click node_browser_api "https://github.com/hydra-db/open-glean/blob/main/lib/api.ts"
click node_hydra_proxy "https://github.com/hydra-db/open-glean/blob/main/app/api/hydra/%5B...path%5D/route.ts"
click node_hydra_sdk "https://github.com/hydra-db/open-glean/blob/main/lib/hydra/client.ts"
click node_llm_proxy "https://github.com/hydra-db/open-glean/blob/main/app/api/llm/chat/route.ts"
click node_llm_service "https://github.com/hydra-db/open-glean/blob/main/lib/llmServer.ts"
click node_auth_api "https://github.com/hydra-db/open-glean/blob/main/app/api/auth/key/route.ts"
click node_session "https://github.com/hydra-db/open-glean/blob/main/lib/session.ts"
click node_config_store "https://github.com/hydra-db/open-glean/blob/main/lib/store/config.tsx"
click node_chat_store "https://github.com/hydra-db/open-glean/blob/main/lib/store/chat.tsx"
click node_chat_api "https://github.com/hydra-db/open-glean/blob/main/app/api/chats/route.ts"
click node_mongo "https://github.com/hydra-db/open-glean/blob/main/lib/mongo.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_ask_ui,node_chat_ui,node_scope_ui,node_research_ui,node_context_ui,node_collections_ui,node_integrations_ui,node_mindmap_ui,node_settings_ui,node_user toneBlue
class node_qa_engine,node_research_engine,node_citations,node_hydra_db toneAmber
class node_browser_api,node_hydra_proxy,node_hydra_sdk,node_llm_proxy,node_llm_service,node_auth_api,node_session,node_chat_api toneRose
class node_config_store,node_chat_store,node_mongo,node_llm_provider toneIndigo
```

## Components

### Workspace

- [Ask composer](https://github.com/hydra-db/open-glean/blob/main/components/AskSearchBar.tsx): `components/AskSearchBar.tsx`
- [Chat workspace](https://github.com/hydra-db/open-glean/blob/main/app/(app)/chat/%5Bid%5D/page.tsx): `app/(app)/chat/[id]/page.tsx`
- [Scope switcher](https://github.com/hydra-db/open-glean/blob/main/components/ScopeSwitcher.tsx): `components/ScopeSwitcher.tsx`
- [Research timeline](https://github.com/hydra-db/open-glean/blob/main/components/ResearchTimeline.tsx): `components/ResearchTimeline.tsx`
- [Context manager](https://github.com/hydra-db/open-glean/blob/main/app/(app)/context/page.tsx): `app/(app)/context/page.tsx`
- [Collections](https://github.com/hydra-db/open-glean/blob/main/app/(app)/collections/%5Bslug%5D/page.tsx): `app/(app)/collections/[slug]/page.tsx`
- [Integrations](https://github.com/hydra-db/open-glean/blob/main/app/(app)/integrations/page.tsx): `app/(app)/integrations/page.tsx`
- [Knowledge mindmap](https://github.com/hydra-db/open-glean/blob/main/app/(app)/mindmap/page.tsx): `app/(app)/mindmap/page.tsx`
- [Settings](https://github.com/hydra-db/open-glean/blob/main/app/(app)/settings/page.tsx): `app/(app)/settings/page.tsx`

### Question answering

- [Q&A engine](https://github.com/hydra-db/open-glean/blob/main/lib/qa.ts): `lib/qa.ts`
- [Research planner](https://github.com/hydra-db/open-glean/blob/main/app/api/research/route.ts): `app/api/research/route.ts`
- [Citation rendering](https://github.com/hydra-db/open-glean/blob/main/lib/citations.ts): `lib/citations.ts`

### Server services

- [Hydra client](https://github.com/hydra-db/open-glean/blob/main/lib/api.ts): `lib/api.ts`
- [Hydra proxy](https://github.com/hydra-db/open-glean/blob/main/app/api/hydra/%5B...path%5D/route.ts): `app/api/hydra/[...path]/route.ts`
- [Hydra SDK](https://github.com/hydra-db/open-glean/blob/main/lib/hydra/client.ts): `lib/hydra/client.ts`
- [LLM chat API](https://github.com/hydra-db/open-glean/blob/main/app/api/llm/chat/route.ts): `app/api/llm/chat/route.ts`
- [LLM service](https://github.com/hydra-db/open-glean/blob/main/lib/llmServer.ts): `lib/llmServer.ts`
- [Key management API](https://github.com/hydra-db/open-glean/blob/main/app/api/auth/key/route.ts): `app/api/auth/key/route.ts`
- [Encrypted session](https://github.com/hydra-db/open-glean/blob/main/lib/session.ts): `lib/session.ts`
- [Chat persistence API](https://github.com/hydra-db/open-glean/blob/main/app/api/chats/route.ts): `app/api/chats/route.ts`

### Persistence

- [Browser config](https://github.com/hydra-db/open-glean/blob/main/lib/store/config.tsx): `lib/store/config.tsx`
- [Conversation state](https://github.com/hydra-db/open-glean/blob/main/lib/store/chat.tsx): `lib/store/chat.tsx`
- [MongoDB persistence](https://github.com/hydra-db/open-glean/blob/main/lib/mongo.ts): `lib/mongo.ts`

### Other components

- **User**
- **Hydra DB**
- **LLM provider**

## Connections

- User → Ask composer: asks (evidence: `README.md`)
- Ask composer → Q&A engine: starts query (evidence: `components/AskSearchBar.tsx`)
- Chat workspace → Q&A engine: runs Q&A (evidence: `app/(app)/chat/[id]/page.tsx`)
- Q&A engine → Hydra client: retrieves context (evidence: `lib/qa.ts`)
- Hydra client → Hydra proxy: proxies requests (evidence: `lib/api.ts`)
- Hydra proxy → Hydra SDK: delegates requests (evidence: `app/api/hydra/[...path]/route.ts`)
- Hydra SDK → Hydra DB: queries (evidence: `README.md`)
- Q&A engine → LLM chat API: requests streamed answer (evidence: `README.md`)
- LLM chat API → LLM service: uses (evidence: `app/api/llm/chat/route.ts`)
- LLM service → LLM provider: calls completions (evidence: `lib/llmServer.ts`)
- Q&A engine → Citation rendering: builds citations (evidence: `lib/qa.ts`)
- Citation rendering → Chat workspace: renders sources (evidence: `app/(app)/chat/[id]/page.tsx`)
- Chat workspace → Research planner: starts research
- Research planner → Hydra SDK: retrieves research context
- Research planner → LLM service: plans and synthesizes (evidence: `app/api/research/route.ts`)
- Research timeline → Chat workspace: shows progress (evidence: `app/(app)/chat/[id]/page.tsx`)
- User → Settings: connects account (evidence: `README.md`)
- Settings → Key management API: submits credentials (evidence: `README.md`)
- Key management API → Encrypted session: stores credentials (evidence: `app/api/auth/key/route.ts`)
- Key management API → Hydra SDK: verifies Hydra key (evidence: `app/api/auth/key/route.ts`)
- Browser config → Key management API: loads key status (evidence: `lib/store/config.tsx`)
- Scope switcher → Hydra client: sets query scope
- Context manager → Hydra client: manages knowledge (evidence: `app/(app)/context/page.tsx`)
- Collections → Hydra client: searches collection (evidence: `app/(app)/collections/[slug]/page.tsx`)
- Integrations → Hydra client: manages connectors (evidence: `app/(app)/integrations/page.tsx`)
- Knowledge mindmap → Hydra client: loads knowledge graph (evidence: `app/(app)/mindmap/page.tsx`)
- Chat workspace → Conversation state: updates conversations (evidence: `app/(app)/chat/[id]/page.tsx`)
- Conversation state → Chat persistence API: persists chats
- Chat persistence API → MongoDB persistence: reads and writes (evidence: `app/api/chats/route.ts`)
- User → Settings: chooses model (evidence: `README.md`)
- Settings → Browser config: stores preferences (evidence: `app/(app)/settings/page.tsx`)