bitchat/TECH_DEBT_PLAN.md

Bitchat Technical Debt Remediation Plan

Overview

This document outlines the technical debt in the bitchat project and provides a prioritized plan for addressing it.

Priority 1: Critical Security & Stability (1-2 weeks)

1.1 Thread Safety Issues

Problem: Potential race conditions in message processing and peer management Solution:

• Audit all concurrent access to shared state
• Add proper synchronization to message queues
• Use actor pattern for BluetoothMeshService
• Add thread sanitizer to debug builds

1.2 Error Handling

Problem: Many errors are silently logged without proper recovery Solution:

• Implement proper error propagation
• Add user-visible error states
• Create recovery mechanisms for common failures
• Add crash reporting for TestFlight

1.3 Memory Management

Problem: Fragment cleanup could leak memory, no proper cleanup on errors Solution:

• Add fragment timeout cleanup
• Implement proper weak references in closures
• Add memory pressure handling
• Profile with Instruments

Priority 2: Code Quality & Maintainability (2-3 weeks)

2.1 Service Refactoring

Problem: BluetoothMeshService is 1600+ lines, doing too much Solution:

• Extract message handling into MessageProcessor
• Extract peer management into PeerManager
• Extract fragment handling into FragmentManager
• Create proper dependency injection

2.2 Testing Infrastructure

Problem: No unit tests, making refactoring risky Solution:

• Add XCTest target
• Create mock implementations for Bluetooth
• Test encryption service thoroughly
• Add integration tests for message flow
• Aim for 70% code coverage

2.3 Documentation

Problem: Limited code comments, no architecture docs Solution:

• Add comprehensive header comments
• Document protocol specifications
• Create architecture diagrams
• Add inline documentation for complex logic

Priority 3: Performance & UX (3-4 weeks)

3.1 Message Deduplication

Problem: Simple Set-based deduplication can grow unbounded Solution:

• Implement LRU cache for message IDs
• Add time-based expiration
• Consider bloom filters for efficiency

3.2 Connection Management

Problem: No connection pooling or retry logic Solution:

• Implement connection state machine
• Add exponential backoff for retries
• Pool peripheral connections
• Add connection quality metrics

3.3 UI Responsiveness

Problem: Heavy operations on main thread Solution:

• Move encryption to background queues
• Add loading states for operations
• Implement message pagination
• Add pull-to-refresh

Priority 4: Feature Enhancements (4-6 weeks)

4.1 Message Persistence (Optional)

Problem: All messages ephemeral, no history Solution:

• Add encrypted SQLite storage
• Implement configurable retention
• Add search functionality
• Maintain privacy-first approach

4.2 Protocol Improvements

Problem: No versioning, hard to upgrade Solution:

• Add protocol version negotiation
• Implement capability discovery
• Plan migration strategy
• Add feature flags

4.3 Network Visualization

Problem: Users don't understand mesh topology Solution:

• Add network graph view
• Show message routing paths
• Display peer connection quality
• Add statistics dashboard

Implementation Strategy

Phase 1: Foundation (Weeks 1-2)

1. Set up testing infrastructure
2. Add thread sanitizer and memory profiler
3. Begin service refactoring
4. Fix critical thread safety issues

Phase 2: Stability (Weeks 3-4)

1. Complete service refactoring
2. Add comprehensive error handling
3. Implement proper memory management
4. Add initial test coverage

Phase 3: Quality (Weeks 5-6)

1. Add documentation
2. Improve connection management
3. Optimize performance bottlenecks
4. Enhance UI responsiveness

Phase 4: Enhancement (Weeks 7-10)

1. Add optional persistence
2. Implement protocol versioning
3. Build network visualization
4. Polish for production

Success Metrics

• Zero crashes in TestFlight
• 70% test coverage
• Sub-100ms message processing
• < 5% battery drain per hour
• Clean architecture with < 300 lines per class

Risk Mitigation

• Keep all changes backwards compatible initially
• Add feature flags for risky changes
• Extensive TestFlight testing between phases
• Maintain current security properties
• Regular security audits of changes