bifrost/CLAUDE.md

# 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.