142 lines
5.2 KiB
Markdown
142 lines
5.2 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|