# alharkan7/beeblio-oss architecture

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

- Interactive diagram: https://gitdiagram.com/alharkan7/beeblio-oss
- Repository: https://github.com/alharkan7/beeblio-oss

## Overview

Beeblio is a local-first AI research workspace: users link an existing folder, work with its files and research materials, and collaborate with Eve in project conversations. The session page joins workspace and conversation; the agent can research and edit files, while the editor supports citation-aware writing and exports. Project records, sessions, knowledge metadata, and share records live in SQLite; project documents remain in the linked folder. The README documents several capabilities whose detailed implementation was not sampled, so those branches are included at the documented subsystem level rather than with speculative call chains.

Main entry points: [`lib/workspace-files.ts`](https://github.com/alharkan7/beeblio-oss/blob/main/lib/workspace-files.ts) (Workspace file access), [`agent/tools`](https://github.com/alharkan7/beeblio-oss/tree/main/agent/tools) (Agent tools), [`app/[projectId]/[[...sessionId]]/page.tsx`](https://github.com/alharkan7/beeblio-oss/blob/main/app/%5BprojectId%5D/%5B%5B...sessionId%5D%5D/page.tsx) (Project session), [`app/eve/[...path]/route.ts`](https://github.com/alharkan7/beeblio-oss/blob/main/app/eve/%5B...path%5D/route.ts) (Eve request proxy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Projects and workspace"]
  node_project_dashboard["Project dashboard"]
  node_project_setup["Project setup<br/>[route.ts]"]
  node_session_page["Project session<br/>[page.tsx]"]
  node_file_explorer["File explorer<br/>[file-explorer.tsx]"]
  node_artifact_browser["Research artifacts"]
  node_upload["Workspace uploads<br/>[route.ts]"]
  node_storage_meter["Storage meter<br/>[storage-meter.tsx]"]
end

subgraph group_assistant["Eve assistant"]
  node_eve_proxy["Eve request proxy<br/>[route.ts]"]
  node_eve_agent["Eve agent<br/>[agent.ts]"]
  node_agent_tools["Agent tools"]
  node_local_commands["Local commands"]
end

subgraph group_research["Research and knowledge"]
  node_literature_search["Literature search<br/>[search.ts]"]
  node_knowledge["Knowledge stores<br/>[knowledge.ts]"]
  node_bibliography["Bibliography"]
  node_matrix["Literature matrix"]
end

subgraph group_writing["Writing and sharing"]
  node_markdown_editor["Markdown editor"]
  node_review["Document review"]
  node_export["Document export<br/>[convert-latex.ts]"]
  node_public_sharing["Public sharing<br/>[page.tsx]"]
  node_form_runtime["Shared forms<br/>[runtime.ts]"]
end

subgraph group_persistence["State and file access"]
  node_db_schema[("Application records<br/>[schema.ts]")]
  node_db_client[("SQLite database<br/>[index.ts]")]
  node_workspace_files["Workspace file access<br/>[workspace-files.ts]"]
  node_agent_token["Agent token<br/>[agent-token.ts]"]
end

node_user(("Local user"))
node_external_services{{"Model and research APIs"}}

node_user -->|"browses projects"| node_project_dashboard
node_user -->|"links folder"| node_project_setup
node_project_dashboard -->|"opens project"| node_session_page
node_project_setup -->|"stores project"| node_db_client
node_session_page -->|"starts conversation"| node_eve_proxy
node_session_page -->|"opens workspace"| node_file_explorer
node_session_page -->|"browses artifacts"| node_artifact_browser
node_user -->|"uploads files"| node_upload
node_upload -->|"creates ticket"| node_workspace_files
node_eve_proxy -->|"forwards requests"| node_eve_agent
node_eve_proxy -->|"mints token"| node_agent_token
node_eve_proxy -->|"registers sessions"| node_db_client
node_eve_agent -->|"uses tools"| node_agent_tools
node_eve_agent -->|"runs workflows"| node_local_commands
node_agent_tools -->|"searches literature"| node_literature_search
node_agent_tools -->|"updates references"| node_bibliography
node_agent_tools -->|"updates matrix"| node_matrix
node_agent_tools -->|"edits project files"| node_workspace_files
node_user -->|"writes documents"| node_markdown_editor
node_markdown_editor -->|"inserts citations"| node_bibliography
node_user -->|"requests review"| node_review
node_markdown_editor -->|"exports document"| node_export
node_user -->|"searches sources"| node_literature_search
node_user -.->|"uses knowledge"| node_knowledge
node_user -->|"shares file"| node_public_sharing
node_public_sharing -->|"renders forms"| node_form_runtime
node_public_sharing -->|"reads shared files"| node_workspace_files
node_user -->|"works with folder"| node_workspace_files
node_workspace_files -->|"resolves projects"| node_db_client
node_db_client -->|"uses schema"| node_db_schema
node_storage_meter -->|"requests usage"| node_workspace_files
node_eve_agent -->|"calls model APIs"| node_external_services
node_literature_search -.->|"queries research APIs"| node_external_services

click node_project_dashboard "https://github.com/alharkan7/beeblio-oss/blob/main/app/_components/projects-dashboard-client.tsx"
click node_project_setup "https://github.com/alharkan7/beeblio-oss/blob/main/app/api/projects/route.ts"
click node_session_page "https://github.com/alharkan7/beeblio-oss/blob/main/app/%5BprojectId%5D/%5B%5B...sessionId%5D%5D/page.tsx"
click node_file_explorer "https://github.com/alharkan7/beeblio-oss/blob/main/app/%5BprojectId%5D/_components/file-explorer.tsx"
click node_artifact_browser "https://github.com/alharkan7/beeblio-oss/blob/main/app/%5BprojectId%5D/_components/research-artifact-browser.tsx"
click node_upload "https://github.com/alharkan7/beeblio-oss/blob/main/app/api/workspace/upload-ticket/route.ts"
click node_eve_proxy "https://github.com/alharkan7/beeblio-oss/blob/main/app/eve/%5B...path%5D/route.ts"
click node_eve_agent "https://github.com/alharkan7/beeblio-oss/blob/main/agent/agent.ts"
click node_agent_tools "https://github.com/alharkan7/beeblio-oss/tree/main/agent/tools"
click node_local_commands "https://github.com/alharkan7/beeblio-oss/tree/main/agent/sandbox"
click node_literature_search "https://github.com/alharkan7/beeblio-oss/blob/main/lib/literature/search.ts"
click node_knowledge "https://github.com/alharkan7/beeblio-oss/blob/main/lib/knowledge.ts"
click node_bibliography "https://github.com/alharkan7/beeblio-oss/blob/main/lib/project-bibliography.ts"
click node_matrix "https://github.com/alharkan7/beeblio-oss/blob/main/lib/literature-matrix.ts"
click node_markdown_editor "https://github.com/alharkan7/beeblio-oss/blob/main/app/%5BprojectId%5D/_components/editors/tiptap-document-editor.tsx"
click node_review "https://github.com/alharkan7/beeblio-oss/blob/main/app/%5BprojectId%5D/_components/document-review-panel.tsx"
click node_export "https://github.com/alharkan7/beeblio-oss/blob/main/lib/document-export/convert-latex.ts"
click node_public_sharing "https://github.com/alharkan7/beeblio-oss/blob/main/app/share/%5BshareId%5D/page.tsx"
click node_form_runtime "https://github.com/alharkan7/beeblio-oss/blob/main/lib/forms/runtime.ts"
click node_db_schema "https://github.com/alharkan7/beeblio-oss/blob/main/db/schema.ts"
click node_db_client "https://github.com/alharkan7/beeblio-oss/blob/main/db/index.ts"
click node_workspace_files "https://github.com/alharkan7/beeblio-oss/blob/main/lib/workspace-files.ts"
click node_agent_token "https://github.com/alharkan7/beeblio-oss/blob/main/lib/agent-token.ts"
click node_storage_meter "https://github.com/alharkan7/beeblio-oss/blob/main/app/%5BprojectId%5D/_components/storage-meter.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_project_dashboard,node_project_setup,node_session_page,node_file_explorer,node_artifact_browser,node_upload,node_storage_meter,node_user toneBlue
class node_eve_proxy,node_eve_agent,node_agent_tools,node_local_commands toneAmber
class node_literature_search,node_knowledge,node_bibliography,node_matrix,node_external_services toneMint
class node_markdown_editor,node_review,node_export,node_public_sharing,node_form_runtime toneRose
class node_db_schema,node_db_client,node_workspace_files,node_agent_token toneIndigo
```

## Components

### Projects and workspace

- [Project dashboard](https://github.com/alharkan7/beeblio-oss/blob/main/app/_components/projects-dashboard-client.tsx): `app/_components/projects-dashboard-client.tsx`
- [Project setup](https://github.com/alharkan7/beeblio-oss/blob/main/app/api/projects/route.ts): `app/api/projects/route.ts`
- [Project session](https://github.com/alharkan7/beeblio-oss/blob/main/app/%5BprojectId%5D/%5B%5B...sessionId%5D%5D/page.tsx): `app/[projectId]/[[...sessionId]]/page.tsx`
- [File explorer](https://github.com/alharkan7/beeblio-oss/blob/main/app/%5BprojectId%5D/_components/file-explorer.tsx): `app/[projectId]/_components/file-explorer.tsx`
- [Research artifacts](https://github.com/alharkan7/beeblio-oss/blob/main/app/%5BprojectId%5D/_components/research-artifact-browser.tsx): `app/[projectId]/_components/research-artifact-browser.tsx`
- [Workspace uploads](https://github.com/alharkan7/beeblio-oss/blob/main/app/api/workspace/upload-ticket/route.ts): `app/api/workspace/upload-ticket/route.ts`
- [Storage meter](https://github.com/alharkan7/beeblio-oss/blob/main/app/%5BprojectId%5D/_components/storage-meter.tsx): `app/[projectId]/_components/storage-meter.tsx`

### Eve assistant

- [Eve request proxy](https://github.com/alharkan7/beeblio-oss/blob/main/app/eve/%5B...path%5D/route.ts): `app/eve/[...path]/route.ts`
- [Eve agent](https://github.com/alharkan7/beeblio-oss/blob/main/agent/agent.ts): `agent/agent.ts`
- [Agent tools](https://github.com/alharkan7/beeblio-oss/tree/main/agent/tools): `agent/tools`
- [Local commands](https://github.com/alharkan7/beeblio-oss/tree/main/agent/sandbox): `agent/sandbox`

### Research and knowledge

- [Literature search](https://github.com/alharkan7/beeblio-oss/blob/main/lib/literature/search.ts): `lib/literature/search.ts`
- [Knowledge stores](https://github.com/alharkan7/beeblio-oss/blob/main/lib/knowledge.ts): `lib/knowledge.ts`
- [Bibliography](https://github.com/alharkan7/beeblio-oss/blob/main/lib/project-bibliography.ts): `lib/project-bibliography.ts`
- [Literature matrix](https://github.com/alharkan7/beeblio-oss/blob/main/lib/literature-matrix.ts): `lib/literature-matrix.ts`

### Writing and sharing

- [Markdown editor](https://github.com/alharkan7/beeblio-oss/blob/main/app/%5BprojectId%5D/_components/editors/tiptap-document-editor.tsx): `app/[projectId]/_components/editors/tiptap-document-editor.tsx`
- [Document review](https://github.com/alharkan7/beeblio-oss/blob/main/app/%5BprojectId%5D/_components/document-review-panel.tsx): `app/[projectId]/_components/document-review-panel.tsx`
- [Document export](https://github.com/alharkan7/beeblio-oss/blob/main/lib/document-export/convert-latex.ts): `lib/document-export/convert-latex.ts`
- [Public sharing](https://github.com/alharkan7/beeblio-oss/blob/main/app/share/%5BshareId%5D/page.tsx): `app/share/[shareId]/page.tsx`
- [Shared forms](https://github.com/alharkan7/beeblio-oss/blob/main/lib/forms/runtime.ts): `lib/forms/runtime.ts`

### State and file access

- [Application records](https://github.com/alharkan7/beeblio-oss/blob/main/db/schema.ts): `db/schema.ts`
- [SQLite database](https://github.com/alharkan7/beeblio-oss/blob/main/db/index.ts): `db/index.ts`
- [Workspace file access](https://github.com/alharkan7/beeblio-oss/blob/main/lib/workspace-files.ts): `lib/workspace-files.ts`
- [Agent token](https://github.com/alharkan7/beeblio-oss/blob/main/lib/agent-token.ts): `lib/agent-token.ts`

### Other components

- **Local user**
- **Model and research APIs**

## Connections

- Local user → Project dashboard: browses projects (evidence: `README.md`)
- Local user → Project setup: links folder (evidence: `README.md`)
- Project dashboard → Project session: opens project (evidence: `README.md`)
- Project setup → SQLite database: stores project (evidence: `app/api/projects/route.ts`)
- Project session → Eve request proxy: starts conversation (evidence: `README.md`)
- Project session → File explorer: opens workspace (evidence: `README.md`)
- Project session → Research artifacts: browses artifacts (evidence: `README.md`)
- Local user → Workspace uploads: uploads files (evidence: `README.md`)
- Workspace uploads → Workspace file access: creates ticket (evidence: `app/api/workspace/upload-ticket/route.ts`)
- Eve request proxy → Eve agent: forwards requests (evidence: `app/eve/[...path]/route.ts`)
- Eve request proxy → Agent token: mints token (evidence: `app/eve/[...path]/route.ts`)
- Eve request proxy → SQLite database: registers sessions (evidence: `app/eve/[...path]/route.ts`)
- Eve agent → Agent tools: uses tools (evidence: `README.md`)
- Eve agent → Local commands: runs workflows (evidence: `README.md`)
- Agent tools → Literature search: searches literature (evidence: `README.md`)
- Agent tools → Bibliography: updates references (evidence: `README.md`)
- Agent tools → Literature matrix: updates matrix (evidence: `README.md`)
- Agent tools → Workspace file access: edits project files (evidence: `README.md`)
- Local user → Markdown editor: writes documents (evidence: `README.md`)
- Markdown editor → Bibliography: inserts citations (evidence: `README.md`)
- Local user → Document review: requests review (evidence: `README.md`)
- Markdown editor → Document export: exports document (evidence: `README.md`)
- Local user → Literature search: searches sources (evidence: `README.md`)
- Local user → Knowledge stores: uses knowledge
- Local user → Public sharing: shares file (evidence: `README.md`)
- Public sharing → Shared forms: renders forms
- Public sharing → Workspace file access: reads shared files (evidence: `app/share/[shareId]/page.tsx`)
- Local user → Workspace file access: works with folder (evidence: `README.md`)
- Workspace file access → SQLite database: resolves projects (evidence: `lib/workspace-files.ts`)
- SQLite database → Application records: uses schema (evidence: `db/index.ts`)
- Storage meter → Workspace file access: requests usage
- Eve agent → Model and research APIs: calls model APIs (evidence: `README.md`)
- Literature search → Model and research APIs: queries research APIs
