# fujacob/cotabby architecture

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

- Interactive diagram: https://gitdiagram.com/fujacob/cotabby
- Repository: https://github.com/fujacob/cotabby

## Overview

Cotabby is a macOS-wide, local-first autocomplete app. Its main workflow observes typing and the focused field, builds a contextual suggestion request, routes generation to the selected engine, then presents ghost text for wordwise acceptance or dismissal. Separate inline features provide emoji completion and macros; settings cover engines and model downloads, while optional screen context and spelling support enrich writing assistance. README documents these capabilities; sampled runtime source confirms engine routing and backend adaptation, but coordinator wiring is not fully shown in the excerpts.

Main entry points: [`Cotabby/App/Coordinators/Suggestion/SuggestionCoordinator.swift`](https://github.com/fujacob/cotabby/blob/main/Cotabby/App/Coordinators/Suggestion/SuggestionCoordinator.swift) (Suggestion coordinator), [`Cotabby/Services/Runtime/SuggestionEngineRouter.swift`](https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/Runtime/SuggestionEngineRouter.swift) (Engine router), [`Cotabby/Services/Runtime/Llama/LlamaSuggestionEngine.swift`](https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/Runtime/Llama/LlamaSuggestionEngine.swift) (Open-source engine), [`Cotabby/Services/Runtime/OpenAICompatible/OpenAICompatibleSuggestionEngine.swift`](https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/Runtime/OpenAICompatible/OpenAICompatibleSuggestionEngine.swift) (Compatible endpoint engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App workflow"]
  node_input["Input monitoring<br/>[InputMonitor.swift]"]
  node_coordinator["Suggestion coordinator"]
  node_presentation["Suggestion presentation"]
  node_overlay["Ghost-text overlay"]
  node_inserter["Suggestion insertion"]
end

subgraph group_suggest["Suggestion runtime"]
  node_request["Suggestion request"]
  node_router["Engine router"]
  node_apple["Apple Intelligence"]
  node_llama["Open-source engine"]
  node_llama_runtime["Local model runtime"]
  node_endpoint["Compatible endpoint engine"]
end

subgraph group_inline["Inline features"]
  node_emoji["Emoji completion"]
  node_emoji_view["Emoji picker"]
  node_macro["Inline macros"]
  node_macro_engine["Macro evaluation<br/>[MacroEngine.swift]"]
end

subgraph group_context["Context and focus"]
  node_focus["Focus tracking<br/>[FocusTracker.swift]"]
  node_visual["Screen context"]
  node_clipboard["Clipboard context"]
  node_spelling["Spelling correction"]
end

subgraph group_config["Settings and models"]
  node_settings["Settings UI"]
  node_settings_model[("Suggestion settings")]
  node_downloads["Model management"]
end

node_user(("Mac user"))
node_host["Focused text field"]
node_service["Configured endpoint"]
node_huggingface["Hugging Face"]

node_user -->|"types in"| node_host
node_input -->|"signals typing"| node_coordinator
node_coordinator -->|"reads focus"| node_focus
node_focus -->|"inspects field"| node_host
node_coordinator -.->|"requests context"| node_visual
node_coordinator -.->|"requests context"| node_clipboard
node_coordinator -->|"builds request"| node_request
node_request -->|"submits request"| node_router
node_router -->|"routes generation"| node_apple
node_router -->|"routes generation"| node_llama
node_router -->|"routes generation"| node_endpoint
node_llama -->|"generates locally"| node_llama_runtime
node_endpoint -.->|"sends request"| node_service
node_apple -->|"returns result"| node_router
node_llama -->|"returns result"| node_router
node_endpoint -.->|"returns result"| node_router
node_router -->|"returns result"| node_coordinator
node_coordinator -->|"presents suggestion"| node_presentation
node_presentation -->|"shows ghost text"| node_overlay
node_user -->|"accepts or dismisses"| node_overlay
node_coordinator -->|"inserts accepted text"| node_inserter
node_inserter -->|"writes text"| node_host
node_user -->|"enters emoji query"| node_emoji
node_emoji -->|"presents picker"| node_emoji_view
node_user -->|"enters macro"| node_macro
node_macro -->|"evaluates query"| node_macro_engine
node_user -->|"configures app"| node_settings
node_settings -->|"updates preferences"| node_settings_model
node_settings -->|"manages models"| node_downloads
node_downloads -.->|"searches/downloads"| node_huggingface
node_coordinator -->|"checks current word"| node_spelling

click node_input "https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/Input/InputMonitor.swift"
click node_coordinator "https://github.com/fujacob/cotabby/blob/main/Cotabby/App/Coordinators/Suggestion/SuggestionCoordinator.swift"
click node_focus "https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/Focus/FocusTracker.swift"
click node_visual "https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/Visual/VisualContextCoordinator.swift"
click node_clipboard "https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/Context/ClipboardContextProvider.swift"
click node_request "https://github.com/fujacob/cotabby/blob/main/Cotabby/Support/Suggestion/Request/SuggestionRequestFactory.swift"
click node_router "https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/Runtime/SuggestionEngineRouter.swift"
click node_apple "https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/Runtime/AppleIntelligence/FoundationModelSuggestionEngine.swift"
click node_llama "https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/Runtime/Llama/LlamaSuggestionEngine.swift"
click node_llama_runtime "https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/Runtime/Llama/LlamaRuntimeManager.swift"
click node_endpoint "https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/Runtime/OpenAICompatible/OpenAICompatibleSuggestionEngine.swift"
click node_presentation "https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/Suggestion/SuggestionOverlayPresenter.swift"
click node_overlay "https://github.com/fujacob/cotabby/blob/main/Cotabby/UI/Overlays/SuggestionOverlayViews.swift"
click node_inserter "https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/Suggestion/SuggestionInserter.swift"
click node_emoji "https://github.com/fujacob/cotabby/blob/main/Cotabby/App/Coordinators/InlineFeatures/EmojiPickerController.swift"
click node_emoji_view "https://github.com/fujacob/cotabby/blob/main/Cotabby/UI/InlineFeatures/EmojiPickerView.swift"
click node_macro "https://github.com/fujacob/cotabby/blob/main/Cotabby/App/Coordinators/InlineFeatures/MacroController.swift"
click node_macro_engine "https://github.com/fujacob/cotabby/blob/main/Cotabby/Support/Macros/MacroEngine.swift"
click node_settings "https://github.com/fujacob/cotabby/blob/main/Cotabby/UI/Settings/SettingsContainerView.swift"
click node_settings_model "https://github.com/fujacob/cotabby/blob/main/Cotabby/Models/Settings/SuggestionSettingsModel.swift"
click node_downloads "https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/ModelManagement/ModelDownloadManager.swift"
click node_spelling "https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/Spelling/CurrentWordSpellChecker.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_input,node_coordinator,node_presentation,node_overlay,node_inserter,node_user toneBlue
class node_request,node_router,node_apple,node_llama,node_llama_runtime,node_endpoint toneAmber
class node_emoji,node_emoji_view,node_macro,node_macro_engine toneMint
class node_focus,node_visual,node_clipboard,node_spelling toneRose
class node_settings,node_settings_model,node_downloads,node_host,node_service,node_huggingface toneIndigo
```

## Components

### App workflow

- [Input monitoring](https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/Input/InputMonitor.swift): `Cotabby/Services/Input/InputMonitor.swift`
- [Suggestion coordinator](https://github.com/fujacob/cotabby/blob/main/Cotabby/App/Coordinators/Suggestion/SuggestionCoordinator.swift): `Cotabby/App/Coordinators/Suggestion/SuggestionCoordinator.swift`
- [Suggestion presentation](https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/Suggestion/SuggestionOverlayPresenter.swift): `Cotabby/Services/Suggestion/SuggestionOverlayPresenter.swift`
- [Ghost-text overlay](https://github.com/fujacob/cotabby/blob/main/Cotabby/UI/Overlays/SuggestionOverlayViews.swift): `Cotabby/UI/Overlays/SuggestionOverlayViews.swift`
- [Suggestion insertion](https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/Suggestion/SuggestionInserter.swift): `Cotabby/Services/Suggestion/SuggestionInserter.swift`

### Suggestion runtime

- [Suggestion request](https://github.com/fujacob/cotabby/blob/main/Cotabby/Support/Suggestion/Request/SuggestionRequestFactory.swift): `Cotabby/Support/Suggestion/Request/SuggestionRequestFactory.swift`
- [Engine router](https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/Runtime/SuggestionEngineRouter.swift): `Cotabby/Services/Runtime/SuggestionEngineRouter.swift`
- [Apple Intelligence](https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/Runtime/AppleIntelligence/FoundationModelSuggestionEngine.swift): `Cotabby/Services/Runtime/AppleIntelligence/FoundationModelSuggestionEngine.swift`
- [Open-source engine](https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/Runtime/Llama/LlamaSuggestionEngine.swift): `Cotabby/Services/Runtime/Llama/LlamaSuggestionEngine.swift`
- [Local model runtime](https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/Runtime/Llama/LlamaRuntimeManager.swift): `Cotabby/Services/Runtime/Llama/LlamaRuntimeManager.swift`
- [Compatible endpoint engine](https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/Runtime/OpenAICompatible/OpenAICompatibleSuggestionEngine.swift): `Cotabby/Services/Runtime/OpenAICompatible/OpenAICompatibleSuggestionEngine.swift`

### Inline features

- [Emoji completion](https://github.com/fujacob/cotabby/blob/main/Cotabby/App/Coordinators/InlineFeatures/EmojiPickerController.swift): `Cotabby/App/Coordinators/InlineFeatures/EmojiPickerController.swift`
- [Emoji picker](https://github.com/fujacob/cotabby/blob/main/Cotabby/UI/InlineFeatures/EmojiPickerView.swift): `Cotabby/UI/InlineFeatures/EmojiPickerView.swift`
- [Inline macros](https://github.com/fujacob/cotabby/blob/main/Cotabby/App/Coordinators/InlineFeatures/MacroController.swift): `Cotabby/App/Coordinators/InlineFeatures/MacroController.swift`
- [Macro evaluation](https://github.com/fujacob/cotabby/blob/main/Cotabby/Support/Macros/MacroEngine.swift): `Cotabby/Support/Macros/MacroEngine.swift`

### Context and focus

- [Focus tracking](https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/Focus/FocusTracker.swift): `Cotabby/Services/Focus/FocusTracker.swift`
- [Screen context](https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/Visual/VisualContextCoordinator.swift): `Cotabby/Services/Visual/VisualContextCoordinator.swift`
- [Clipboard context](https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/Context/ClipboardContextProvider.swift): `Cotabby/Services/Context/ClipboardContextProvider.swift`
- [Spelling correction](https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/Spelling/CurrentWordSpellChecker.swift): `Cotabby/Services/Spelling/CurrentWordSpellChecker.swift`

### Settings and models

- [Settings UI](https://github.com/fujacob/cotabby/blob/main/Cotabby/UI/Settings/SettingsContainerView.swift): `Cotabby/UI/Settings/SettingsContainerView.swift`
- [Suggestion settings](https://github.com/fujacob/cotabby/blob/main/Cotabby/Models/Settings/SuggestionSettingsModel.swift): `Cotabby/Models/Settings/SuggestionSettingsModel.swift`
- [Model management](https://github.com/fujacob/cotabby/blob/main/Cotabby/Services/ModelManagement/ModelDownloadManager.swift): `Cotabby/Services/ModelManagement/ModelDownloadManager.swift`

### Other components

- **Mac user**
- **Focused text field**
- **Configured endpoint**
- **Hugging Face**

## Connections

- Mac user → Focused text field: types in
- Input monitoring → Suggestion coordinator: signals typing
- Suggestion coordinator → Focus tracking: reads focus
- Focus tracking → Focused text field: inspects field
- Suggestion coordinator → Screen context: requests context
- Suggestion coordinator → Clipboard context: requests context
- Suggestion coordinator → Suggestion request: builds request
- Suggestion request → Engine router: submits request
- Engine router → Apple Intelligence: routes generation
- Engine router → Open-source engine: routes generation
- Engine router → Compatible endpoint engine: routes generation
- Open-source engine → Local model runtime: generates locally
- Compatible endpoint engine → Configured endpoint: sends request
- Apple Intelligence → Engine router: returns result
- Open-source engine → Engine router: returns result
- Compatible endpoint engine → Engine router: returns result
- Engine router → Suggestion coordinator: returns result
- Suggestion coordinator → Suggestion presentation: presents suggestion
- Suggestion presentation → Ghost-text overlay: shows ghost text
- Mac user → Ghost-text overlay: accepts or dismisses
- Suggestion coordinator → Suggestion insertion: inserts accepted text
- Suggestion insertion → Focused text field: writes text
- Mac user → Emoji completion: enters emoji query
- Emoji completion → Emoji picker: presents picker
- Mac user → Inline macros: enters macro
- Inline macros → Macro evaluation: evaluates query
- Mac user → Settings UI: configures app
- Settings UI → Suggestion settings: updates preferences
- Settings UI → Model management: manages models
- Model management → Hugging Face: searches/downloads
- Suggestion coordinator → Spelling correction: checks current word