# masdos/khemeia-eln architecture

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

- Interactive diagram: https://gitdiagram.com/masdos/khemeia-eln
- Repository: https://github.com/masdos/khemeia-eln

## Overview

Khemeia ELN is a local-first chemistry electronic lab notebook. Researchers use its desktop interface to organize projects and protocols, record and search experiments, trace reagent and equipment use, attach files, and export records. A separate report workflow uses a local Ollama model to draft reports for saving and export. The map follows the documented UI, service, repository, and SQLite layers; some page and integration links rely on README or source-index references because those implementations were not excerpted.

Main entry points: [`app/ui/router.py`](https://github.com/masdos/khemeia-eln/blob/main/app/ui/router.py) (Page router), [`app/services/export_service.py`](https://github.com/masdos/khemeia-eln/blob/main/app/services/export_service.py) (Document export), [`app/ui/pages/experiment_detail.py`](https://github.com/masdos/khemeia-eln/blob/main/app/ui/pages/experiment_detail.py) (Experiment pages), [`app/database/connection.py`](https://github.com/masdos/khemeia-eln/blob/main/app/database/connection.py) (SQLite store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Desktop interface"]
  node_app_entry["App startup<br/>[main.py]"]
  node_navigation["Page router<br/>[router.py]"]
  node_experiment_ui["Experiment pages"]
  node_dashboard_ui["Dashboard<br/>[dashboard.py]"]
  node_inventory_ui["Inventory pages<br/>[inventory.py]"]
  node_project_ui["Project pages<br/>[project_detail.py]"]
  node_protocol_ui["Protocol pages<br/>[protocol_detail.py]"]
  node_reports_ui["Report pages<br/>[reports.py]"]
end

subgraph group_domain["Lab workflows"]
  node_experiment_service["Experiment workflow"]
  node_inventory_service["Inventory traceability"]
  node_project_service["Project management<br/>[project_service.py]"]
  node_protocol_service["Protocol management"]
  node_report_service["Saved reports<br/>[report_service.py]"]
end

subgraph group_data["Persistence and files"]
  node_sqlite[("SQLite store<br/>[connection.py]")]
  node_experiment_repo["Experiment records"]
  node_inventory_repos["Reagent and equipment records"]
  node_project_repo["Project records"]
  node_protocol_repo["Protocol records"]
  node_report_repo["Report records"]
  node_attachments["Attachments"]
end

subgraph group_ai["Local AI and export"]
  node_ai_ui["AI report generator"]
  node_ai_service["AI drafting<br/>[ai_service.py]"]
  node_ollama_client["Ollama client<br/>[ollama_client.py]"]
  node_export_service["Document export<br/>[export_service.py]"]
end

node_researcher(("Researcher"))
node_ollama{{"Local Ollama model"}}
node_export_formats["Markdown PDF DOCX"]

node_researcher -->|"starts app"| node_app_entry
node_app_entry -->|"sets up"| node_navigation
node_researcher -.->|"navigates"| node_navigation
node_navigation -->|"renders"| node_dashboard_ui
node_navigation -->|"renders"| node_experiment_ui
node_navigation -->|"renders"| node_inventory_ui
node_navigation -->|"renders"| node_project_ui
node_navigation -->|"renders"| node_protocol_ui
node_navigation -->|"renders"| node_reports_ui
node_navigation -->|"renders"| node_ai_ui
node_dashboard_ui -->|"lists experiments"| node_experiment_service
node_experiment_ui -->|"edits experiments"| node_experiment_service
node_experiment_ui -->|"links resources"| node_inventory_service
node_experiment_ui -->|"loads project"| node_project_service
node_experiment_ui -->|"loads protocol"| node_protocol_service
node_experiment_ui -->|"exports experiment"| node_export_service
node_inventory_ui -->|"manages stock"| node_inventory_service
node_project_ui -->|"manages projects"| node_project_service
node_protocol_ui -.->|"manages protocols"| node_protocol_service
node_reports_ui -->|"manages reports"| node_report_service
node_ai_ui -->|"requests drafts"| node_ai_service
node_ai_ui -->|"exports reports"| node_export_service
node_experiment_service -->|"reads and writes"| node_experiment_repo
node_inventory_service -->|"reads and writes"| node_inventory_repos
node_project_service -->|"reads and writes"| node_project_repo
node_protocol_service -->|"reads and writes"| node_protocol_repo
node_report_service -->|"reads and writes"| node_report_repo
node_experiment_repo -->|"queries"| node_sqlite
node_inventory_repos -->|"queries"| node_sqlite
node_project_repo -.->|"queries"| node_sqlite
node_protocol_repo -.->|"queries"| node_sqlite
node_report_repo -.->|"queries"| node_sqlite
node_ai_service -->|"uses client"| node_ollama_client
node_ollama_client -.->|"sends prompts"| node_ollama
node_export_service -->|"reads experiment"| node_experiment_repo
node_export_service -->|"reads resources"| node_inventory_repos
node_export_service -->|"reads project"| node_project_repo
node_export_service -->|"reads protocol"| node_protocol_repo
node_export_service -->|"reads attachments"| node_attachments
node_export_service -.->|"reads reports"| node_report_repo
node_export_service -->|"writes files"| node_export_formats

click node_app_entry "https://github.com/masdos/khemeia-eln/blob/main/main.py"
click node_navigation "https://github.com/masdos/khemeia-eln/blob/main/app/ui/router.py"
click node_experiment_ui "https://github.com/masdos/khemeia-eln/blob/main/app/ui/pages/experiment_detail.py"
click node_dashboard_ui "https://github.com/masdos/khemeia-eln/blob/main/app/ui/pages/dashboard.py"
click node_inventory_ui "https://github.com/masdos/khemeia-eln/blob/main/app/ui/pages/inventory.py"
click node_project_ui "https://github.com/masdos/khemeia-eln/blob/main/app/ui/pages/project_detail.py"
click node_protocol_ui "https://github.com/masdos/khemeia-eln/blob/main/app/ui/pages/protocol_detail.py"
click node_reports_ui "https://github.com/masdos/khemeia-eln/blob/main/app/ui/pages/reports.py"
click node_experiment_service "https://github.com/masdos/khemeia-eln/blob/main/app/services/experiment_service.py"
click node_inventory_service "https://github.com/masdos/khemeia-eln/blob/main/app/services/inventory_service.py"
click node_project_service "https://github.com/masdos/khemeia-eln/blob/main/app/services/project_service.py"
click node_protocol_service "https://github.com/masdos/khemeia-eln/blob/main/app/services/protocol_service.py"
click node_report_service "https://github.com/masdos/khemeia-eln/blob/main/app/services/report_service.py"
click node_sqlite "https://github.com/masdos/khemeia-eln/blob/main/app/database/connection.py"
click node_experiment_repo "https://github.com/masdos/khemeia-eln/blob/main/app/repositories/experiment_repository.py"
click node_inventory_repos "https://github.com/masdos/khemeia-eln/blob/main/app/repositories/reagent_repository.py"
click node_project_repo "https://github.com/masdos/khemeia-eln/blob/main/app/repositories/project_repository.py"
click node_protocol_repo "https://github.com/masdos/khemeia-eln/blob/main/app/repositories/protocol_repository.py"
click node_report_repo "https://github.com/masdos/khemeia-eln/blob/main/app/repositories/report_repository.py"
click node_attachments "https://github.com/masdos/khemeia-eln/blob/main/app/repositories/attachment_repository.py"
click node_ai_ui "https://github.com/masdos/khemeia-eln/blob/main/app/ui/pages/ai_report_generator.py"
click node_ai_service "https://github.com/masdos/khemeia-eln/blob/main/app/services/ai_service.py"
click node_ollama_client "https://github.com/masdos/khemeia-eln/blob/main/app/services/ollama_client.py"
click node_export_service "https://github.com/masdos/khemeia-eln/blob/main/app/services/export_service.py"

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_app_entry,node_navigation,node_experiment_ui,node_dashboard_ui,node_inventory_ui,node_project_ui,node_protocol_ui,node_reports_ui toneBlue
class node_experiment_service,node_inventory_service,node_project_service,node_protocol_service,node_report_service toneAmber
class node_sqlite,node_experiment_repo,node_inventory_repos,node_project_repo,node_protocol_repo,node_report_repo,node_attachments toneMint
class node_ai_ui,node_ai_service,node_ollama_client,node_export_service toneRose
class node_researcher,node_ollama,node_export_formats toneIndigo
```

## Components

### Desktop interface

- [App startup](https://github.com/masdos/khemeia-eln/blob/main/main.py): `main.py`
- [Page router](https://github.com/masdos/khemeia-eln/blob/main/app/ui/router.py): `app/ui/router.py`
- [Experiment pages](https://github.com/masdos/khemeia-eln/blob/main/app/ui/pages/experiment_detail.py): `app/ui/pages/experiment_detail.py`
- [Dashboard](https://github.com/masdos/khemeia-eln/blob/main/app/ui/pages/dashboard.py): `app/ui/pages/dashboard.py`
- [Inventory pages](https://github.com/masdos/khemeia-eln/blob/main/app/ui/pages/inventory.py): `app/ui/pages/inventory.py`
- [Project pages](https://github.com/masdos/khemeia-eln/blob/main/app/ui/pages/project_detail.py): `app/ui/pages/project_detail.py`
- [Protocol pages](https://github.com/masdos/khemeia-eln/blob/main/app/ui/pages/protocol_detail.py): `app/ui/pages/protocol_detail.py`
- [Report pages](https://github.com/masdos/khemeia-eln/blob/main/app/ui/pages/reports.py): `app/ui/pages/reports.py`

### Lab workflows

- [Experiment workflow](https://github.com/masdos/khemeia-eln/blob/main/app/services/experiment_service.py): `app/services/experiment_service.py`
- [Inventory traceability](https://github.com/masdos/khemeia-eln/blob/main/app/services/inventory_service.py): `app/services/inventory_service.py`
- [Project management](https://github.com/masdos/khemeia-eln/blob/main/app/services/project_service.py): `app/services/project_service.py`
- [Protocol management](https://github.com/masdos/khemeia-eln/blob/main/app/services/protocol_service.py): `app/services/protocol_service.py`
- [Saved reports](https://github.com/masdos/khemeia-eln/blob/main/app/services/report_service.py): `app/services/report_service.py`

### Persistence and files

- [SQLite store](https://github.com/masdos/khemeia-eln/blob/main/app/database/connection.py): `app/database/connection.py`
- [Experiment records](https://github.com/masdos/khemeia-eln/blob/main/app/repositories/experiment_repository.py): `app/repositories/experiment_repository.py`
- [Reagent and equipment records](https://github.com/masdos/khemeia-eln/blob/main/app/repositories/reagent_repository.py): `app/repositories/reagent_repository.py`
- [Project records](https://github.com/masdos/khemeia-eln/blob/main/app/repositories/project_repository.py): `app/repositories/project_repository.py`
- [Protocol records](https://github.com/masdos/khemeia-eln/blob/main/app/repositories/protocol_repository.py): `app/repositories/protocol_repository.py`
- [Report records](https://github.com/masdos/khemeia-eln/blob/main/app/repositories/report_repository.py): `app/repositories/report_repository.py`
- [Attachments](https://github.com/masdos/khemeia-eln/blob/main/app/repositories/attachment_repository.py): `app/repositories/attachment_repository.py`

### Local AI and export

- [AI report generator](https://github.com/masdos/khemeia-eln/blob/main/app/ui/pages/ai_report_generator.py): `app/ui/pages/ai_report_generator.py`
- [AI drafting](https://github.com/masdos/khemeia-eln/blob/main/app/services/ai_service.py): `app/services/ai_service.py`
- [Ollama client](https://github.com/masdos/khemeia-eln/blob/main/app/services/ollama_client.py): `app/services/ollama_client.py`
- [Document export](https://github.com/masdos/khemeia-eln/blob/main/app/services/export_service.py): `app/services/export_service.py`

### Other components

- **Researcher**
- **Local Ollama model**
- **Markdown PDF DOCX**

## Connections

- Researcher → App startup: starts app
- App startup → Page router: sets up (evidence: `main.py`)
- Researcher → Page router: navigates
- Page router → Dashboard: renders (evidence: `app/ui/router.py`)
- Page router → Experiment pages: renders (evidence: `app/ui/router.py`)
- Page router → Inventory pages: renders (evidence: `app/ui/router.py`)
- Page router → Project pages: renders (evidence: `app/ui/router.py`)
- Page router → Protocol pages: renders (evidence: `app/ui/router.py`)
- Page router → Report pages: renders (evidence: `app/ui/router.py`)
- Page router → AI report generator: renders (evidence: `app/ui/router.py`)
- Dashboard → Experiment workflow: lists experiments (evidence: `app/ui/pages/dashboard.py`)
- Experiment pages → Experiment workflow: edits experiments (evidence: `app/ui/pages/experiment_detail.py`)
- Experiment pages → Inventory traceability: links resources (evidence: `app/ui/pages/experiment_detail.py`)
- Experiment pages → Project management: loads project (evidence: `app/ui/pages/experiment_detail.py`)
- Experiment pages → Protocol management: loads protocol (evidence: `app/ui/pages/experiment_detail.py`)
- Experiment pages → Document export: exports experiment (evidence: `app/ui/pages/experiment_detail.py`)
- Inventory pages → Inventory traceability: manages stock (evidence: `app/ui/pages/inventory.py`)
- Project pages → Project management: manages projects (evidence: `app/ui/pages/project_detail.py`)
- Protocol pages → Protocol management: manages protocols
- Report pages → Saved reports: manages reports (evidence: `app/ui/pages/reports.py`)
- AI report generator → AI drafting: requests drafts (evidence: `app/ui/pages/ai_report_generator.py`)
- AI report generator → Document export: exports reports (evidence: `app/ui/pages/ai_report_generator.py`)
- Experiment workflow → Experiment records: reads and writes (evidence: `app/services/experiment_service.py`)
- Inventory traceability → Reagent and equipment records: reads and writes (evidence: `app/services/inventory_service.py`)
- Project management → Project records: reads and writes (evidence: `app/services/project_service.py`)
- Protocol management → Protocol records: reads and writes (evidence: `app/services/protocol_service.py`)
- Saved reports → Report records: reads and writes (evidence: `app/services/report_service.py`)
- Experiment records → SQLite store: queries (evidence: `app/repositories/experiment_repository.py`)
- Reagent and equipment records → SQLite store: queries (evidence: `app/repositories/reagent_repository.py`)
- Project records → SQLite store: queries
- Protocol records → SQLite store: queries
- Report records → SQLite store: queries
- AI drafting → Ollama client: uses client (evidence: `app/services/ai_service.py`)
- Ollama client → Local Ollama model: sends prompts
- Document export → Experiment records: reads experiment (evidence: `app/services/export_service.py`)
- Document export → Reagent and equipment records: reads resources (evidence: `app/services/export_service.py`)
- Document export → Project records: reads project (evidence: `app/services/export_service.py`)
- Document export → Protocol records: reads protocol (evidence: `app/services/export_service.py`)
- Document export → Attachments: reads attachments (evidence: `app/services/export_service.py`)
- Document export → Report records: reads reports (evidence: `app/services/export_service.py`)
- Document export → Markdown PDF DOCX: writes files (evidence: `app/services/export_service.py`)
