oai-swift/DEVELOPMENT.md

oAI — Development Guide

Project Structure

oAI/
├── Models/              # Data models
│   ├── Message.swift           # Chat message model
│   ├── Conversation.swift      # Saved conversation model
│   ├── ModelInfo.swift         # AI model metadata
│   └── Settings.swift          # App settings enums
│
├── Views/               # SwiftUI views
│   ├── Main/                   # Primary UI components
│   │   ├── ChatView.swift      # Main chat interface
│   │   ├── MessageRow.swift    # Individual message display
│   │   ├── InputBar.swift      # Message input with commands
│   │   ├── HeaderView.swift    # Top bar (provider/model/status)
│   │   └── FooterView.swift    # Bottom stats bar
│   │
│   └── Screens/                # Modal/sheet views
│       ├── SettingsView.swift  # Settings with tabs
│       ├── ModelSelectorView.swift
│       ├── ConversationListView.swift
│       └── HelpView.swift
│
├── ViewModels/          # Observable view models
│   └── ChatViewModel.swift     # Main chat logic & state
│
├── Providers/           # AI provider implementations
│   ├── Provider.swift          # Protocol definition
│   ├── OpenRouterProvider.swift
│   ├── AnthropicProvider.swift
│   ├── OpenAIProvider.swift
│   └── OllamaProvider.swift
│
├── Services/            # Business logic & data
│   ├── DatabaseService.swift   # SQLite operations (GRDB)
│   ├── SettingsService.swift   # Settings persistence
│   ├── ProviderRegistry.swift  # AI provider management
│   ├── MCPService.swift        # File access (MCP)
│   ├── WebSearchService.swift  # DuckDuckGo/Google search
│   ├── GitSyncService.swift    # Git synchronization
│   ├── ContextSelectionService.swift  # Smart context
│   ├── EmbeddingService.swift  # Semantic search
│   ├── EmailService.swift      # Email monitoring (IMAP)
│   └── EmailHandlerService.swift  # Email AI responder
│
└── Resources/
    └── oAI.help/               # macOS Help Book

Key Technologies

• SwiftUI - Modern declarative UI framework
• GRDB - SQLite database wrapper for persistence
• MarkdownUI - Markdown rendering with syntax highlighting
• os.Logger - Native logging framework
• Network Framework - Pure Swift IMAP/SMTP implementation
• Security Framework - Keychain and encryption services

Database Schema

Conversations: id, name, createdAt, updatedAt Messages: id, conversationId, role, content, tokens, cost, timestamp Message Metadata: message_id, importance_score, user_starred, summary Message Embeddings: message_id, embedding (BLOB), model, dimension Conversation Summaries: id, conversationId, startIndex, endIndex, summary Email Logs: id, sender, subject, status, timestamp

Location: ~/Library/Application Support/oAI/oai_conversations.db

Building

Build Scripts

Script	Architecture	Output
build.sh	Apple Silicon (arm64)	Installs directly to /Applications
build-dmg.sh	Apple Silicon (arm64)	oAI-<version>-AppleSilicon.dmg on Desktop
build-dmg-universal.sh	Universal (arm64 + x86_64)	oAI-<version>-Universal.dmg on Desktop
build_nb/sv/da/de/en.sh	Apple Silicon (arm64)	Build + launch in specific language

All scripts: find Developer ID cert, clean-build via xcodebuild, re-sign with codesign --options runtime --timestamp, verify. Version is read from MARKETING_VERSION in project.pbxproj.

Manual Build Commands

# Clean build
xcodebuild clean -scheme oAI

# Debug build
xcodebuild -scheme oAI -configuration Debug

# Run tests
xcodebuild test -scheme oAI

Output: ~/Library/Developer/Xcode/DerivedData/oAI-*/Build/Products/Debug/oAI.app

In Xcode: ⌘B build, ⌘R run, ⌘⇧K clean, ⌘. stop.

XProtect Note

XProtect 5331 flags Debug builds (bash + IMAP + file access = RAT signature match). Use ./build.sh (Developer ID signed) for all local testing.

Logs

~/Library/Logs/oAI.log

Performance Notes

• Context Selection: 50-80% token reduction for long conversations
• Semantic Search: ~$0.02-0.15/month for heavy users
• Conversation Export: Markdown format for human readability
• Database: Indexed queries for fast conversation retrieval
• Streaming: Efficient memory usage with AsyncThrowingStream

Contributing

Contributions are welcome! By submitting a pull request you agree that your contribution will be licensed under the AGPL-3.0.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure:

• Code follows Swift style guidelines
• All tests pass
• Documentation is updated
• Commit messages are descriptive

Acknowledgments

• MarkdownUI - Excellent markdown rendering library
• GRDB - Robust SQLite wrapper for Swift
• Anthropic, OpenAI, OpenRouter - AI API providers