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:

{
  "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 with pagination
• Timeline Tabs: Home, Mentions, Local, Federated timeline switching
• Compose Dialog: Modal for creating posts with accessibility
• Settings Dialog: Sound pack, desktop notifications, accessibility options
• Login Dialog: Instance selection and authentication
• URL Selection Dialog: Choose from multiple URLs in posts
• Context Menu: Copy, URL opening, reply, boost, favorite actions

Keyboard Shortcuts

• Ctrl+N: New post
• Ctrl+R: Reply to selected post
• Ctrl+B: Boost selected post
• Ctrl+F: Favorite selected post
• Ctrl+C: Copy selected post to clipboard
• Ctrl+U: Open URLs from selected post in browser
• 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

[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

[notifications]
enabled = true
direct_messages = true
mentions = true
boosts = false
favorites = false
follows = true
timeline_updates = false

[timeline]
posts_per_page = 40

[accessibility]
announce_thread_state = true
auto_expand_mentions = false
keyboard_navigation_wrap = true
page_step_size = 5
verbose_announcements = 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

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.