https://github.com/max21dev/banter
Lightning-Fast Native Group Chat over Nostr
https://github.com/max21dev/banter
Last synced: 9 months ago
JSON representation
Lightning-Fast Native Group Chat over Nostr
- Host: GitHub
- URL: https://github.com/max21dev/banter
- Owner: max21dev
- License: mit
- Created: 2025-08-18T13:50:58.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-08-18T15:16:12.000Z (10 months ago)
- Last Synced: 2025-08-18T17:28:26.949Z (10 months ago)
- Language: Swift
- Size: 79.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Banter: Lightning-Fast Native Group Chat over Nostr
> **Note:** This is a work in progress and is not ready for public release.
Banter is a native iOS/macOS application that implements the Nostr protocol for decentralized group chat. It delivers a seamless, instant messaging experience with real-time updates and smooth offline access, ensuring users enjoy responsive performance and uninterrupted conversations.
## ✨ Features
### Core Functionality
- **NIP-29 Group Chat Support** - Full implementation of NIP-29 group chat specification
- **Real-time Messaging** - Live message updates via WebSocket connections
- **Flexible Relay Connections** - Connect to any NIP-29 Nostr relay of your choice with seamless relay switching
- **User Profiles** - Rich user metadata with avatars and bios
- **Group Management** - Join, leave, and manage group memberships
### Advanced Caching System
- **3-Tier Cache Architecture** - Memory, disk, and network caching
- **Offline Support** - Access previously viewed content without internet
- **Smart Prefetching** - Intelligent loading of user profiles and images
- **Cache-First Loading** - Instant UI updates with background refresh
- **Automatic & Manual Cleanup** - Intelligent cache management and expiration, with options for users to trigger manual cache clearing
## 📱 Screenshots & Demos
### App Screenshots
#### macOS
#### iOS
### Screen Recordings
#### macOS
#### iOS
## 🏗️ Architecture
### Caching Components
```
┌─────────────────────┐
│ SwiftUI Views │
├─────────────────────┤
│ Cached Services │ ← CachedGroupChatService, CachedUserMetadataService
├─────────────────────┤
│ Cache Managers │ ← Group, Message, User, Image Cache Managers
├─────────────────────┤
│ Core Data Stack │ ← SQLite persistent storage
├─────────────────────┤
│ Network Layer │ ← NostrRelayManager, WebSocket connections
└─────────────────────┘
```
### Key Files
- **Services/**
- `CachedGroupChatService.swift` - Enhanced group chat with caching
- `CachedUserMetadataService.swift` - User profile caching
- `ImageCacheManager.swift` - Avatar and image caching
- `PersistenceManager.swift` - Core Data management
- `CachePolicyManager.swift` - Cache policies and cleanup
- **Models/**
- `BanterDataModel.xcdatamodeld` - Core Data model
- `NostrModels.swift` - Nostr protocol models
- **Views/**
- `CachedUserAvatarView.swift` - Cached avatar display
- `CacheStatusView.swift` - Cache monitoring UI
## 🚀 Getting Started
### Prerequisites
- iOS 15.0+ / macOS 12.0+
- Xcode 14.0+
- Swift 5.7+
- Basic understanding of Nostr protocol
### Installation
#### Option 1: Clone and Build
```bash
# Clone the repository
git clone https://github.com/max21dev/banter.git
cd banter
# Open in Xcode
open banter.xcodeproj
# Build and run
# Select your target device and press Cmd+R
```
#### Option 2: Build Server Setup (Advanced)
For advanced users who want to use the build server:
```bash
# Copy environment configuration
cp env.example .env
# Edit .env with your paths
nano .env
# Run setup script
chmod +x setup-buildserver.sh
./setup-buildserver.sh
```
### Configuration
The app automatically configures optimal caching settings. To customize:
```swift
// Modify cache policies in CachePolicyManager.swift
struct CachePolicy {
let userProfileExpiration: TimeInterval = 24 * 60 * 60 // 24 hours
let maxMessagesPerGroup: Int = 1000
let maxImageCacheSize: Int64 = 100 * 1024 * 1024 // 100 MB
}
```
## 📖 Usage
### Basic Operations
- **Join Groups**: Connect to NIP-29 relays, discover, and join groups
- **Send Messages**: Real-time messaging with other group members
- **View Profiles**: See user information and avatars
- **Search**: Find groups and messages across all cached content
### Cache Management
- **Automatic**: The app handles all caching automatically
- **Manual Cleanup**: Use the settings to clear the cache
## 🔧 Development
### Project Structure
```
banter/
├── banter/ # Main app source
│ ├── Assets.xcassets/ # App icons and colors
│ ├── Models/ # Data models
│ ├── Network/ # Network layer
│ ├── Services/ # Business logic
│ ├── Utils/ # Utilities
│ └── Views/ # SwiftUI views
├── banterTests/ # Unit tests
├── banterUITests/ # UI tests
└── Documentation/ # Project docs
```
### Building from Source
1. Ensure you have the latest Xcode version
2. Open `banter.xcodeproj` in Xcode
3. Select your target device (iOS Simulator, macOS, or physical device)
4. Press `Cmd+B` to build
5. Press `Cmd+R` to run
### Testing
```bash
# Run unit tests
xcodebuild test -project banter.xcodeproj -scheme banter -destination 'platform=iOS Simulator,name=iPhone 15'
# Run UI tests
xcodebuild test -project banter.xcodeproj -scheme banter -destination 'platform=iOS Simulator,name=iPhone 15' -only-testing:banterUITests
```
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.
### Development Setup
1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes
4. Add tests if applicable
5. Commit your changes: `git commit -m 'Add amazing feature'`
6. Push to the branch: `git push origin feature/amazing-feature`
7. Open a Pull Request
### Code Style
- Follow Swift API Design Guidelines
- Use SwiftLint for code formatting
- Write unit tests for new functionality
- Update documentation for API changes
## 📚 Technical Details
### Nostr Protocol Support
- **NIP-01**: Basic protocol implementation
- **NIP-29**: Group chat specification
- **WebSocket**: Real-time relay connections
- **Cryptography**: Event signing and verification
### Data Flow
1. **Cache Check**: Always check cache first
2. **UI Update**: Immediate display of cached data
3. **Network Fetch**: Background refresh from relays
4. **Cache Update**: Store new data for future use
### Error Handling
- Graceful fallbacks for network issues
- Cache corruption recovery
- Offline mode support
- Connection retry logic
## 🐛 Troubleshooting
### Common Issues
#### Build Errors
- Ensure you have the correct Xcode version
- Clean build folder: `Cmd+Shift+K`
- Reset package caches: `File > Packages > Reset Package Caches`
#### Runtime Issues
- Check relay connectivity in settings
- Verify Nostr identity is properly configured
- Monitor cache status for storage issues
#### Performance Issues
- Check cache hit rates in the status view
- Monitor memory usage
- Verify relay response times
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Nostr protocol community and contributors
- NIP-29 specification authors
- Swift and SwiftUI development teams
- All contributors and testers