# chelmooz/maieutik architecture

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

- Interactive diagram: https://gitdiagram.com/chelmooz/maieutik
- Repository: https://github.com/chelmooz/maieutik

## Overview

Maieutik is a local-first notes indexing and retrieval product, with companion API/web and egui applications and Laya System 1 primitives. The documented end-to-end path is scanning and extracting notes, embedding and indexing them, then semantic, lexical, or hybrid retrieval; file watching maintains the index. Chat/generation and several MCP methods are partial or stubbed. The graph preserves documented capabilities, while unsampled subsystem internals and cross-process wiring are shown only where README evidence supports them.

Main entry points: [`laya-primitives/src/lib.rs`](https://github.com/chelmooz/maieutik/blob/main/laya-primitives/src/lib.rs) (Laya System), [`maieutik/src/core/retrieval/mod.rs`](https://github.com/chelmooz/maieutik/blob/main/maieutik/src/core/retrieval/mod.rs) (Search Modes), [`maieutik/src/core/indexer/mod.rs`](https://github.com/chelmooz/maieutik/blob/main/maieutik/src/core/indexer/mod.rs) (Chunk and Index), [`maieutik/src/lib.rs`](https://github.com/chelmooz/maieutik/blob/main/maieutik/src/lib.rs) (Application State)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User Interfaces"]
  node_web["Web UI<br/>[App.tsx]"]
  node_webchat["Chat Hook<br/>[useChat.ts]"]
  node_webfiles["File API Client<br/>[client.ts]"]
  node_egui["Desktop UI<br/>[app.rs]"]
  node_ui_backend["UI Backend<br/>[backend.rs]"]
  node_ui_pipeline["Hybrid Pipeline<br/>[pipeline.rs]"]
  node_ui_ports["UI Ports<br/>[ports.rs]"]
end

subgraph group_api["API and MCP"]
  node_api_state["API State<br/>[app.rs]"]
  node_api_routes["REST Routes<br/>[mod.rs]"]
  node_api_adapters["API Adapters<br/>[adapters.rs]"]
  node_mcp["MCP Bridge<br/>[mod.rs]"]
  node_mcp_http["MCP HTTP<br/>[http.rs]"]
end

subgraph group_core["Index and Retrieval"]
  node_app_state["Application State<br/>[lib.rs]"]
  node_config[("Configuration Store<br/>[store.rs]")]
  node_scan["File Scan<br/>[scan.rs]"]
  node_extract["Text Extraction<br/>[mod.rs]"]
  node_indexer[("Chunk and Index<br/>[mod.rs]")]
  node_embed_cache["Embedding Cache<br/>[embedding_cache.rs]"]
  node_watch["File Watcher<br/>[watch.rs]"]
  node_retrieval["Search Modes<br/>[mod.rs]"]
  node_bm25["BM25 Search<br/>[bm25.rs]"]
  node_fusion["RRF Fusion<br/>[fusion.rs]"]
  node_passages["Passage Selection<br/>[passage.rs]"]
  node_query["Query Processing<br/>[query.rs]"]
end

subgraph group_ai["AI and Models"]
  node_llm["Generation<br/>[mod.rs]"]
  node_models["Model Management<br/>[mod.rs]"]
  node_speech["Speech Stub<br/>[mod.rs]"]
end

subgraph group_laya["Laya Primitives"]
  node_laya_lib["Laya System<br/>[lib.rs]"]
  node_encoder["Shared Encoder<br/>[mod.rs]"]
  node_noul["Safety Guard<br/>[mod.rs]"]
  node_choice["Intent Router<br/>[mod.rs]"]
  node_score["RAG Scorer<br/>[mod.rs]"]
  node_batch["Batch Inference<br/>[mod.rs]"]
end

node_user(("User"))

node_user -->|"uses"| node_web
node_user -->|"queries"| node_egui
node_web -->|"uses"| node_webchat
node_web -.->|"loads files"| node_webfiles
node_webchat -.->|"posts chat"| node_api_routes
node_webfiles -.->|"requests files"| node_api_routes
node_egui -->|"dispatches commands"| node_ui_backend
node_ui_backend -->|"runs"| node_ui_pipeline
node_ui_pipeline -->|"uses search and AI ports"| node_ui_ports
node_api_state -->|"constructs"| node_api_adapters
node_api_routes -->|"uses state"| node_api_state
node_api_adapters -->|"reads index"| node_app_state
node_api_state -->|"configures Ollama"| node_llm
node_app_state -->|"loads settings"| node_config
node_app_state -->|"runs watcher"| node_watch
node_watch -->|"reindexes changes"| node_indexer
node_app_state -->|"initializes indexing"| node_scan
node_scan -.->|"indexes files"| node_indexer
node_indexer -.->|"extracts text"| node_extract
node_indexer -->|"caches embeddings"| node_embed_cache
node_indexer -->|"supports search"| node_retrieval
node_retrieval -.->|"processes queries"| node_query
node_retrieval -.->|"runs lexical mode"| node_bm25
node_retrieval -.->|"fuses rankings"| node_fusion
node_retrieval -.->|"selects passages"| node_passages
node_mcp -->|"routes search"| node_retrieval
node_mcp -->|"routes generation"| node_llm
node_mcp -->|"uses transport"| node_mcp_http
node_llm -.->|"uses local models"| node_models
node_speech -.->|"planned voice input"| node_user
node_laya_lib -->|"loads shared encoder"| node_encoder
node_laya_lib -->|"loads guard"| node_noul
node_laya_lib -->|"loads router"| node_choice
node_laya_lib -->|"loads scorer"| node_score
node_laya_lib -->|"creates batch inference"| node_batch
node_ui_pipeline -.->|"optional reranking and guard"| node_laya_lib

click node_web "https://github.com/chelmooz/maieutik/blob/main/maieutik-web/src/App.tsx"
click node_webchat "https://github.com/chelmooz/maieutik/blob/main/maieutik-web/src/hooks/useChat.ts"
click node_webfiles "https://github.com/chelmooz/maieutik/blob/main/maieutik-web/src/api/client.ts"
click node_egui "https://github.com/chelmooz/maieutik/blob/main/maieutik-ui/src/app.rs"
click node_ui_backend "https://github.com/chelmooz/maieutik/blob/main/maieutik-ui/src/backend.rs"
click node_ui_pipeline "https://github.com/chelmooz/maieutik/blob/main/maieutik-ui/src/pipeline.rs"
click node_ui_ports "https://github.com/chelmooz/maieutik/blob/main/maieutik-ui/src/ports.rs"
click node_api_state "https://github.com/chelmooz/maieutik/blob/main/maieutik-api/src/app.rs"
click node_api_routes "https://github.com/chelmooz/maieutik/blob/main/maieutik-api/src/routes/mod.rs"
click node_api_adapters "https://github.com/chelmooz/maieutik/blob/main/maieutik-api/src/adapters.rs"
click node_mcp "https://github.com/chelmooz/maieutik/blob/main/maieutik/src/mcp/mod.rs"
click node_mcp_http "https://github.com/chelmooz/maieutik/blob/main/maieutik/src/mcp/http.rs"
click node_app_state "https://github.com/chelmooz/maieutik/blob/main/maieutik/src/lib.rs"
click node_config "https://github.com/chelmooz/maieutik/blob/main/maieutik/src/config/store.rs"
click node_scan "https://github.com/chelmooz/maieutik/blob/main/maieutik/src/core/scan.rs"
click node_extract "https://github.com/chelmooz/maieutik/blob/main/maieutik/src/utils/mod.rs"
click node_indexer "https://github.com/chelmooz/maieutik/blob/main/maieutik/src/core/indexer/mod.rs"
click node_embed_cache "https://github.com/chelmooz/maieutik/blob/main/maieutik/src/core/embedding_cache.rs"
click node_watch "https://github.com/chelmooz/maieutik/blob/main/maieutik/src/core/watch.rs"
click node_retrieval "https://github.com/chelmooz/maieutik/blob/main/maieutik/src/core/retrieval/mod.rs"
click node_bm25 "https://github.com/chelmooz/maieutik/blob/main/maieutik/src/core/retrieval/bm25.rs"
click node_fusion "https://github.com/chelmooz/maieutik/blob/main/maieutik/src/core/retrieval/fusion.rs"
click node_passages "https://github.com/chelmooz/maieutik/blob/main/maieutik/src/core/retrieval/passage.rs"
click node_query "https://github.com/chelmooz/maieutik/blob/main/maieutik/src/core/retrieval/query.rs"
click node_llm "https://github.com/chelmooz/maieutik/blob/main/maieutik/src/llm/mod.rs"
click node_models "https://github.com/chelmooz/maieutik/blob/main/maieutik/src/model/mod.rs"
click node_speech "https://github.com/chelmooz/maieutik/blob/main/maieutik/src/speech/mod.rs"
click node_laya_lib "https://github.com/chelmooz/maieutik/blob/main/laya-primitives/src/lib.rs"
click node_encoder "https://github.com/chelmooz/maieutik/blob/main/laya-primitives/src/encoder/mod.rs"
click node_noul "https://github.com/chelmooz/maieutik/blob/main/laya-primitives/src/noul/mod.rs"
click node_choice "https://github.com/chelmooz/maieutik/blob/main/laya-primitives/src/choice/mod.rs"
click node_score "https://github.com/chelmooz/maieutik/blob/main/laya-primitives/src/score/mod.rs"
click node_batch "https://github.com/chelmooz/maieutik/blob/main/laya-primitives/src/batch/mod.rs"

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_web,node_webchat,node_webfiles,node_egui,node_ui_backend,node_ui_pipeline,node_ui_ports,node_user toneBlue
class node_api_state,node_api_routes,node_api_adapters,node_mcp,node_mcp_http toneAmber
class node_app_state,node_config,node_scan,node_extract,node_indexer,node_embed_cache,node_watch,node_retrieval,node_bm25,node_fusion,node_passages,node_query toneMint
class node_llm,node_models,node_speech toneRose
class node_laya_lib,node_encoder,node_noul,node_choice,node_score,node_batch toneIndigo
```

## Components

### User Interfaces

- [Web UI](https://github.com/chelmooz/maieutik/blob/main/maieutik-web/src/App.tsx): `maieutik-web/src/App.tsx`
- [Chat Hook](https://github.com/chelmooz/maieutik/blob/main/maieutik-web/src/hooks/useChat.ts): `maieutik-web/src/hooks/useChat.ts`
- [File API Client](https://github.com/chelmooz/maieutik/blob/main/maieutik-web/src/api/client.ts): `maieutik-web/src/api/client.ts`
- [Desktop UI](https://github.com/chelmooz/maieutik/blob/main/maieutik-ui/src/app.rs): `maieutik-ui/src/app.rs`
- [UI Backend](https://github.com/chelmooz/maieutik/blob/main/maieutik-ui/src/backend.rs): `maieutik-ui/src/backend.rs`
- [Hybrid Pipeline](https://github.com/chelmooz/maieutik/blob/main/maieutik-ui/src/pipeline.rs): `maieutik-ui/src/pipeline.rs`
- [UI Ports](https://github.com/chelmooz/maieutik/blob/main/maieutik-ui/src/ports.rs): `maieutik-ui/src/ports.rs`

### API and MCP

- [API State](https://github.com/chelmooz/maieutik/blob/main/maieutik-api/src/app.rs): `maieutik-api/src/app.rs`
- [REST Routes](https://github.com/chelmooz/maieutik/blob/main/maieutik-api/src/routes/mod.rs): `maieutik-api/src/routes/mod.rs`
- [API Adapters](https://github.com/chelmooz/maieutik/blob/main/maieutik-api/src/adapters.rs): `maieutik-api/src/adapters.rs`
- [MCP Bridge](https://github.com/chelmooz/maieutik/blob/main/maieutik/src/mcp/mod.rs): `maieutik/src/mcp/mod.rs`
- [MCP HTTP](https://github.com/chelmooz/maieutik/blob/main/maieutik/src/mcp/http.rs): `maieutik/src/mcp/http.rs`

### Index and Retrieval

- [Application State](https://github.com/chelmooz/maieutik/blob/main/maieutik/src/lib.rs): `maieutik/src/lib.rs`
- [Configuration Store](https://github.com/chelmooz/maieutik/blob/main/maieutik/src/config/store.rs): `maieutik/src/config/store.rs`
- [File Scan](https://github.com/chelmooz/maieutik/blob/main/maieutik/src/core/scan.rs): `maieutik/src/core/scan.rs`
- [Text Extraction](https://github.com/chelmooz/maieutik/blob/main/maieutik/src/utils/mod.rs): `maieutik/src/utils/mod.rs`
- [Chunk and Index](https://github.com/chelmooz/maieutik/blob/main/maieutik/src/core/indexer/mod.rs): `maieutik/src/core/indexer/mod.rs`
- [Embedding Cache](https://github.com/chelmooz/maieutik/blob/main/maieutik/src/core/embedding_cache.rs): `maieutik/src/core/embedding_cache.rs`
- [File Watcher](https://github.com/chelmooz/maieutik/blob/main/maieutik/src/core/watch.rs): `maieutik/src/core/watch.rs`
- [Search Modes](https://github.com/chelmooz/maieutik/blob/main/maieutik/src/core/retrieval/mod.rs): `maieutik/src/core/retrieval/mod.rs`
- [BM25 Search](https://github.com/chelmooz/maieutik/blob/main/maieutik/src/core/retrieval/bm25.rs): `maieutik/src/core/retrieval/bm25.rs`
- [RRF Fusion](https://github.com/chelmooz/maieutik/blob/main/maieutik/src/core/retrieval/fusion.rs): `maieutik/src/core/retrieval/fusion.rs`
- [Passage Selection](https://github.com/chelmooz/maieutik/blob/main/maieutik/src/core/retrieval/passage.rs): `maieutik/src/core/retrieval/passage.rs`
- [Query Processing](https://github.com/chelmooz/maieutik/blob/main/maieutik/src/core/retrieval/query.rs): `maieutik/src/core/retrieval/query.rs`

### AI and Models

- [Generation](https://github.com/chelmooz/maieutik/blob/main/maieutik/src/llm/mod.rs): `maieutik/src/llm/mod.rs`
- [Model Management](https://github.com/chelmooz/maieutik/blob/main/maieutik/src/model/mod.rs): `maieutik/src/model/mod.rs`
- [Speech Stub](https://github.com/chelmooz/maieutik/blob/main/maieutik/src/speech/mod.rs): `maieutik/src/speech/mod.rs`

### Laya Primitives

- [Laya System](https://github.com/chelmooz/maieutik/blob/main/laya-primitives/src/lib.rs): `laya-primitives/src/lib.rs`
- [Shared Encoder](https://github.com/chelmooz/maieutik/blob/main/laya-primitives/src/encoder/mod.rs): `laya-primitives/src/encoder/mod.rs`
- [Safety Guard](https://github.com/chelmooz/maieutik/blob/main/laya-primitives/src/noul/mod.rs): `laya-primitives/src/noul/mod.rs`
- [Intent Router](https://github.com/chelmooz/maieutik/blob/main/laya-primitives/src/choice/mod.rs): `laya-primitives/src/choice/mod.rs`
- [RAG Scorer](https://github.com/chelmooz/maieutik/blob/main/laya-primitives/src/score/mod.rs): `laya-primitives/src/score/mod.rs`
- [Batch Inference](https://github.com/chelmooz/maieutik/blob/main/laya-primitives/src/batch/mod.rs): `laya-primitives/src/batch/mod.rs`

### Other components

- **User**

## Connections

- User → Web UI: uses (evidence: `maieutik-web/src/App.tsx`)
- User → Desktop UI: queries (evidence: `maieutik-ui/src/app.rs`)
- Web UI → Chat Hook: uses
- Web UI → File API Client: loads files
- Chat Hook → REST Routes: posts chat (evidence: `maieutik-web/src/hooks/useChat.ts`)
- File API Client → REST Routes: requests files (evidence: `maieutik-web/src/api/client.ts`)
- Desktop UI → UI Backend: dispatches commands (evidence: `maieutik-ui/src/app.rs`)
- UI Backend → Hybrid Pipeline: runs (evidence: `maieutik-ui/src/backend.rs`)
- Hybrid Pipeline → UI Ports: uses search and AI ports (evidence: `maieutik-ui/src/pipeline.rs`)
- API State → API Adapters: constructs (evidence: `maieutik-api/src/app.rs`)
- REST Routes → API State: uses state (evidence: `maieutik-api/src/routes/mod.rs`)
- API Adapters → Application State: reads index
- API State → Generation: configures Ollama (evidence: `maieutik-api/src/app.rs`)
- Application State → Configuration Store: loads settings (evidence: `maieutik/src/lib.rs`)
- Application State → File Watcher: runs watcher (evidence: `maieutik/src/lib.rs`)
- File Watcher → Chunk and Index: reindexes changes (evidence: `maieutik/src/lib.rs`)
- Application State → File Scan: initializes indexing (evidence: `maieutik/src/lib.rs`)
- File Scan → Chunk and Index: indexes files (evidence: `README.md`)
- Chunk and Index → Text Extraction: extracts text (evidence: `README.md`)
- Chunk and Index → Embedding Cache: caches embeddings (evidence: `maieutik/src/core/indexer/mod.rs`)
- Chunk and Index → Search Modes: supports search (evidence: `maieutik/src/core/indexer/mod.rs`)
- Search Modes → Query Processing: processes queries (evidence: `README.md`)
- Search Modes → BM25 Search: runs lexical mode (evidence: `README.md`)
- Search Modes → RRF Fusion: fuses rankings (evidence: `README.md`)
- Search Modes → Passage Selection: selects passages (evidence: `README.md`)
- MCP Bridge → Search Modes: routes search (evidence: `maieutik/src/mcp/mod.rs`)
- MCP Bridge → Generation: routes generation (evidence: `maieutik/src/mcp/mod.rs`)
- MCP Bridge → MCP HTTP: uses transport (evidence: `maieutik/src/mcp/mod.rs`)
- Generation → Model Management: uses local models
- Speech Stub → User: planned voice input (evidence: `README.md`)
- Laya System → Shared Encoder: loads shared encoder (evidence: `laya-primitives/src/lib.rs`)
- Laya System → Safety Guard: loads guard (evidence: `laya-primitives/src/lib.rs`)
- Laya System → Intent Router: loads router (evidence: `laya-primitives/src/lib.rs`)
- Laya System → RAG Scorer: loads scorer (evidence: `laya-primitives/src/lib.rs`)
- Laya System → Batch Inference: creates batch inference (evidence: `laya-primitives/src/lib.rs`)
- Hybrid Pipeline → Laya System: optional reranking and guard