# hanxiao/omni-macos architecture

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

- Interactive diagram: https://gitdiagram.com/hanxiao/omni-macos
- Repository: https://github.com/hanxiao/omni-macos

## Overview

Omni is an on-device macOS app for semantic search across files, with browsing, multimodal indexing, optional OCR, folder-embedding visualization, and a localhost HTTP/MCP serving surface. The main workflow is selecting local sources, crawling and extracting content, embedding and indexing it, then searching and browsing results. The README documents multimodal formats, airgapped operation, and serving. Some UI and OCR wiring is unsampled; those links are omitted where source evidence is unavailable.

Main entry points: [`App/AppModel.swift`](https://github.com/hanxiao/omni-macos/blob/main/App/AppModel.swift) (App coordinator), [`Sources/OmniKit/Indexer.swift`](https://github.com/hanxiao/omni-macos/blob/main/Sources/OmniKit/Indexer.swift) (Index pipeline), [`App/Serving/ServingController.swift`](https://github.com/hanxiao/omni-macos/blob/main/App/Serving/ServingController.swift) (Serving controller), [`App/Serving/Router.swift`](https://github.com/hanxiao/omni-macos/blob/main/App/Serving/Router.swift) (Request router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Mac App"]
  node_appmodel["App coordinator<br/>[AppModel.swift]"]
  node_browse["Browse and results<br/>[ContentView.swift]"]
  node_foldermap["Folder embedding map"]
  node_ocrui["OCR interface<br/>[OCRView.swift]"]
end

subgraph group_index["Indexing"]
  node_crawler["File crawler<br/>[FileCrawler.swift]"]
  node_extractor["Content extraction"]
  node_indexer["Index pipeline<br/>[Indexer.swift]"]
end

subgraph group_models["Embedding and OCR"]
  node_engine["Omni embedding engine<br/>[OmniEngine.swift]"]
  node_ocr["OCR model<br/>[OCRModel.swift]"]
end

subgraph group_search["Search and Storage"]
  node_queryparse["Query parser"]
  node_store[("Vector index<br/>[VectorStore.swift]")]
  node_projection["Embedding projection"]
end

subgraph group_serve["Serving"]
  node_controller["Serving controller"]
  node_http["HTTP server<br/>[HTTPServer.swift]"]
  node_router["Request router<br/>[Router.swift]"]
  node_backend["Serving backend"]
  node_mcp["MCP adapter<br/>[MCPAdapter.swift]"]
  node_sourceapi["Sources API"]
end

node_user(("Mac user"))
node_sources["Local sources"]
node_client(("API or MCP client"))

node_user -->|"uses"| node_appmodel
node_sources -->|"crawls"| node_crawler
node_appmodel -->|"starts indexing"| node_indexer
node_indexer -->|"crawls files"| node_crawler
node_crawler -->|"extracts content"| node_extractor
node_indexer -->|"reads content"| node_extractor
node_indexer -->|"embeds content"| node_engine
node_indexer -->|"writes index"| node_store
node_appmodel -->|"loads model"| node_engine
node_appmodel -->|"opens index"| node_store
node_appmodel -->|"parses queries"| node_queryparse
node_appmodel -->|"updates results"| node_browse
node_user -->|"browses"| node_browse
node_appmodel -->|"projects embeddings"| node_projection
node_projection -->|"uses GPU engine"| node_engine
node_appmodel -->|"owns serving"| node_controller
node_controller -->|"attaches backend"| node_backend
node_controller -->|"starts server"| node_http
node_controller -->|"configures routes"| node_router
node_http -.->|"dispatches requests"| node_router
node_router -->|"routes MCP"| node_mcp
node_router -->|"routes sources"| node_sourceapi
node_mcp -->|"calls backend"| node_backend
node_client -->|"sends requests"| node_http
node_backend -->|"embeds queries"| node_engine
node_backend -->|"searches index"| node_store
node_ocrui -.->|"transcribes"| node_ocr
node_indexer -.->|"OCR for scans"| node_ocr

click node_appmodel "https://github.com/hanxiao/omni-macos/blob/main/App/AppModel.swift"
click node_browse "https://github.com/hanxiao/omni-macos/blob/main/App/ContentView.swift"
click node_foldermap "https://github.com/hanxiao/omni-macos/blob/main/App/FolderEmbeddingVisualization.swift"
click node_crawler "https://github.com/hanxiao/omni-macos/blob/main/Sources/OmniKit/FileCrawler.swift"
click node_extractor "https://github.com/hanxiao/omni-macos/blob/main/Sources/OmniKit/FileExtractor.swift"
click node_indexer "https://github.com/hanxiao/omni-macos/blob/main/Sources/OmniKit/Indexer.swift"
click node_engine "https://github.com/hanxiao/omni-macos/blob/main/Sources/OmniKit/OmniEngine.swift"
click node_ocr "https://github.com/hanxiao/omni-macos/blob/main/Sources/OmniKit/OCR/OCRModel.swift"
click node_ocrui "https://github.com/hanxiao/omni-macos/blob/main/App/OCRView.swift"
click node_queryparse "https://github.com/hanxiao/omni-macos/blob/main/Sources/OmniKit/SearchQueryParser.swift"
click node_store "https://github.com/hanxiao/omni-macos/blob/main/Sources/OmniKit/VectorStore.swift"
click node_projection "https://github.com/hanxiao/omni-macos/blob/main/Sources/OmniKit/ProjectionEngine.swift"
click node_controller "https://github.com/hanxiao/omni-macos/blob/main/App/Serving/ServingController.swift"
click node_http "https://github.com/hanxiao/omni-macos/blob/main/App/Serving/HTTPServer.swift"
click node_router "https://github.com/hanxiao/omni-macos/blob/main/App/Serving/Router.swift"
click node_backend "https://github.com/hanxiao/omni-macos/blob/main/App/Serving/ServingBackend.swift"
click node_mcp "https://github.com/hanxiao/omni-macos/blob/main/App/Serving/MCPAdapter.swift"
click node_sourceapi "https://github.com/hanxiao/omni-macos/blob/main/App/Serving/SourcesAdapter.swift"

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_appmodel,node_browse,node_foldermap,node_ocrui,node_user,node_client toneBlue
class node_crawler,node_extractor,node_indexer toneAmber
class node_engine,node_ocr toneMint
class node_queryparse,node_store,node_projection toneRose
class node_controller,node_http,node_router,node_backend,node_mcp,node_sourceapi,node_sources toneIndigo
```

## Components

### Mac App

- [App coordinator](https://github.com/hanxiao/omni-macos/blob/main/App/AppModel.swift): `App/AppModel.swift`
- [Browse and results](https://github.com/hanxiao/omni-macos/blob/main/App/ContentView.swift): `App/ContentView.swift`
- [Folder embedding map](https://github.com/hanxiao/omni-macos/blob/main/App/FolderEmbeddingVisualization.swift): `App/FolderEmbeddingVisualization.swift`
- [OCR interface](https://github.com/hanxiao/omni-macos/blob/main/App/OCRView.swift): `App/OCRView.swift`

### Indexing

- [File crawler](https://github.com/hanxiao/omni-macos/blob/main/Sources/OmniKit/FileCrawler.swift): `Sources/OmniKit/FileCrawler.swift`
- [Content extraction](https://github.com/hanxiao/omni-macos/blob/main/Sources/OmniKit/FileExtractor.swift): `Sources/OmniKit/FileExtractor.swift`
- [Index pipeline](https://github.com/hanxiao/omni-macos/blob/main/Sources/OmniKit/Indexer.swift): `Sources/OmniKit/Indexer.swift`

### Embedding and OCR

- [Omni embedding engine](https://github.com/hanxiao/omni-macos/blob/main/Sources/OmniKit/OmniEngine.swift): `Sources/OmniKit/OmniEngine.swift`
- [OCR model](https://github.com/hanxiao/omni-macos/blob/main/Sources/OmniKit/OCR/OCRModel.swift): `Sources/OmniKit/OCR/OCRModel.swift`

### Search and Storage

- [Query parser](https://github.com/hanxiao/omni-macos/blob/main/Sources/OmniKit/SearchQueryParser.swift): `Sources/OmniKit/SearchQueryParser.swift`
- [Vector index](https://github.com/hanxiao/omni-macos/blob/main/Sources/OmniKit/VectorStore.swift): `Sources/OmniKit/VectorStore.swift`
- [Embedding projection](https://github.com/hanxiao/omni-macos/blob/main/Sources/OmniKit/ProjectionEngine.swift): `Sources/OmniKit/ProjectionEngine.swift`

### Serving

- [Serving controller](https://github.com/hanxiao/omni-macos/blob/main/App/Serving/ServingController.swift): `App/Serving/ServingController.swift`
- [HTTP server](https://github.com/hanxiao/omni-macos/blob/main/App/Serving/HTTPServer.swift): `App/Serving/HTTPServer.swift`
- [Request router](https://github.com/hanxiao/omni-macos/blob/main/App/Serving/Router.swift): `App/Serving/Router.swift`
- [Serving backend](https://github.com/hanxiao/omni-macos/blob/main/App/Serving/ServingBackend.swift): `App/Serving/ServingBackend.swift`
- [MCP adapter](https://github.com/hanxiao/omni-macos/blob/main/App/Serving/MCPAdapter.swift): `App/Serving/MCPAdapter.swift`
- [Sources API](https://github.com/hanxiao/omni-macos/blob/main/App/Serving/SourcesAdapter.swift): `App/Serving/SourcesAdapter.swift`

### Other components

- **Mac user**
- **Local sources**
- **API or MCP client**

## Connections

- Mac user → App coordinator: uses
- Local sources → File crawler: crawls (evidence: `Sources/OmniKit/FileCrawler.swift`)
- App coordinator → Index pipeline: starts indexing (evidence: `App/AppModel.swift`)
- Index pipeline → File crawler: crawls files (evidence: `Sources/OmniKit/Indexer.swift`)
- File crawler → Content extraction: extracts content (evidence: `Sources/OmniKit/FileCrawler.swift`)
- Index pipeline → Content extraction: reads content (evidence: `Sources/OmniKit/Indexer.swift`)
- Index pipeline → Omni embedding engine: embeds content (evidence: `Sources/OmniKit/Indexer.swift`)
- Index pipeline → Vector index: writes index (evidence: `Sources/OmniKit/Indexer.swift`)
- App coordinator → Omni embedding engine: loads model (evidence: `App/AppModel.swift`)
- App coordinator → Vector index: opens index (evidence: `App/AppModel.swift`)
- App coordinator → Query parser: parses queries (evidence: `App/AppModel.swift`)
- App coordinator → Browse and results: updates results (evidence: `App/AppModel.swift`)
- Mac user → Browse and results: browses
- App coordinator → Embedding projection: projects embeddings (evidence: `App/FolderEmbeddingVisualization.swift`)
- Embedding projection → Omni embedding engine: uses GPU engine (evidence: `Sources/OmniKit/ProjectionEngine.swift`)
- App coordinator → Serving controller: owns serving (evidence: `App/Serving/ServingController.swift`)
- Serving controller → Serving backend: attaches backend (evidence: `App/Serving/ServingController.swift`)
- Serving controller → HTTP server: starts server (evidence: `App/Serving/ServingController.swift`)
- Serving controller → Request router: configures routes (evidence: `App/Serving/ServingController.swift`)
- HTTP server → Request router: dispatches requests
- Request router → MCP adapter: routes MCP (evidence: `App/Serving/Router.swift`)
- Request router → Sources API: routes sources (evidence: `App/Serving/Router.swift`)
- MCP adapter → Serving backend: calls backend (evidence: `App/Serving/MCPAdapter.swift`)
- API or MCP client → HTTP server: sends requests
- Serving backend → Omni embedding engine: embeds queries (evidence: `App/Serving/ServingBackend.swift`)
- Serving backend → Vector index: searches index (evidence: `App/Serving/ServingBackend.swift`)
- OCR interface → OCR model: transcribes
- Index pipeline → OCR model: OCR for scans
