# renset/macai architecture

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

- Interactive diagram: https://gitdiagram.com/renset/macai
- Repository: https://github.com/renset/macai

## Overview

macai is a native macOS AI chat client. Users configure an API service and persona, compose a message (optionally with attachments), send it through the chat workflow to an AI provider, and view the response in the conversation. Chats and settings are persisted locally, with optional iCloud sync; preferences also expose service, persona, backup/restore, and general settings. The source index supports the central UI, message, persistence, and attachment relationships below; some capability links are documented in the README, while unsampled implementation details are left unconnected.

Main entry points: [`macai/macaiApp.swift`](https://github.com/renset/macai/blob/main/macai/macaiApp.swift) (App shell), [`macai/UI/Chat/ChatLogicHandler.swift`](https://github.com/renset/macai/blob/main/macai/UI/Chat/ChatLogicHandler.swift) (Chat actions), [`macai/Store/ChatStore.swift`](https://github.com/renset/macai/blob/main/macai/Store/ChatStore.swift) (Chat persistence), [`macai/UI/Preferences/PreferencesView.swift`](https://github.com/renset/macai/blob/main/macai/UI/Preferences/PreferencesView.swift) (Preferences)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_chat["Chat workflow"]
  node_app["App shell<br/>[macaiApp.swift]"]
  node_content["Main content<br/>[ContentView.swift]"]
  node_chatui["Chat interface<br/>[ChatView.swift]"]
  node_logic["Chat actions"]
  node_viewmodel["Chat view model"]
  node_messages["Message handling"]
  node_messagecontent["Message content"]
  node_attachments["Attachment parsing"]
  node_chatlist["Chat list<br/>[ChatListView.swift]"]
end

subgraph group_ai["AI services"]
  node_provider["AI providers"]
  node_factory["Provider factory"]
end

subgraph group_data["Data and sync"]
  node_chatstore[("Chat persistence<br/>[ChatStore.swift]")]
  node_patcher["Database patching"]
  node_migration["Legacy migration"]
  node_cloudsync["iCloud sync"]
  node_attachmentsmodel["Attachment models"]
end

subgraph group_settings["Preferences"]
  node_preferences["Preferences"]
  node_apisettings["API service settings"]
  node_personas["AI personas"]
  node_backup["Backup and restore"]
  node_tokens[("Token storage<br/>[TokenManager.swift]")]
end

node_user(("Mac user"))
node_externalai(("AI service"))
node_cloudkit(("CloudKit"))

node_user -->|"launches"| node_app
node_app -->|"presents"| node_content
node_content -->|"shows"| node_chatui
node_content -->|"shows"| node_chatlist
node_chatui -.->|"delegates"| node_logic
node_logic -->|"uses"| node_viewmodel
node_viewmodel -->|"uses"| node_messages
node_viewmodel -->|"creates via"| node_factory
node_factory -.->|"selects"| node_provider
node_provider -.->|"requests"| node_externalai
node_messages -.->|"sends messages"| node_externalai
node_messagecontent -->|"parses with"| node_attachments
node_messagecontent -->|"uses"| node_attachmentsmodel
node_logic -->|"handles"| node_attachmentsmodel
node_logic -->|"uses"| node_chatstore
node_preferences -->|"shows"| node_apisettings
node_preferences -->|"shows"| node_personas
node_preferences -->|"uses"| node_chatstore
node_apisettings -->|"uses"| node_tokens
node_apisettings -.->|"configures"| node_provider
node_backup -.->|"backs up"| node_chatstore
node_app -->|"initializes"| node_cloudsync
node_cloudsync -->|"syncs with"| node_cloudkit
node_app -->|"initializes"| node_patcher
node_chatstore -->|"deletes tokens"| node_tokens
node_user -.->|"imports or exports"| node_backup

click node_app "https://github.com/renset/macai/blob/main/macai/macaiApp.swift"
click node_content "https://github.com/renset/macai/blob/main/macai/UI/ContentView.swift"
click node_chatui "https://github.com/renset/macai/blob/main/macai/UI/Chat/ChatView.swift"
click node_logic "https://github.com/renset/macai/blob/main/macai/UI/Chat/ChatLogicHandler.swift"
click node_viewmodel "https://github.com/renset/macai/blob/main/macai/UI/Chat/ChatViewModel.swift"
click node_messages "https://github.com/renset/macai/blob/main/macai/Utilities/MessageManager.swift"
click node_messagecontent "https://github.com/renset/macai/blob/main/macai/Models/MessageContent.swift"
click node_attachments "https://github.com/renset/macai/blob/main/macai/Utilities/AttachmentParser.swift"
click node_chatlist "https://github.com/renset/macai/blob/main/macai/UI/ChatList/ChatListView.swift"
click node_provider "https://github.com/renset/macai/tree/main/macai/Utilities/APIHandlers"
click node_factory "https://github.com/renset/macai/blob/main/macai/Utilities/APIHandlers/APIServiceFactory.swift"
click node_chatstore "https://github.com/renset/macai/blob/main/macai/Store/ChatStore.swift"
click node_patcher "https://github.com/renset/macai/blob/main/macai/Utilities/DatabasePatcher.swift"
click node_migration "https://github.com/renset/macai/blob/main/macai/Store/V1ToV3Migration.swift"
click node_cloudsync "https://github.com/renset/macai/blob/main/macai/Utilities/CloudSyncManager.swift"
click node_attachmentsmodel "https://github.com/renset/macai/blob/main/macai/Models/DocumentAttachment.swift"
click node_preferences "https://github.com/renset/macai/blob/main/macai/UI/Preferences/PreferencesView.swift"
click node_apisettings "https://github.com/renset/macai/blob/main/macai/UI/Preferences/TabAPIServicesView.swift"
click node_personas "https://github.com/renset/macai/blob/main/macai/UI/Preferences/TabAIPersonasView.swift"
click node_backup "https://github.com/renset/macai/blob/main/macai/UI/Preferences/TabBackupRestoreView.swift"
click node_tokens "https://github.com/renset/macai/blob/main/macai/Utilities/TokenManager.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_app,node_content,node_chatui,node_logic,node_viewmodel,node_messages,node_messagecontent,node_attachments,node_chatlist,node_user toneBlue
class node_provider,node_factory toneAmber
class node_chatstore,node_patcher,node_migration,node_cloudsync,node_attachmentsmodel toneMint
class node_preferences,node_apisettings,node_personas,node_backup,node_tokens toneRose
class node_externalai,node_cloudkit toneIndigo
```

## Components

### Chat workflow

- [App shell](https://github.com/renset/macai/blob/main/macai/macaiApp.swift): `macai/macaiApp.swift`
- [Main content](https://github.com/renset/macai/blob/main/macai/UI/ContentView.swift): `macai/UI/ContentView.swift`
- [Chat interface](https://github.com/renset/macai/blob/main/macai/UI/Chat/ChatView.swift): `macai/UI/Chat/ChatView.swift`
- [Chat actions](https://github.com/renset/macai/blob/main/macai/UI/Chat/ChatLogicHandler.swift): `macai/UI/Chat/ChatLogicHandler.swift`
- [Chat view model](https://github.com/renset/macai/blob/main/macai/UI/Chat/ChatViewModel.swift): `macai/UI/Chat/ChatViewModel.swift`
- [Message handling](https://github.com/renset/macai/blob/main/macai/Utilities/MessageManager.swift): `macai/Utilities/MessageManager.swift`
- [Message content](https://github.com/renset/macai/blob/main/macai/Models/MessageContent.swift): `macai/Models/MessageContent.swift`
- [Attachment parsing](https://github.com/renset/macai/blob/main/macai/Utilities/AttachmentParser.swift): `macai/Utilities/AttachmentParser.swift`
- [Chat list](https://github.com/renset/macai/blob/main/macai/UI/ChatList/ChatListView.swift): `macai/UI/ChatList/ChatListView.swift`

### AI services

- [AI providers](https://github.com/renset/macai/tree/main/macai/Utilities/APIHandlers): `macai/Utilities/APIHandlers`
- [Provider factory](https://github.com/renset/macai/blob/main/macai/Utilities/APIHandlers/APIServiceFactory.swift): `macai/Utilities/APIHandlers/APIServiceFactory.swift`

### Data and sync

- [Chat persistence](https://github.com/renset/macai/blob/main/macai/Store/ChatStore.swift): `macai/Store/ChatStore.swift`
- [Database patching](https://github.com/renset/macai/blob/main/macai/Utilities/DatabasePatcher.swift): `macai/Utilities/DatabasePatcher.swift`
- [Legacy migration](https://github.com/renset/macai/blob/main/macai/Store/V1ToV3Migration.swift): `macai/Store/V1ToV3Migration.swift`
- [iCloud sync](https://github.com/renset/macai/blob/main/macai/Utilities/CloudSyncManager.swift): `macai/Utilities/CloudSyncManager.swift`
- [Attachment models](https://github.com/renset/macai/blob/main/macai/Models/DocumentAttachment.swift): `macai/Models/DocumentAttachment.swift`

### Preferences

- [Preferences](https://github.com/renset/macai/blob/main/macai/UI/Preferences/PreferencesView.swift): `macai/UI/Preferences/PreferencesView.swift`
- [API service settings](https://github.com/renset/macai/blob/main/macai/UI/Preferences/TabAPIServicesView.swift): `macai/UI/Preferences/TabAPIServicesView.swift`
- [AI personas](https://github.com/renset/macai/blob/main/macai/UI/Preferences/TabAIPersonasView.swift): `macai/UI/Preferences/TabAIPersonasView.swift`
- [Backup and restore](https://github.com/renset/macai/blob/main/macai/UI/Preferences/TabBackupRestoreView.swift): `macai/UI/Preferences/TabBackupRestoreView.swift`
- [Token storage](https://github.com/renset/macai/blob/main/macai/Utilities/TokenManager.swift): `macai/Utilities/TokenManager.swift`

### Other components

- **Mac user**
- **AI service**
- **CloudKit**

## Connections

- Mac user → App shell: launches (evidence: `macai/macaiApp.swift`)
- App shell → Main content: presents (evidence: `macai/macaiApp.swift`)
- Main content → Chat interface: shows (evidence: `macai/UI/ContentView.swift`)
- Main content → Chat list: shows (evidence: `macai/UI/ContentView.swift`)
- Chat interface → Chat actions: delegates
- Chat actions → Chat view model: uses (evidence: `macai/UI/Chat/ChatLogicHandler.swift`)
- Chat view model → Message handling: uses (evidence: `macai/UI/Chat/ChatViewModel.swift`)
- Chat view model → Provider factory: creates via (evidence: `macai/UI/Chat/ChatViewModel.swift`)
- Provider factory → AI providers: selects
- AI providers → AI service: requests
- Message handling → AI service: sends messages
- Message content → Attachment parsing: parses with (evidence: `macai/Models/MessageContent.swift`)
- Message content → Attachment models: uses (evidence: `macai/Models/MessageContent.swift`)
- Chat actions → Attachment models: handles (evidence: `macai/UI/Chat/ChatLogicHandler.swift`)
- Chat actions → Chat persistence: uses (evidence: `macai/UI/Chat/ChatLogicHandler.swift`)
- Preferences → API service settings: shows (evidence: `macai/UI/Preferences/PreferencesView.swift`)
- Preferences → AI personas: shows (evidence: `macai/UI/Preferences/PreferencesView.swift`)
- Preferences → Chat persistence: uses (evidence: `macai/UI/Preferences/PreferencesView.swift`)
- API service settings → Token storage: uses (evidence: `macai/UI/Preferences/TabAPIServicesView.swift`)
- API service settings → AI providers: configures
- Backup and restore → Chat persistence: backs up
- App shell → iCloud sync: initializes (evidence: `macai/macaiApp.swift`)
- iCloud sync → CloudKit: syncs with (evidence: `macai/Utilities/CloudSyncManager.swift`)
- App shell → Database patching: initializes (evidence: `macai/macaiApp.swift`)
- Chat persistence → Token storage: deletes tokens (evidence: `macai/Store/ChatStore.swift`)
- Mac user → Backup and restore: imports or exports