Initial commit: Bifrost accessible fediverse client
- Full ActivityPub support for Pleroma, GoToSocial, and Mastodon - Screen reader optimized interface with PySide6 - Timeline switching with tabs and keyboard shortcuts (Ctrl+1-4) - Threaded conversation navigation with expand/collapse - Cross-platform desktop notifications via plyer - Customizable sound pack system with audio feedback - Complete keyboard navigation and accessibility features - XDG Base Directory compliant configuration - Multiple account support with OAuth authentication 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Storm Dragon
386
CLAUDE.md
Normal file
386
CLAUDE.md
Normal file
@ -0,0 +1,386 @@
|
||||
# Bifrost Fediverse Client - Development Plan
|
||||
|
||||
## Project Overview
|
||||
Bifrost is a fully accessible fediverse client built with PySide6, designed specifically for screen reader users. The application uses "post/posts" terminology instead of "toot" and focuses on excellent keyboard navigation and audio feedback.
|
||||
|
||||
## Core Features
|
||||
- Full ActivityPub protocol support (Pleroma and GoToSocial primary targets)
|
||||
- Threaded conversation navigation with collapsible tree view
|
||||
- Customizable sound pack system for audio notifications
|
||||
- Screen reader optimized interface
|
||||
- XDG Base Directory specification compliance
|
||||
|
||||
## Technology Stack
|
||||
- **PySide6**: Main GUI framework (proven accessibility with existing doom launcher)
|
||||
- **requests**: HTTP client for ActivityPub APIs
|
||||
- **simpleaudio**: Cross-platform audio with subprocess fallback
|
||||
- **XDG directories**: Configuration and data storage
|
||||
|
||||
## Architecture
|
||||
|
||||
### Directory Structure
|
||||
```
|
||||
bifrost/
|
||||
├── bifrost/
|
||||
│ ├── __init__.py
|
||||
│ ├── main.py # Application entry point
|
||||
│ ├── accessibility/ # Accessibility widgets and helpers
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── accessible_tree.py # AccessibleTreeWidget for conversations
|
||||
│ │ └── accessible_combo.py # Enhanced ComboBox from doom launcher
|
||||
│ ├── activitypub/ # Federation protocol handling
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── client.py # Main ActivityPub client
|
||||
│ │ ├── pleroma.py # Pleroma-specific implementation
|
||||
│ │ └── gotosocial.py # GoToSocial-specific implementation
|
||||
│ ├── models/ # Data models
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── post.py # Post data structure
|
||||
│ │ ├── user.py # User profiles
|
||||
│ │ ├── timeline.py # Timeline model for QTreeView
|
||||
│ │ └── thread.py # Conversation threading
|
||||
│ ├── widgets/ # Custom UI components
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── timeline_view.py # Main timeline widget
|
||||
│ │ ├── compose_dialog.py # Post composition
|
||||
│ │ ├── settings_dialog.py # Application settings
|
||||
│ │ └── login_dialog.py # Instance login
|
||||
│ ├── audio/ # Sound system
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── sound_manager.py # Audio notification handler
|
||||
│ │ └── sound_pack.py # Sound pack management
|
||||
│ └── config/ # Configuration management
|
||||
│ ├── __init__.py
|
||||
│ ├── settings.py # Settings handler with XDG compliance
|
||||
│ └── accounts.py # Account management
|
||||
├── sounds/ # Sound packs directory
|
||||
│ ├── default/
|
||||
│ │ ├── pack.json
|
||||
│ │ ├── private_message.wav
|
||||
│ │ ├── mention.wav
|
||||
│ │ ├── boost.wav
|
||||
│ │ ├── reply.wav
|
||||
│ │ ├── post_sent.wav
|
||||
│ │ ├── timeline_update.wav
|
||||
│ │ └── notification.wav
|
||||
│ └── doom/ # Example themed sound pack
|
||||
│ ├── pack.json
|
||||
│ └── *.wav files
|
||||
├── tests/
|
||||
│ ├── __init__.py
|
||||
│ ├── test_accessibility.py
|
||||
│ ├── test_activitypub.py
|
||||
│ └── test_audio.py
|
||||
├── requirements.txt
|
||||
├── setup.py
|
||||
└── README.md
|
||||
```
|
||||
|
||||
### XDG Directory Usage
|
||||
- **Config**: `~/.config/bifrost/` - Settings, accounts, current sound pack
|
||||
- **Data**: `~/.local/share/bifrost/` - Sound packs, cached data
|
||||
- **Cache**: `~/.cache/bifrost/` - Temporary files, avatar cache
|
||||
|
||||
## Accessibility Implementation
|
||||
|
||||
### From Doom Launcher Success
|
||||
- **AccessibleComboBox**: Enhanced keyboard navigation (Page Up/Down, Home/End)
|
||||
- **Proper Accessible Names**: All widgets get descriptive `setAccessibleName()`
|
||||
- **Focus Management**: Clear tab order and focus indicators
|
||||
- **No Custom Speech**: Screen reader handles all announcements
|
||||
|
||||
### Threaded Conversation Navigation
|
||||
**Navigation Pattern:**
|
||||
```
|
||||
Timeline Item: "Alice posted: Hello world (3 replies, collapsed)"
|
||||
[Right Arrow] → "Alice posted: Hello world (3 replies, expanded)"
|
||||
[Down Arrow] → " Bob replied: Hi there"
|
||||
[Down Arrow] → " Carol replied: How's it going?"
|
||||
[Down Arrow] → "David posted: Another topic"
|
||||
```
|
||||
|
||||
**Key Behaviors:**
|
||||
- Right Arrow: Expand thread, announce "expanded"
|
||||
- Left Arrow: Collapse thread, announce "collapsed"
|
||||
- Down Arrow: Next item (skip collapsed children)
|
||||
- Up Arrow: Previous item
|
||||
- Page Down/Up: Jump 5 items
|
||||
- Home/End: First/last item
|
||||
|
||||
### AccessibleTreeWidget Requirements
|
||||
- Inherit from QTreeWidget
|
||||
- Override keyPressEvent for custom navigation
|
||||
- Proper accessibility roles and states
|
||||
- Focus management for nested items
|
||||
- Status announcements via Qt accessibility
|
||||
|
||||
## Sound System Design
|
||||
|
||||
### Sound Events
|
||||
- **startup**: Application started
|
||||
- **shutdown**: Application closing
|
||||
- **private_message**: Direct message received
|
||||
- **mention**: User mentioned in post
|
||||
- **boost**: Post boosted/reblogged
|
||||
- **reply**: Reply to user's post
|
||||
- **post_sent**: User successfully posted
|
||||
- **timeline_update**: New posts in timeline
|
||||
- **notification**: General notification
|
||||
- **expand**: Thread expanded
|
||||
- **collapse**: Thread collapsed
|
||||
- **success**: General success feedback
|
||||
- **error**: Error occurred
|
||||
|
||||
### Sound Pack Structure
|
||||
**pack.json Format:**
|
||||
```json
|
||||
{
|
||||
"name": "Pack Display Name",
|
||||
"description": "Pack description",
|
||||
"author": "Creator name",
|
||||
"version": "1.0",
|
||||
"sounds": {
|
||||
"private_message": "filename.wav",
|
||||
"mention": "filename.wav",
|
||||
"boost": "filename.wav",
|
||||
"reply": "filename.wav",
|
||||
"post_sent": "filename.wav",
|
||||
"timeline_update": "filename.wav",
|
||||
"notification": "filename.wav"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### SoundManager Features
|
||||
- simpleaudio for cross-platform WAV playback with volume control
|
||||
- Subprocess fallback (sox/play on Linux, afplay on macOS, PowerShell on Windows)
|
||||
- Fallback to default pack if sound missing
|
||||
- Master volume and notification volume controls
|
||||
- Enable/disable per event
|
||||
- Pack discovery and validation
|
||||
- Smart threading (direct calls for simpleaudio, threaded for subprocess)
|
||||
|
||||
## ActivityPub Implementation
|
||||
|
||||
### Core Client Features
|
||||
- **Timeline Streaming**: Real-time updates via WebSocket/polling
|
||||
- **Post Composition**: Text, media attachments, visibility settings
|
||||
- **Thread Resolution**: Fetch complete conversation trees
|
||||
- **User Profiles**: Following, followers, profile viewing
|
||||
- **Notifications**: Mentions, boosts, follows, favorites
|
||||
|
||||
### Server Compatibility
|
||||
**Primary Targets:**
|
||||
- Pleroma: Full feature support
|
||||
- GoToSocial: Full feature support
|
||||
|
||||
**Extended Support:**
|
||||
- Mastodon: Best effort compatibility
|
||||
- Other ActivityPub servers: Basic functionality
|
||||
|
||||
### API Endpoints Usage
|
||||
- `/api/v1/timelines/home` - Home timeline
|
||||
- `/api/v1/statuses` - Post creation
|
||||
- `/api/v1/statuses/:id/context` - Thread fetching
|
||||
- `/api/v1/streaming` - Real-time updates
|
||||
- `/api/v1/notifications` - Notification management
|
||||
|
||||
## User Interface Design
|
||||
|
||||
### Main Window Layout
|
||||
```
|
||||
[Menu Bar]
|
||||
[Instance/Account Selector]
|
||||
[Timeline Tree View - Main Focus]
|
||||
[Compose Box]
|
||||
[Status Bar]
|
||||
```
|
||||
|
||||
### Key UI Components
|
||||
- **Timeline View**: AccessibleTreeWidget showing posts and threads
|
||||
- **Compose Dialog**: Modal for creating posts with accessibility
|
||||
- **Settings Dialog**: Sound pack selection, accessibility options
|
||||
- **Login Dialog**: Instance selection and authentication
|
||||
|
||||
### Keyboard Shortcuts
|
||||
- **Ctrl+N**: New post
|
||||
- **Ctrl+R**: Reply to selected post
|
||||
- **Ctrl+B**: Boost selected post
|
||||
- **Ctrl+F**: Favorite selected post
|
||||
- **F5**: Refresh timeline
|
||||
- **Ctrl+,**: Settings
|
||||
- **Escape**: Close dialogs
|
||||
|
||||
## Development Phases
|
||||
|
||||
### Phase 1: Foundation
|
||||
1. Project structure setup
|
||||
2. XDG configuration system
|
||||
3. Basic PySide6 window with accessibility
|
||||
4. AccessibleTreeWidget implementation
|
||||
5. Sound system foundation
|
||||
|
||||
### Phase 2: ActivityPub Core
|
||||
1. Basic HTTP client
|
||||
2. Authentication (OAuth2)
|
||||
3. Timeline fetching and display
|
||||
4. Post composition and sending
|
||||
5. Basic thread display
|
||||
|
||||
### Phase 3: Advanced Features
|
||||
1. Thread expansion/collapse
|
||||
2. Real-time updates
|
||||
3. Notifications system
|
||||
4. Sound pack system
|
||||
5. Settings interface
|
||||
|
||||
### Phase 4: Polish
|
||||
1. Comprehensive accessibility testing
|
||||
2. Screen reader testing (Orca, NVDA, JAWS)
|
||||
3. Performance optimization
|
||||
4. Error handling
|
||||
5. Documentation
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Accessibility Testing
|
||||
- Automated testing with screen reader APIs
|
||||
- Manual testing with Orca, NVDA (via Wine)
|
||||
- Keyboard-only navigation testing
|
||||
- Focus management verification
|
||||
|
||||
### Functional Testing
|
||||
- ActivityPub protocol compliance
|
||||
- Thread navigation accuracy
|
||||
- Sound system reliability
|
||||
- Configuration persistence
|
||||
|
||||
### Test Instances
|
||||
- Pleroma test server
|
||||
- GoToSocial test server
|
||||
- Mock ActivityPub server for edge cases
|
||||
|
||||
## Configuration Management
|
||||
|
||||
### Settings Structure
|
||||
```ini
|
||||
[general]
|
||||
instance_url = https://example.social
|
||||
username = user
|
||||
timeline_refresh_interval = 60
|
||||
|
||||
[audio]
|
||||
sound_pack = Doom
|
||||
master_volume = 100
|
||||
notification_volume = 100
|
||||
|
||||
[sounds]
|
||||
private_message_enabled = true
|
||||
private_message_volume = 0.8
|
||||
mention_enabled = true
|
||||
mention_volume = 1.0
|
||||
# ... other sound settings
|
||||
|
||||
[accessibility]
|
||||
announce_thread_state = true
|
||||
auto_expand_mentions = false
|
||||
keyboard_navigation_wrap = true
|
||||
```
|
||||
|
||||
### Account Storage
|
||||
- Secure credential storage
|
||||
- Multiple account support
|
||||
- Instance-specific settings
|
||||
|
||||
## Known Challenges and Solutions
|
||||
|
||||
### ActivityPub Complexity
|
||||
- **Challenge**: Different server implementations vary
|
||||
- **Solution**: Modular client design with server-specific adapters
|
||||
|
||||
### Screen Reader Performance
|
||||
- **Challenge**: Large timelines may impact performance
|
||||
- **Solution**: Virtual scrolling, lazy loading, efficient tree models
|
||||
|
||||
### Thread Visualization
|
||||
- **Challenge**: Complex thread structures hard to navigate
|
||||
- **Solution**: Clear indentation, status announcements, skip collapsed
|
||||
|
||||
### Sound Customization
|
||||
- **Challenge**: Users want different audio feedback
|
||||
- **Solution**: Comprehensive sound pack system with easy installation
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Advanced Features
|
||||
- Custom timeline filters
|
||||
- Multiple column support
|
||||
- Direct message interface
|
||||
- List management
|
||||
- Advanced search
|
||||
|
||||
### Accessibility Extensions
|
||||
- Braille display optimization
|
||||
- Voice control integration
|
||||
- High contrast themes
|
||||
- Font size scaling
|
||||
|
||||
### Federation Features
|
||||
- Cross-instance thread following
|
||||
- Server switching
|
||||
- Federation status monitoring
|
||||
- Custom emoji support
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Core Requirements
|
||||
```
|
||||
PySide6>=6.0.0
|
||||
requests>=2.25.0
|
||||
simpleaudio>=1.0.4
|
||||
numpy
|
||||
configparser
|
||||
pathlib
|
||||
```
|
||||
|
||||
### Optional Dependencies
|
||||
```
|
||||
pytest (testing)
|
||||
coverage (test coverage)
|
||||
black (code formatting)
|
||||
mypy (type checking)
|
||||
```
|
||||
|
||||
## Installation and Distribution
|
||||
|
||||
### Development Setup
|
||||
```bash
|
||||
git clone <repository>
|
||||
cd bifrost
|
||||
pip install -r requirements.txt
|
||||
# Run with proper display
|
||||
DISPLAY=:0 ./bifrost.py
|
||||
# Or
|
||||
python bifrost.py
|
||||
```
|
||||
|
||||
### Packaging
|
||||
- Python wheel distribution
|
||||
- AppImage for Linux
|
||||
- Consideration for distro packages
|
||||
|
||||
## Accessibility Compliance
|
||||
|
||||
### Standards Adherence
|
||||
- WCAG 2.1 AA compliance
|
||||
- Qt Accessibility framework usage
|
||||
- AT-SPI2 protocol support (Linux)
|
||||
- Platform accessibility APIs
|
||||
|
||||
### Screen Reader Testing Matrix
|
||||
- **Orca** (Linux): Primary target
|
||||
- **NVDA** (Windows via Wine): Secondary
|
||||
- **JAWS** (Windows via Wine): Basic compatibility
|
||||
- **VoiceOver** (macOS): Future consideration
|
||||
|
||||
This document serves as the comprehensive development guide for Bifrost, ensuring all accessibility, functionality, and architectural decisions are preserved and can be referenced throughout development.
|
||||
Reference in New Issue
Block a user